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

package/runtime/knowledge/docs/ui/components/atoms/vc-hint/vc-hint.docs.md

@@ -145,7 +145,7 @@ Show helper text by default, but swap to an error message when validation fails:
 ## Architecture notes
 
 - VcHint is a single `<div>` element — no wrapper. `role="alert"` is toggled reactively via `:role` binding when `error` prop changes.
-- CSS variables are scoped with `.vc-hint` selector in `vc-hint.vue` `<style scoped>`.
+- The `--hint-*` CSS variables are declared globally on `:root` (not scoped to `.vc-hint`); the component's `<style lang="scss">` block is not scoped.
 - Source: `framework/ui/components/atoms/vc-hint/vc-hint.vue`
 
 <!-- internal:end -->

package/runtime/knowledge/docs/ui/components/atoms/vc-icon/vc-icon.docs.md

@@ -25,14 +25,15 @@ A unified icon component that renders icons from multiple libraries. Lucide Icon
 
 ## Key Props
 
-| Prop         | Type                                                   | Default           | Description                              |
-| ------------ | ------------------------------------------------------ | ----------------- | ---------------------------------------- |
-| `icon`       | `string \| Component`                                  | `"lucide-square"` | Icon identifier or Vue component         |
-| `size`       | `"xs" \| "s" \| "m" \| "l" \| "xl" \| "xxl" \| "xxxl"` | `"m"`             | Predefined size                          |
-| `variant`    | `"warning" \| "danger" \| "success"`                   | —                 | Semantic color variant                   |
-| `customSize` | `number`                                               | —                 | Custom size in pixels (overrides `size`) |
-| `ariaLabel`  | `string`                                               | —                 | Accessible label for meaningful icons    |
-| `basePath`   | `string`                                               | `"/assets/icons"` | Base path for SVG sprite icons           |
+| Prop           | Type                                                   | Default           | Description                                                                                                                                            |
+| -------------- | ------------------------------------------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `icon`         | `string \| Component`                                  | `"lucide-square"` | Icon identifier or Vue component                                                                                                                       |
+| `size`         | `"xs" \| "s" \| "m" \| "l" \| "xl" \| "xxl" \| "xxxl"` | `"m"`             | Predefined size                                                                                                                                        |
+| `variant`      | `"warning" \| "danger" \| "success"`                   | —                 | Semantic color variant                                                                                                                                 |
+| `customSize`   | `number`                                               | —                 | Custom size in pixels (overrides `size`)                                                                                                               |
+| `ariaLabel`    | `string`                                               | —                 | Accessible label for meaningful icons                                                                                                                  |
+| `basePath`     | `string`                                               | `"/assets/icons"` | Base path for SVG sprite icons                                                                                                                         |
+| `useContainer` | `boolean`                                              | `false`           | Deprecated. Wraps the icon in a fixed-size container; removed in a future version (logs a dev warning). Remove it — icons render correctly without it. |
 
 ::storybook id="layout-vcicon--all-sizes" height="300"
 
@@ -127,6 +128,6 @@ import MyCustomIcon from "./MyCustomIcon.vue";
 - Icon resolution is handled by a switch on the string prefix: `lucide-` maps to the Lucide component registry; `fa-` / `fas fa-` / `bi-` / `material-` are legacy paths kept for backward compatibility and will be removed in v3.
 - The `svg:` prefix loads from an SVG sprite at `basePath` (default `/assets/icons`) using a `<use>` element. Sprite must be included in the app's static assets.
 - `customSize` takes a number and sets `width`/`height` inline; it overrides the `size` prop class entirely.
-- Color variants (`warning`, `danger`, `success`) apply CSS custom property overrides (`--icon-color`) rather than inline style to allow theme-level customization.
+- Color variants (`warning`, `danger`, `success`) resolve to the per-variant CSS custom properties `--icon-color-{success|danger|warning}`. Prefix/registry icons pick these up via variant CSS classes; custom Vue-component icons receive the color inline as `color: var(--icon-color-${variant})`.
 
 <!-- internal:end -->

package/runtime/knowledge/docs/ui/components/atoms/vc-image/vc-image.docs.md

@@ -35,9 +35,15 @@ An image display component with predefined sizes, aspect ratio control, and a pl
 | `bordered`      | `boolean`                                                       | `false`          | Adds a subtle border                                                                                                                               |
 | `clickable`     | `boolean`                                                       | `false`          | Makes the image interactive with cursor and click event                                                                                            |
 | `emptyIcon`     | `string`                                                        | `"lucide-image"` | Icon shown when `src` is empty                                                                                                                     |
-| `alt`           | `string`                                                        | —                | Accessible alt text                                                                                                                                |
+| `alt`           | `string`                                                        | —                | Accessible alt text. Required to expose `role="img"`; without it the image is decorative                                                           |
 | `thumbnailSize` | `ThumbnailSize`                                                 | —                | Load a thumbnail variant instead of full-size image. Values: `"sm"`, `"md"`, `"lg"`, `"64x64"`, `"128x128"`, `"168x168"`, `"216x216"`, `"348x348"` |
 
+## Events
+
+| Event   | Payload | Description                                                 |
+| ------- | ------- | ----------------------------------------------------------- |
+| `click` | —       | Emitted on click/Enter/Space, only when `clickable` is true |
+
 ::storybook id="data-display-vcimage--size-variants" height="300"
 
 ## Size Reference
@@ -53,6 +59,15 @@ An image display component with predefined sizes, aspect ratio control, and a pl
 | `xxl`  | 145px          |
 | `auto` | 100% of parent |
 
+## CSS Custom Properties
+
+| Variable                   | Default               | Description                     |
+| -------------------------- | --------------------- | ------------------------------- |
+| `--image-border-radius`    | `6px`                 | Corner radius when `bordered`   |
+| `--image-border-color`     | `var(--neutrals-200)` | Border color when `bordered`    |
+| `--image-empty-icon-color` | `var(--neutrals-400)` | Placeholder icon color          |
+| `--image-focus-ring-color` | `var(--primary-300)`  | Focus ring color when clickable |
+
 ## Common Patterns
 
 ### Product Thumbnail in a List
@@ -87,7 +102,7 @@ An image display component with predefined sizes, aspect ratio control, and a pl
 
 ## Accessibility
 
-- When `src` is present and no `clickable`, the container has `role="img"` with `aria-label` from `alt`
+- When `src` **and** `alt` are present and not `clickable`, the container has `role="img"` with `aria-label` from `alt`. Without `alt` the image is treated as decorative (no `role`), since `role="img"` requires an accessible name.
 - Clickable images receive `role="button"`, `tabindex="0"`, and keyboard support (Enter/Space)
 - Empty placeholder icon is marked `aria-hidden="true"`
 - Focus ring appears on `:focus-visible` for clickable images
@@ -107,8 +122,8 @@ When displaying images in lists or grids, pass a `thumbnailSize` (e.g. `"128x128
 
 - VcImage lives in `framework/ui/components/atoms/vc-image/`.
 - Images are rendered as CSS `background-image` on a `<div>` rather than an `<img>` tag; this enables `background-size: cover/contain` and preserves aspect-ratio without JS.
-- HTTPS enforcement: the `src` watcher rewrites `http://` to `https://` when `window.location.protocol === 'https:'`.
-- `thumbnailSize` appends a query parameter to the URL compatible with Virto Commerce image proxy: `?size=128x128`. This is a platform-specific convention.
+- HTTPS enforcement: the `ensureHttps()` helper (called from the `imageHandler` computed and the thumbnail-probe watcher) upgrades `http://` to `https://` when `window.location.protocol === 'https:'`.
+- `thumbnailSize` inserts a size suffix before the file extension, compatible with the Virto Commerce thumbnail convention: `photo.jpg` becomes `photo_128x128.jpg`. This is a platform-specific convention.
 - Aspect ratios are implemented as Tailwind aspect-ratio utility classes (`tw-aspect-square`, `tw-aspect-video`, etc.).
 - Clickable mode adds `role="button"` and forwards keyboard Enter/Space to the click handler, consistent with other atom-level interactive components.
 

package/runtime/knowledge/docs/ui/components/atoms/vc-label/vc-label.docs.md

@@ -167,9 +167,9 @@ Use a different icon for the tooltip trigger:
 ## Architecture notes
 
 - VcLabel lives in `framework/ui/components/atoms/vc-label/`.
-- The element type (`<label>` vs `<div>`) is determined by a computed `tag` that checks whether `htmlFor` is a non-empty string.
+- The root element type (`<label>` vs `<div>`) is chosen inline via `:is="htmlFor ? 'label' : 'div'"` on the root `<component>` (no `tag` computed exists).
 - The tooltip trigger is rendered by `VcTooltip` (internal molecule); the `tooltipIcon` prop simply passes through to an inner `VcIcon` instance.
-- `multilanguage` + `currentLanguage` render a small pill via an inline `<span>` with `.vc-label__lang` class — not a separate component.
+- `multilanguage` + `currentLanguage` render a small pill via an inline `<div>` with `.vc-label__language` class — not a separate component.
 - VcLabel is the canonical label primitive consumed by `VcInput`, `VcSelect`, `VcTextarea`, `VcCheckbox`, and `VcRadioButton` in `framework/ui/components/molecules/`.
 
 <!-- internal:end -->

package/runtime/knowledge/docs/ui/components/atoms/vc-link/vc-link.docs.md

@@ -35,10 +35,11 @@ function openDetails() {
 
 ## Key Props
 
-| Prop       | Type      | Default | Description                                    |
-| ---------- | --------- | ------- | ---------------------------------------------- |
-| `active`   | `boolean` | `false` | Highlights the link as currently selected      |
-| `disabled` | `boolean` | `false` | Prevents interaction and applies muted styling |
+| Prop       | Type         | Default | Description                                                                     |
+| ---------- | ------------ | ------- | ------------------------------------------------------------------------------- |
+| `active`   | `boolean`    | `false` | Highlights the link as currently selected                                       |
+| `disabled` | `boolean`    | `false` | Prevents interaction and applies muted styling                                  |
+| `onClick`  | `() => void` | --      | Declared prop, currently unused by the template (use the `click` event instead) |
 
 ## Events
 

package/runtime/knowledge/docs/ui/components/atoms/vc-loading/vc-loading.docs.md

@@ -52,7 +52,8 @@ const isLoading = ref(true);
 | `--loading-overlay-bg` | `rgba(255,255,255,0.6)` | Overlay background color      |
 | `--loading-bar-width`  | `140px`                 | Width of the progress bar     |
 | `--loading-bar-height` | `4px`                   | Height of the progress bar    |
-| `--loading-z-index`    | `9998`                  | Z-index of the overlay layer  |
+
+> **Note:** The overlay z-index comes from the global `--z-critical-loading` token and is not overridable per-instance.
 
 ::storybook id="layout-vcloading--interactive"
 
@@ -117,7 +118,7 @@ Override the bar color to match a specific status or brand theme:
 
 ## Tips
 
-- VcLoading is hidden with `display: none` when inactive, so it adds zero layout cost when idle.
+- VcLoading is hidden via the `tw-hidden` class when inactive, so it adds zero layout cost when idle.
 - The sweep animation runs on a 1.5-second infinite loop using CSS `@keyframes` — no JavaScript timers involved.
 - The overlay applies `backdrop-filter: blur(3px)` for a frosted-glass effect. If you need a fully opaque overlay, set `--loading-overlay-bg: rgba(255,255,255,1)`.
 - When using inside a scrollable container, the overlay covers only the visible viewport of that container because it is absolutely positioned.
@@ -138,8 +139,8 @@ Override the bar color to match a specific status or brand theme:
 
 ## Architecture notes
 
-- The overlay is a single `<div>` with `v-show` (not `v-if`) so it remains in the DOM and retains animation state. `display: none` from `v-show` removes it from the paint tree when inactive.
-- The sweeping bar is a child `<div>` animated via `@keyframes vc-loading-sweep` (translateX from `-100%` to `100%`).
+- The overlay is a single `<div>` always rendered in the DOM; visibility is toggled via the `vc-loading-overlay--active` class (base state is `tw-hidden`), so it retains animation state when inactive.
+- The sweeping bar is a child `<div>` animated via `@keyframes vc-bar-sweep`, animating the `left` property from `-40%` to `100%`.
 - `backdrop-filter: blur(3px)` is applied to the overlay div directly; older Safari requires `-webkit-backdrop-filter` as a fallback.
 - Source: `framework/ui/components/atoms/vc-loading/vc-loading.vue`
 

package/runtime/knowledge/docs/ui/components/atoms/vc-progress/vc-progress.docs.md

@@ -148,13 +148,14 @@ async function handleUpload(files: FileList) {
 
 ## CSS Custom Properties
 
-| Variable                         | Default               | Description                |
-| -------------------------------- | --------------------- | -------------------------- |
-| `--progressbar-height`           | `8px`                 | Bar height                 |
-| `--progressbar-border-radius`    | `9999px`              | Border radius (pill shape) |
-| `--progressbar-background-color` | `var(--neutrals-200)` | Track background           |
-| `--progressbar-foreground-color` | `var(--primary-500)`  | Fill color                 |
-| `--progressbar-striped-bg`       | gradient              | Striped variant background |
+| Variable                         | Default               | Description                  |
+| -------------------------------- | --------------------- | ---------------------------- |
+| `--progressbar-height`           | `8px`                 | Bar height                   |
+| `--progressbar-border-radius`    | `9999px`              | Border radius (pill shape)   |
+| `--progressbar-background-color` | `var(--neutrals-200)` | Track background             |
+| `--progressbar-foreground-color` | `var(--primary-500)`  | Fill color                   |
+| `--progressbar-striped-bg`       | gradient              | Striped variant background   |
+| `--progressbar-striped-color`    | `var(--primary-400)`  | Striped variant stripe color |
 
 ## Tips
 
@@ -179,7 +180,7 @@ async function handleUpload(files: FileList) {
 
 ## Architecture notes
 
-- The fill width is driven by `transform: scaleX(value / 100)` with `transform-origin: left`, not `width`, for smoother GPU-accelerated animation.
+- The fill is a full-width (`width: 100%`) element translated horizontally via `transform: translateX(-(100 - value)%)`, not `width`, for smoother GPU-accelerated animation. There is no `scaleX` or `transform-origin: left`.
 - The `value` prop is clamped via `Math.min(100, Math.max(0, props.value))` in a computed.
 - Source: `framework/ui/components/atoms/vc-progress/vc-progress.vue`
 

package/runtime/knowledge/docs/ui/components/atoms/vc-scrollable-container/vc-scrollable-container.docs.md

@@ -128,6 +128,13 @@ Replace the default chevrons with custom indicators:
 </VcScrollableContainer>
 ```
 
+## CSS Custom Properties
+
+| Variable               | Default               | Description           |
+| ---------------------- | --------------------- | --------------------- |
+| `--scroll-arrow-size`  | `16px`                | Arrow indicator size  |
+| `--scroll-arrow-color` | `var(--neutrals-400)` | Arrow indicator color |
+
 ## Tips
 
 - The `speed` prop is captured once at mount time and is not reactive. If you need to change speed dynamically, remount the component with a `:key` binding.

package/runtime/knowledge/docs/ui/components/atoms/vc-skeleton/vc-skeleton.docs.md

@@ -136,7 +136,7 @@ The last row automatically renders at 60% width for a natural paragraph feel.
 
 ## Architecture notes
 
-- The `text` variant uses an `Array(rows).fill(0)` to render `<span>` elements via `v-for`. The last row gets a `width: 60%` inline style for a natural paragraph taper.
+- The `text` variant renders rows via `v-for="index in rows"` over `<div class="vc-skeleton__row">` elements. `getRowWidth(index)` returns `60%` for the last row (inline style) for a natural paragraph taper.
 - Animation uses a CSS `@keyframes` pulse (opacity oscillation), not a moving shimmer, for simplicity and performance.
 - Source: `framework/ui/components/atoms/vc-skeleton/vc-skeleton.vue`
 

package/runtime/knowledge/docs/ui/components/atoms/vc-status/vc-status.docs.md

@@ -131,8 +131,8 @@ Each variant has its own set of CSS variables following the pattern `--status-{v
 
 ## Architecture notes
 
-- The `extend` prop switches a CSS class; all color theming is done via `--status-{variant}-*` CSS variables scoped under `.vc-status`.
-- Special variants `"light-danger"`, `"info-dark"`, and `"primary"` are kept for backward compatibility and mapped via a `variantClassMap` in `vc-status.vue`.
+- The `extend` prop toggles the `vc-status--extended` modifier class; all color theming is done via `--status-{variant}-*` CSS variables scoped under `.vc-status`.
+- Each variant is bound directly as `vc-status--${variant}` and styled through a SCSS `@each $variant in $variants` loop; the special variants `"light-danger"`, `"info-dark"`, and `"primary"` are kept for backward compatibility.
 - Source: `framework/ui/components/atoms/vc-status/vc-status.vue`
 
 <!-- internal:end -->

package/runtime/knowledge/docs/ui/components/atoms/vc-status-icon/vc-status-icon.docs.md

@@ -167,7 +167,7 @@ VcStatusIcon is intentionally minimal. If you need a text label next to the icon
 
 ## Architecture notes
 
-- VcStatusIcon wraps two `VcIcon` instances in a single `<span>` with `v-if`/`v-else` switching on the `status` prop.
+- VcStatusIcon wraps two `VcIcon` instances in a single `<div class="vc-status-icon">` with `v-if`/`v-else` switching on the `status` prop.
 - Icon size inherits from parent font-size; no dedicated size prop is exposed.
 - Source: `framework/ui/components/atoms/vc-status-icon/vc-status-icon.vue`
 

package/runtime/knowledge/docs/ui/components/atoms/vc-tooltip/vc-tooltip.docs.md

@@ -6,7 +6,7 @@ group: feedback
 
 # VcTooltip
 
-A floating tooltip that appears on hover or focus to provide contextual information about a trigger element. Powered by Floating UI for automatic positioning, collision detection, and arrow alignment. The tooltip is teleported to the document body for proper stacking above all content.
+A floating tooltip that appears on hover or focus to provide contextual information about a trigger element. Powered by Floating UI for automatic positioning, collision detection, and arrow alignment. The tooltip is teleported to the vc-app root element (falling back to `document.body`) for proper stacking above all content.
 
 ## Quick Start
 
@@ -248,13 +248,13 @@ const actions = [
   </template>
 </VcTooltip>
 
-<!-- Correct -- use a popover or dropdown for interactive content -->
-<VcPopover>
+<!-- Correct -- use a popover or dropdown component for interactive content -->
+<YourPopover>
   <span>Click for help</span>
   <template #content>
     <a href="/docs">Read the documentation</a>
   </template>
-</VcPopover>
+</YourPopover>
 ```
 
 ### Forgetting the #tooltip slot
@@ -324,7 +324,8 @@ const actions = [
 | `--tooltip-font-size`     | `12px`                 | Text size                  |
 | `--tooltip-padding-x`     | `10px`                 | Horizontal padding         |
 | `--tooltip-padding-y`     | `6px`                  | Vertical padding           |
-| `--tooltip-z-index`       | `1002`                 | Stacking order             |
+
+Stacking order comes from the global `--z-critical-tooltip` token and is not overridable per-instance.
 
 ## Accessibility
 
@@ -332,7 +333,7 @@ const actions = [
 - `aria-describedby` links the trigger to the tooltip when visible
 - Shows on `focusin`, hides on `focusout` for keyboard users
 - Escape key dismisses the tooltip
-- Tooltip is teleported to the document body for proper stacking context
+- Tooltip is teleported to the vc-app root element (falling back to `document.body`) for proper stacking context
 - Fade transition (150ms in, 100ms out) provides smooth visual feedback
 - The tooltip has `pointer-events: none` -- it cannot be interacted with directly
 
@@ -347,10 +348,10 @@ const actions = [
 ## Architecture notes
 
 - VcTooltip uses `@floating-ui/vue` (`useFloating`, `autoUpdate`, `flip`, `shift`, `arrow`, `offset` middleware).
-- The tooltip content is teleported to `<body>` via Vue's `<Teleport>` to escape stacking contexts.
-- Show/hide state is managed with a single `isVisible` ref toggled by `mouseenter`/`mouseleave` and `focusin`/`focusout` on the trigger slot wrapper.
-- The delay timer is stored in a `timeoutId` ref and cleared on `mouseleave` to cancel pending show.
-- Arrow positioning is handled by the `arrowEl` template ref passed to the `arrow` middleware; position is applied via `:style` on the arrow element.
+- The tooltip content is teleported via Vue's `<Teleport>` to escape stacking contexts. The target is resolved by `useTeleportTarget()` with priority explicit target -> vc-app root element (`AppRootElementKey`) -> `<body>` fallback.
+- Show/hide state is managed with a single `tooltipVisible` ref toggled by `mouseenter`/`mouseleave` and `focusin`/`focusout` on the trigger slot wrapper.
+- The delay timer is stored in a `showTimeout` variable (not a ref) and cleared in `hideTooltip`/`onBeforeUnmount` to cancel a pending show.
+- Arrow positioning is handled by the `arrowRef` template ref passed to the `arrow` middleware; position is applied via `:style` on the arrow element.
 - Source: `framework/ui/components/atoms/vc-tooltip/vc-tooltip.vue`
 
 <!-- internal:end -->

package/runtime/knowledge/docs/ui/components/atoms/vc-video/vc-video.docs.md

@@ -34,14 +34,21 @@ import { VcVideo } from "@vc-shell/framework";
 
 ## Key Props
 
-| Prop      | Type     | Default | Description                                        |
-| --------- | -------- | ------- | -------------------------------------------------- |
-| `source`  | `string` | --      | Embed URL for the video (e.g., YouTube embed link) |
-| `label`   | `string` | --      | Label text displayed above the video               |
-| `tooltip` | `string` | --      | Tooltip text shown on the label's info icon        |
+| Prop                | Type     | Default | Description                                                                            |
+| ------------------- | -------- | ------- | -------------------------------------------------------------------------------------- |
+| `source`            | `string` | --      | Embed URL for the video (e.g., YouTube embed link)                                     |
+| `label`             | `string` | --      | Label text displayed above the video                                                   |
+| `tooltip`           | `string` | --      | Tooltip text shown on the label's info icon                                            |
+| `additionalSandbox` | `string` | --      | Extra space-separated iframe sandbox tokens appended to the secure default (see below) |
 
 ::storybook id="data-display-vcvideo--with-tooltip" height="400"
 
+## Events
+
+| Event   | Payload | Description                                                  |
+| ------- | ------- | ------------------------------------------------------------ |
+| `click` | --      | Declared public emit. Currently the template never fires it. |
+
 ## Common Patterns
 
 ### Video with Label and Tooltip
@@ -110,17 +117,30 @@ When `source` is not provided, VcVideo renders a centered film icon placeholder
 
 - Always use the **embed** URL format, not the standard watch URL. For YouTube, use `https://www.youtube.com/embed/VIDEO_ID` instead of `https://www.youtube.com/watch?v=VIDEO_ID`.
 - The iframe has `loading="lazy"`, so videos below the fold are not loaded until the user scrolls to them. This keeps initial page load fast.
-- The `sandbox` attribute restricts iframe capabilities to `allow-scripts allow-same-origin allow-presentation allow-popups` for security. If your video host requires additional permissions, you may need a custom wrapper.
+- The `sandbox` attribute defaults to the secure minimum `allow-scripts allow-presentation`. If your video host requires more, append tokens via `additionalSandbox` — see the Security section below.
+- The iframe sets a fixed `allow` permissions policy (`accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture`) plus `allowfullscreen`, so embedded players can autoplay, go fullscreen, and use picture-in-picture. These are not configurable per-instance.
 - The iframe renders at a fixed height of 300px. To customize the height, override the iframe styles via a scoped CSS rule targeting `.vc-video__container iframe`.
 - The placeholder has a height of 200px so the layout does not collapse when no source is provided.
 
 ## Accessibility
 
 - The iframe uses the `title` attribute (set to `label` or "Video") for screen readers
-- `sandbox` attribute restricts iframe capabilities to `allow-scripts allow-same-origin allow-presentation allow-popups`
+- `sandbox` attribute defaults to the secure minimum `allow-scripts allow-presentation`
 - `loading="lazy"` defers iframe load until visible
 - Placeholder state uses `role="img"` with `aria-label="No video source"`
 
+## Security
+
+The iframe `sandbox` defaults to `allow-scripts allow-presentation` — the minimum that keeps mainstream embeds (YouTube, Vimeo) working while denying the framed page access to the parent origin. To add capabilities a specific host needs, pass them through `additionalSandbox`:
+
+```vue
+<!-- Some embeds need popups for auth flows -->
+<VcVideo source="https://example.com/embed" additional-sandbox="allow-popups" />
+```
+
+!!! danger "Never combine `allow-same-origin` with `allow-scripts`"
+Per MDN and OWASP, enabling both tokens lets the embedded page remove its own sandbox and reach the parent origin's cookies, `localStorage`, and DOM. `VcVideo` renders whatever `source` you pass, so for untrusted or user-supplied URLs do **not** add `allow-same-origin`.
+
 !!! warning "Always use embed URLs, not watch URLs"
 YouTube watch URLs (`youtube.com/watch?v=...`) will be blocked by the browser's frame policy. Always convert to the embed format (`youtube.com/embed/VIDEO_ID`). Vimeo similarly requires `player.vimeo.com/video/VIDEO_ID`.
 
@@ -136,7 +156,7 @@ YouTube watch URLs (`youtube.com/watch?v=...`) will be blocked by the browser's
 
 - VcVideo lives in `framework/ui/components/atoms/vc-video/`.
 - The component is a thin wrapper around a native `<iframe>` — no custom video controls are implemented.
-- The `sandbox` attribute is hardcoded to `allow-scripts allow-same-origin allow-presentation allow-popups`. Apps that need additional iframe permissions must wrap the component or use a plain `<iframe>`.
+- The `sandbox` attribute is computed from a secure base (`allow-scripts allow-presentation`) plus any `additionalSandbox` tokens, deduped. `allow-same-origin` is intentionally omitted from the default — see the Security section.
 - The label is rendered via `VcLabel` (internal atom) with the `tooltip` prop forwarded as the VcLabel tooltip slot content.
 - Placeholder state (`source` is falsy) swaps the iframe for a `<div>` with `role="img"` containing a `VcIcon` with `lucide-film`.
 

package/runtime/knowledge/docs/ui/components/atoms/vc-widget/vc-widget.docs.md

@@ -42,14 +42,15 @@ function openNotifications() {
 
 ## Key Props
 
-| Prop         | Type               | Default | Description                                                       |
-| ------------ | ------------------ | ------- | ----------------------------------------------------------------- |
-| `icon`       | `string`           | --      | Icon name (Lucide format, e.g., `"lucide-save"`)                  |
-| `title`      | `string`           | --      | Label text below (or beside) the icon                             |
-| `value`      | `string \| number` | --      | Badge count displayed on the icon; numbers above 99 show as "99+" |
-| `disabled`   | `boolean`          | `false` | Prevents clicks and applies muted styling                         |
-| `isExpanded` | `boolean`          | `false` | Expanded visual state                                             |
-| `horizontal` | `boolean`          | `false` | Arranges icon and title side by side instead of stacked           |
+| Prop         | Type               | Default | Description                                                                                                                                                      |
+| ------------ | ------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `icon`       | `string`           | --      | Icon name (Lucide format, e.g., `"lucide-save"`)                                                                                                                 |
+| `title`      | `string`           | --      | Label text below (or beside) the icon                                                                                                                            |
+| `value`      | `string \| number` | --      | Badge count displayed on the icon; numbers above 99 show as "99+"                                                                                                |
+| `disabled`   | `boolean`          | `false` | Prevents clicks and applies muted styling                                                                                                                        |
+| `isExpanded` | `boolean`          | `false` | Expanded visual state                                                                                                                                            |
+| `horizontal` | `boolean`          | `false` | Arranges icon and title side by side instead of stacked                                                                                                          |
+| `widgetId`   | `string`           | --      | Sets the `data-widget-id` attribute on the root element. The root also binds `data-widget-name` from `title`; both are used for widget identification/targeting. |
 
 ## Events
 
@@ -97,16 +98,18 @@ Badge values above 99 are automatically displayed as "99+".
 
 ## CSS Custom Properties
 
-| Variable                     | Default               | Description          |
-| ---------------------------- | --------------------- | -------------------- |
-| `--widget-bg-color`          | `transparent`         | Background color     |
-| `--widget-bg-hover-color`    | `var(--neutrals-50)`  | Background on hover  |
-| `--widget-icon-color`        | `var(--neutrals-700)` | Icon color           |
-| `--widget-icon-hover-color`  | `var(--primary-600)`  | Icon color on hover  |
-| `--widget-title-color`       | `var(--neutrals-600)` | Title text color     |
-| `--widget-title-hover-color` | `var(--primary-600)`  | Title color on hover |
-| `--widget-border-radius`     | `8px`                 | Corner radius        |
-| `--widget-focus-ring-color`  | `var(--primary-300)`  | Focus ring color     |
+| Variable                        | Default               | Description               |
+| ------------------------------- | --------------------- | ------------------------- |
+| `--widget-bg-color`             | `transparent`         | Background color          |
+| `--widget-bg-hover-color`       | `var(--neutrals-50)`  | Background on hover       |
+| `--widget-icon-color`           | `var(--neutrals-700)` | Icon color                |
+| `--widget-icon-hover-color`     | `var(--primary-600)`  | Icon color on hover       |
+| `--widget-icon-disabled-color`  | `var(--neutrals-400)` | Icon color when disabled  |
+| `--widget-title-color`          | `var(--neutrals-600)` | Title text color          |
+| `--widget-title-hover-color`    | `var(--primary-600)`  | Title color on hover      |
+| `--widget-title-disabled-color` | `var(--neutrals-400)` | Title color when disabled |
+| `--widget-border-radius`        | `8px`                 | Corner radius             |
+| `--widget-focus-ring-color`     | `var(--primary-300)`  | Focus ring color          |
 
 ## Accessibility
 
@@ -128,7 +131,7 @@ Badge values above 99 are automatically displayed as "99+".
 ## Architecture notes
 
 - VcWidget lives in `framework/ui/components/atoms/vc-widget/`.
-- The badge overlay is rendered by embedding `VcBadge` with `isDot`/`content` derived from the `value` prop; values above 99 are truncated to `"99+"` in the component template.
+- The badge overlay is rendered by embedding `VcBadge` with `content="truncateCount"`, `custom-position`, `top="-6px"`, and `size="s"`. The `99+` truncation is performed by the shared `formatBadgeCount` utility (via the `truncateCount` computed), not inline in the template.
 - `isExpanded` applies `.vc-widget--expanded` modifier; used by the shell sidebar to visually distinguish active navigation state.
 - `horizontal` applies `.vc-widget--horizontal` modifier which switches the internal flex direction from `column` to `row`.
 - The widget registers as a keyboard-interactive element (`role="button"`, Enter/Space handlers) rather than using a `<button>` to allow embedding arbitrary icon components without nesting interactive elements.

package/runtime/knowledge/docs/ui/components/molecules/multilanguage-selector/multilanguage-selector.docs.md

@@ -1,12 +1,12 @@
 ---
-title: MultilanguageSelector
+title: VcLanguageSelector
 category: components
 group: form
 ---
 
-# MultilanguageSelector
+# VcLanguageSelector
 
-Compact circular flag button that opens a dropdown for selecting a content language. Designed for use in detail blades where entities have multilingual fields (e.g., product name, offer description, category title). This is distinct from the `LanguageSelector` settings entry, which changes the application UI locale -- `MultilanguageSelector` controls which language version of the content the user is editing.
+Compact circular flag button that opens a dropdown for selecting a content language. Designed for use in detail blades where entities have multilingual fields (e.g., product name, offer description, category title). This is distinct from the `LanguageSelector` settings entry, which changes the application UI locale -- `VcLanguageSelector` controls which language version of the content the user is editing.
 
 ## When to Use
 
@@ -21,7 +21,7 @@ Compact circular flag button that opens a dropdown for selecting a content langu
 ```vue
 <script setup lang="ts">
 import { ref } from "vue";
-import { MultilanguageSelector } from "@vc-shell/framework";
+import { VcLanguageSelector } from "@vc-shell/framework";
 
 const currentLang = ref("en-US");
 
@@ -32,7 +32,7 @@ const languages = [
 </script>
 
 <template>
-  <MultilanguageSelector
+  <VcLanguageSelector
     v-model="currentLang"
     :options="languages"
   />
@@ -58,7 +58,7 @@ A typical use case is a product detail blade where the user can edit the name an
 ```vue
 <script setup lang="ts">
 import { ref, computed } from "vue";
-import { MultilanguageSelector } from "@vc-shell/framework";
+import { VcLanguageSelector } from "@vc-shell/framework";
 
 const product = ref({
   names: { "en-US": "Widget", "de-DE": "Widget-Teil" },
@@ -91,7 +91,7 @@ const currentDescription = computed({
 <template>
   <VcBlade title="Edit Product">
     <template #actions>
-      <MultilanguageSelector
+      <VcLanguageSelector
         v-model="currentLang"
         :options="languages"
       />
@@ -132,7 +132,7 @@ onMounted(async () => {
 
 - **Compact layout**: The button renders as a small circle showing the flag of the currently selected language. Clicking it opens a dropdown with all available options.
 - **v-model binding**: The component uses `modelValue` / `update:modelValue` for two-way binding, following the standard Vue 3 v-model convention.
-- **Flag images**: The `flag` property on each option is optional. When provided, it shows the flag image; otherwise, the language code text is displayed.
+- **Flag images**: The `flag` property on each option is optional. When provided, it shows the flag image; otherwise, a globe icon (`lucide-globe`) is displayed.
 - **Dropdown positioning**: The dropdown is positioned relative to the button and adjusts to avoid viewport overflow.
 
 ## Tips

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

@@ -53,12 +53,12 @@ Without `v-model`, no items are expanded on mount. Pass an initial value to pre-
 
 Four variants control the visual grouping and spacing of accordion items.
 
-| Variant     | Description                                                              |
-| ----------- | ------------------------------------------------------------------------ |
-| `default`   | Items stacked with shared top/bottom borders, no gaps                    |
-| `bordered`  | Single outer border wrapping all items, items separated by inner borders |
-| `separated` | Card-like items with 12px gaps between them, each with its own border    |
-| `ghost`     | Transparent background, minimal styling, no borders or padding           |
+| Variant     | Description                                                                |
+| ----------- | -------------------------------------------------------------------------- |
+| `default`   | Items stacked with shared top/bottom borders, no gaps                      |
+| `bordered`  | Single outer border wrapping all items, items separated by inner borders   |
+| `separated` | Card-like items with 12px gaps between them, each with its own border      |
+| `ghost`     | Transparent background, minimal styling, no borders and no content padding |
 
 ```vue
 <VcAccordion :items="items" variant="separated" />
@@ -262,6 +262,16 @@ interface AccordionItem {
 | `--accordion-item-transition-duration`     | `300ms`                | Expand/collapse animation duration        |
 | `--accordion-item-fade-height`             | `60px`                 | Fade gradient height on collapsed preview |
 | `--accordion-item-focus-ring-color`        | `var(--primary-100)`   | Focus ring color for keyboard navigation  |
+| `--accordion-item-header-font-size`        | `14px`                 | Header font size                          |
+| `--accordion-item-header-font-weight`      | `500`                  | Header font weight                        |
+| `--accordion-item-header-line-height`      | `20px`                 | Header line height                        |
+| `--accordion-item-header-text-transform`   | `none`                 | Header text transform                     |
+| `--accordion-item-header-gap`              | `0`                    | Gap between header label and icon         |
+| `--accordion-item-icon-margin-left`        | `12px`                 | Left margin of the chevron icon           |
+| `--accordion-item-icon-size`               | `20px`                 | Chevron icon size                         |
+| `--accordion-item-content-color`           | `var(--secondary-950)` | Content body text color                   |
+| `--accordion-item-content-font-size`       | `14px`                 | Content body font size                    |
+| `--accordion-item-content-line-height`     | `20px`                 | Content body line height                  |
 
 > **Note:** The `ghost` variant overrides several variables to transparent/zero values for minimal appearance.
 

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

@@ -194,10 +194,10 @@ In a typical VC-Shell blade hierarchy, push a breadcrumb each time a child blade
 
 ```vue
 <script setup lang="ts">
-import { useBreadcrumbs, useBladeContext } from "@vc-shell/framework";
+import { useBreadcrumbs, useBlade } from "@vc-shell/framework";
 
 const { breadcrumbs, push } = useBreadcrumbs();
-const { openBlade, closeSelf } = useBladeContext();
+const { openBlade, closeSelf } = useBlade();
 
 function openProductDetail(product: Product) {
   push({
@@ -270,12 +270,13 @@ clickHandler: () => { navigate(); return true; }
 
 ## CSS Variables
 
-| Variable                                  | Default                | Description                          |
-| ----------------------------------------- | ---------------------- | ------------------------------------ |
-| `--separator-color`                       | `var(--neutrals-400)`  | Color of the `/` separator character |
-| `--breadcrumbs-item-border-color`         | `var(--secondary-300)` | Border color of breadcrumb items     |
-| `--breadcrumbs-expand-button-color`       | `var(--neutrals-500)`  | Color of the overflow "more" button  |
-| `--breadcrumbs-expand-button-color-hover` | `var(--neutrals-600)`  | Hover color of the overflow button   |
+| Variable                                  | Default                | Description                               |
+| ----------------------------------------- | ---------------------- | ----------------------------------------- |
+| `--separator-color`                       | `var(--neutrals-400)`  | Color of the `/` separator character      |
+| `--breadcrumbs-item-border-color`         | `var(--secondary-300)` | Border color of breadcrumb items          |
+| `--breadcrumbs-item-border-color-hover`   | `var(--secondary-400)` | Border color of breadcrumb items on hover |
+| `--breadcrumbs-expand-button-color`       | `var(--neutrals-500)`  | Color of the overflow "more" button       |
+| `--breadcrumbs-expand-button-color-hover` | `var(--neutrals-600)`  | Hover color of the overflow button        |
 
 ## Accessibility