@vc-shell/vc-app-skill 2.0.0-alpha.29 → 2.0.0-alpha.31

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

@@ -0,0 +1,178 @@
+# useResponsive
+
+Reactive breakpoint state for building responsive blade UIs. Returns refs that indicate the current viewport category (phone, tablet, mobile, desktop) and whether the device supports touch input. Replaces the legacy `$isMobile.value` global properties in templates and `inject(IsMobileKey)` in script setup with a single, consistent API.
+
+## When to Use
+
+- Conditionally render desktop vs. mobile layouts in blade pages and components
+- Apply responsive CSS classes based on viewport size
+- Toggle behavior (e.g., disable drag-and-drop on touch devices, switch column visibility)
+- When NOT to use: for CSS-only responsive changes, prefer Tailwind breakpoint prefixes (`md:`, `lg:`) instead of JavaScript-driven conditionals
+
+## Quick Start
+
+```vue
+<script setup lang="ts">
+import { useResponsive } from "@vc-shell/framework";
+
+const { isMobile, isDesktop } = useResponsive();
+</script>
+
+<template>
+  <VcBlade title="Orders">
+    <!-- Vue auto-unwraps refs from script setup — no .value needed -->
+    <div v-if="isDesktop" class="tw-flex tw-gap-4">
+      <OrdersTable />
+      <OrdersSummary />
+    </div>
+    <OrdersTable v-else />
+  </VcBlade>
+</template>
+```
+
+## API
+
+### Parameters
+
+None. The composable reads breakpoint state from the framework's provide/inject context, which is set up automatically by `VcApp`.
+
+### Returns (`UseResponsiveReturn`)
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `isMobile` | `Ref<boolean>` | `false` | `true` when viewport width < 1024px |
+| `isDesktop` | `Ref<boolean>` | `true` | `true` when viewport width >= 1024px |
+| `isPhone` | `Ref<boolean>` | `false` | `true` when viewport width < 480px |
+| `isTablet` | `Ref<boolean>` | `false` | `true` when 480px <= viewport width < 1024px |
+| `isTouch` | `boolean` | `false` | `true` on touch-capable devices (not reactive — set once at app init) |
+
+Breakpoint thresholds: phone < 480px, tablet 480–1023px, desktop >= 1024px. These match the framework's `setupBreakpoints()` configuration.
+
+Note: `isMobile` is the union of `isPhone` and `isTablet` — it covers all viewports below the desktop threshold.
+
+## How It Works
+
+Under the hood, `useResponsive()` calls `inject()` for each breakpoint key (`IsMobileKey`, `IsDesktopKey`, etc.) with sensible defaults. The framework's root `VcApp` component provides these refs during app initialization using VueUse's `useBreakpoints`. Because the return values are the same `Ref<boolean>` instances provided at the app level, they are reactive and shared across all components.
+
+The defaults ensure the composable works even outside the VcApp provider tree (e.g., in unit tests or Storybook), defaulting to desktop mode.
+
+## Recipe: Responsive Blade with Mobile Card Layout
+
+```vue
+<script setup lang="ts">
+import { useResponsive, useBlade } from "@vc-shell/framework";
+
+const { isMobile, isDesktop } = useResponsive();
+const { openBlade } = useBlade();
+</script>
+
+<template>
+  <VcBlade title="Products">
+    <VcDataTable
+      :items="products"
+      :total-count="totalCount"
+      @row-click="({ data }) => openBlade({ name: 'ProductDetails', param: data.id })"
+    >
+      <VcColumn
+        id="image"
+        title=""
+        type="image"
+        :width="60"
+        :always-visible="true"
+        mobile-role="image"
+      />
+      <VcColumn
+        id="name"
+        :title="t('NAME')"
+        :sortable="true"
+        :always-visible="true"
+        mobile-role="title"
+      />
+      <!-- Extra columns visible only on desktop -->
+      <VcColumn id="sku" :title="t('SKU')" :sortable="true" />
+      <VcColumn id="price" :title="t('PRICE')" type="money" :sortable="true" />
+      <VcColumn id="createdDate" :title="t('DATE')" type="date-ago" :sortable="true" />
+    </VcDataTable>
+  </VcBlade>
+</template>
+```
+
+## Recipe: Touch-Aware Drag and Drop
+
+```vue
+<script setup lang="ts">
+import { useResponsive } from "@vc-shell/framework";
+
+const { isTouch } = useResponsive();
+</script>
+
+<template>
+  <VcDataTable
+    :items="items"
+    :reorderable-rows="!isTouch"
+    @reorder="onReorder"
+  >
+    <!-- columns -->
+  </VcDataTable>
+</template>
+```
+
+## Common Mistakes
+
+**Wrong: using `$isMobile.value` in template (deprecated)**
+```vue
+<template>
+  <!-- $isMobile is a global property — requires .value, no auto-unwrap -->
+  <div v-if="$isMobile.value">Mobile</div>
+</template>
+```
+
+**Correct: using `useResponsive()` destructure**
+```vue
+<script setup lang="ts">
+import { useResponsive } from "@vc-shell/framework";
+const { isMobile } = useResponsive();
+</script>
+<template>
+  <!-- Vue auto-unwraps refs from script setup — clean and type-safe -->
+  <div v-if="isMobile">Mobile</div>
+</template>
+```
+
+---
+
+**Wrong: using `inject(IsMobileKey)` directly**
+```vue
+<script setup lang="ts">
+import { inject, ref } from "vue";
+import { IsMobileKey } from "@vc-shell/framework";
+// Verbose, requires importing both inject and the key
+const isMobile = inject(IsMobileKey, ref(false));
+</script>
+```
+
+**Correct: using `useResponsive()`**
+```vue
+<script setup lang="ts">
+import { useResponsive } from "@vc-shell/framework";
+// One import, one line, all breakpoints available
+const { isMobile } = useResponsive();
+</script>
+```
+
+## Tips
+
+- **Destructure only what you need.** `const { isMobile } = useResponsive()` is fine — unused refs have no overhead since they already exist at the app level.
+- **Prefer CSS breakpoints for styling.** Use `useResponsive()` for structural changes (different component trees), but for spacing/sizing tweaks use Tailwind responsive prefixes (`md:tw-px-4`).
+- **`isTouch` is not reactive.** It's determined once at app startup based on `ontouchstart` / `maxTouchPoints`. It won't change if a user connects a mouse to a tablet mid-session.
+- **Works in tests without providers.** Defaults to desktop mode (`isDesktop: true`, `isMobile: false`), so most component tests don't need to provide breakpoint keys unless testing mobile-specific behavior.
+
+## Migration
+
+See [migration guide #36](../../../../migration/36-use-responsive.md) for automated codemod and manual migration instructions.
+
+## Related
+
+- `VcApp` — provides the breakpoint refs that `useResponsive()` reads
+- `VcBlade` — uses `isMobile` internally for mobile blade layout
+- `VcDataTable` — uses `isMobile` for mobile card rendering and pull-to-refresh

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

@@ -1,6 +1,6 @@
 # useSlowNetworkDetection
 
-Detects slow network conditions and shows a persistent warning notification so users know why the UI is unresponsive. Two detection channels work together: a **proactive** channel reads `navigator.connection.effectiveType` to catch weak connections before any request is made, and a **reactive** channel flags API requests that have been pending for more than 5 seconds. The notification auto-dismisses with a 3-second delay after conditions clear, preventing flicker. When the browser goes fully offline, the slow-network notification is suppressed in favor of the existing offline notification from `useConnectionStatus`.
+Detects slow network conditions and shows a persistent warning notification so users know why the UI is unresponsive. Two detection channels work together: a **proactive** channel reads `navigator.connection.effectiveType` to catch weak connections before any request is made, and a **reactive** channel flags API requests that have been pending for more than 10 seconds. The notification auto-dismisses with a 3-second delay after conditions clear, preventing flicker. When the browser goes fully offline, the slow-network notification is suppressed in favor of the existing offline notification from `useConnectionStatus`.
 
 Like `useConnectionStatus`, this is a module-level singleton — calling it from multiple components shares the same state and listeners.
 
@@ -41,14 +41,14 @@ const { isSlowNetwork } = useSlowNetworkDetection();
 | Property | Type | Description |
 |---|---|---|
 | `isSlowNetwork` | `Readonly<Ref<boolean>>` | `true` when the network is slow (either channel active). Read-only. |
-| `trackRequest` | `(id: string) => void` | Start tracking a request. If it isn't untracked within 5 s, it counts as slow. |
+| `trackRequest` | `(id: string) => void` | Start tracking a request. If it isn't untracked within 10 s, it counts as slow. |
 | `untrackRequest` | `(id: string) => void` | Stop tracking a request. Cancels the timer or decrements the slow count. |
 
 ### Constants
 
 | Name | Value | Purpose |
 |---|---|---|
-| `SLOW_REQUEST_THRESHOLD_MS` | `5000` | Time before a pending request is considered slow |
+| `SLOW_REQUEST_THRESHOLD_MS` | `10000` | Time before a pending request is considered slow |
 | `DISMISS_DELAY_MS` | `3000` | Delay before hiding the notification after recovery |
 | `SLOW_EFFECTIVE_TYPES` | `["slow-2g", "2g"]` | Connection types flagged as slow |
 
@@ -60,7 +60,7 @@ On first call, the composable checks `navigator.connection.effectiveType` (Netwo
 
 ### Channel 2: Request timers (reactive)
 
-The fetch interceptor in `framework/core/interceptors/index.ts` calls `trackRequest(id)` before every `/api/*` request and `untrackRequest(id)` in the `finally` block. Each tracked request gets a 5-second timer. If the response arrives in time, the timer is cancelled. If not, `isSlowNetwork` becomes `true` and stays `true` until all slow requests complete.
+The fetch interceptor in `framework/core/interceptors/index.ts` calls `trackRequest(id)` before every `/api/*` request and `untrackRequest(id)` in the `finally` block. Each tracked request gets a 10-second timer. If the response arrives in time, the timer is cancelled. If not, `isSlowNetwork` becomes `true` and stays `true` until all slow requests complete.
 
 ### Notification lifecycle
 

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

@@ -28,6 +28,7 @@ An image display component with predefined sizes, aspect ratio control, and a pl
 | `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 |
+| `thumbnailSize` | `ThumbnailSize` | — | Load a thumbnail variant instead of full-size image. Values: `"sm"`, `"md"`, `"lg"`, `"64x64"`, `"128x128"`, `"168x168"`, `"216x216"`, `"348x348"` |
 
 ## Size Reference
 

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

@@ -40,6 +40,7 @@ function deleteImage() { /* remove from list */ }
 | `name` | `string` | — | File name displayed in the tray |
 | `imageFit` | `"contain" \| "cover"` | `"contain"` | How the image fits within the tile |
 | `actions` | `VcImageTileActions` | — | Which built-in action buttons to show |
+| `thumbnailSize` | `ThumbnailSize` | — | Load a thumbnail variant instead of full-size image |
 
 ## VcImageTileActions Interface
 

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

@@ -62,7 +62,7 @@ A blade has four visual zones, rendered top-to-bottom:
 |--------------------------------------|
 |  [Save] [Delete] [Refresh]  [More >] |  <-- Toolbar
 |--------------------------------------|
-|  ** Unsaved changes banner **        |  <-- Status Banners
+|  ** Status banners (stacked) **      |  <-- Status Banners
 |--------------------------------------|
 |                                      |
 |         Content (default slot)       |  <-- Content Area
@@ -74,7 +74,7 @@ A blade has four visual zones, rendered top-to-bottom:
 
 **Toolbar** -- Action buttons from the `toolbarItems` prop. Overflow items automatically collapse into a "More" dropdown (via `ResizeObserver`).
 
-**Status Banners** -- Yellow banner when `modified` is `true`; red banner when the blade has an error (set via `setError()`).
+**Status Banners** -- Unified, priority-sorted banner area. System banners: yellow when `modified` is `true`, red when the blade has an error (via `setError()`). Custom banners can be added programmatically via `useBlade().addBanner()` — see [useBlade docs](../../../core/composables/useBlade/useBlade.docs.md#banner-management).
 
 **Content Area** -- The `default` slot. Scrolls independently of header and toolbar.
 
@@ -399,6 +399,31 @@ import { useBeforeUnload } from "@vc-shell/framework";
 useBeforeUnload(hasChanges);  // Browser tab close warning
 ```
 
+## Custom Banners
+
+Add informational, warning, or success banners to a blade programmatically. Banners appear between the header and toolbar, sorted by severity.
+
+```vue
+<script setup lang="ts">
+import { useBlade } from "@vc-shell/framework";
+
+const { addBanner, removeBanner, clearBanners } = useBlade();
+
+// Info banner (e.g. read-only mode)
+addBanner({ variant: "info", message: "This record is read-only" });
+
+// Dismissible warning with action
+addBanner({
+  variant: "warning",
+  message: "License expires in 7 days",
+  dismissible: true,
+  action: { label: "Renew", handler: () => openRenewal() },
+});
+</script>
+```
+
+Four variants are available: `danger`, `warning`, `info`, `success`. System banners (error and unsaved changes) are always present and cannot be removed by `clearBanners()`. For the full API reference, see [useBlade — Banner Management](../../../core/composables/useBlade/useBlade.docs.md#banner-management).
+
 ## Blade Width Control
 
 ```vue

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

@@ -13,17 +13,21 @@ A responsive multi-image gallery with drag-and-drop reorder, file upload, lightb
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
+| `layout` | `"filmstrip" \| "grid"` | `"filmstrip"` | Layout mode — filmstrip shows a single scrollable row with expand/collapse; grid shows the classic multi-row auto-fill layout. |
+| `label` | `string` | `undefined` | Label text displayed in the gallery header. |
+| `required` | `boolean` | `false` | Shows a required indicator (`*`) on the label. |
 | `images` | `ICommonAsset[]` | `[]` | Array of image assets to display. |
 | `disabled` | `boolean` | `false` | Disables all interactive actions. |
 | `multiple` | `boolean` | `false` | Allow selecting multiple files in upload dialog. |
-| `loading` | `boolean` | `false` | Shows a loading spinner on the upload zone. |
+| `loading` | `boolean` | `false` | Shows a loading overlay with spinner on the gallery. |
 | `itemActions` | `{ preview?: boolean; edit?: boolean; remove?: boolean }` | `{ preview: true, edit: true, remove: true }` | Per-tile action visibility. |
 | `rules` | `IValidationRules` | `undefined` | Validation rules for uploaded files. |
 | `name` | `string` | `"Gallery"` | Field name for validation messages. |
 | `accept` | `string` | `undefined` | Accepted file extensions. |
-| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Tile size preset. |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Tile size preset. Sizes are smaller on mobile. |
 | `gap` | `number` | `8` | Gap between tiles in pixels. |
 | `imagefit` | `"contain" \| "cover"` | `"contain"` | How images fit within tiles. |
+| `thumbnailSize` | `ThumbnailSize` | auto from `size` | Thumbnail size for tile images. Auto-mapped: sm→128x128, md→216x216, lg→348x348. Preview thumbnails use 64x64. |
 
 ## Events
 
@@ -44,20 +48,24 @@ A responsive multi-image gallery with drag-and-drop reorder, file upload, lightb
 
 ## Features
 
-- **Drag-and-drop reorder** -- Drag tiles to reorder. Emits `sort` with the new array. The dragged tile shows a ghost preview during the drag operation.
-- **External file drop** -- Drop files from the OS onto the gallery to upload. The entire gallery acts as a drop target with visual feedback.
-- **Lightbox preview** -- Click a tile to open a full-screen preview carousel. Navigate between images with arrow keys or swipe gestures.
-- **Responsive grid** -- Auto-fill grid adapts to container width using CSS grid with `auto-fill` and `minmax()`.
-- **Per-tile actions** -- Each tile shows preview, edit, and remove buttons on hover. Disable individual actions via the `itemActions` prop.
+- **Filmstrip layout (default)** -- Single-row scrollable strip powered by Swiper. Navigate with arrows, mouse wheel, or swipe. Click "Expand (N)" to show all images in a grid. "Collapse" returns to filmstrip.
+- **Grid layout** -- Classic auto-fill grid that wraps images into multiple rows. Set `layout="grid"` to use this mode.
+- **Drag-and-drop reorder** -- Drag tiles by the grip handle to reorder (powered by SortableJS). Works on both desktop and touch devices. In filmstrip mode, dragging to the edge auto-scrolls the strip. Emits `sort` with the new array.
+- **External file drop** -- Drop files from the OS onto the gallery to upload. The dashed border acts as a visual drop zone indicator (desktop only). A full overlay appears during drag-over.
+- **Fullscreen preview** -- Click the preview button to open a fullscreen carousel. Swipe or use arrow keys to navigate. Thumbnail strip at the bottom syncs with the main image.
+- **Per-tile actions** -- Each tile shows preview, edit, and remove buttons. On desktop: visible on hover. On mobile: visible on tap. Tile name is shown in the top bar alongside the drag handle.
+- **Loading state** -- When `loading` is true, a pulsing border and spinner overlay appear on the gallery. Upload button is disabled. Swiper navigation is frozen.
+- **Mobile responsive** -- Smaller tile sizes, no drag-and-drop hints, no dashed borders, compact action buttons, tap-to-reveal overlays. Uses `useResponsive` throughout.
+- **Lazy loading** -- Images use native `loading="lazy"` for deferred loading.
 
 ## Basic Usage
 
 ```vue
 <VcGallery
+  label="Product Images"
+  required
   :images="product.images"
-  size="md"
   imagefit="cover"
-  :item-actions="{ preview: true, edit: true, remove: true }"
   @upload="handleUpload"
   @sort="handleSort"
   @edit="handleEdit"
@@ -65,6 +73,31 @@ A responsive multi-image gallery with drag-and-drop reorder, file upload, lightb
 />
 ```
 
+## Filmstrip Layout (Default)
+
+```vue
+<VcGallery
+  label="Images"
+  :images="product.images"
+  imagefit="cover"
+  @upload="handleUpload"
+  @sort="handleSort"
+  @remove="handleRemove"
+/>
+```
+
+## Classic Grid Layout
+
+```vue
+<VcGallery
+  layout="grid"
+  label="Attachments"
+  :images="product.images"
+  @upload="handleUpload"
+  @sort="handleSort"
+/>
+```
+
 ## Recipe: Product Image Gallery in a Blade
 
 ```vue
@@ -99,6 +132,8 @@ function handleRemove(image: ICommonAsset) {
 <template>
   <VcBlade title="Product Images">
     <VcGallery
+      label="Product Images"
+      required
       :images="images"
       multiple
       accept=".jpg,.png,.webp"
@@ -152,20 +187,24 @@ function handleRemove(image: ICommonAsset) {
 
 ## Tips
 
-- The `size` prop controls tile dimensions: `"sm"` is good for compact grids (e.g., thumbnails in a sidebar), `"md"` is the standard, and `"lg"` works well for hero image management.
+- The `size` prop controls tile dimensions: `"sm"` is good for compact grids (e.g., thumbnails in a sidebar), `"md"` is the standard, and `"lg"` works well for hero image management. Tiles are automatically smaller on mobile.
 - Use `imagefit="cover"` for photo galleries where cropping is acceptable, and `"contain"` for logos or icons where the full image must be visible.
-- The upload zone tile always appears at the end of the grid when the gallery is not disabled. It accepts both click and drag-and-drop interactions.
+- The filmstrip layout is ideal for blades where vertical space is limited. Users can expand to see all images or scroll horizontally. The classic grid layout is better for dedicated media management pages.
+- Use the `label` prop to display a header label integrated with the upload button. Add `required` to show a required indicator.
 - The `startingSortOrder` parameter in the `upload` event tells you where the new files should be inserted in the sort order. Use it to maintain correct ordering when appending new images.
+- On desktop, reorder by dragging the grip handle icon. In filmstrip mode, dragging to the strip edge auto-scrolls to reveal more tiles.
+- On mobile, tap a tile to reveal action buttons and the image name. Drag-and-drop hints and dashed borders are hidden automatically.
 
 ## Accessibility
 
 - Tiles are keyboard-navigable with Tab and action buttons are focusable
-- Lightbox preview supports keyboard navigation (arrow keys, Escape to close)
-- The upload zone is accessible via keyboard (Enter/Space to open file picker)
-- Drag-and-drop reorder requires mouse/touch; provide an alternative reorder mechanism for keyboard-only users if needed
+- Fullscreen preview supports keyboard navigation (arrow keys, Escape to close) and swipe gestures
+- The upload button in the header is keyboard-accessible
+- On mobile, tile actions are revealed via tap with click-outside to dismiss
 
 ## Related Components
 
 - **VcImageUpload** -- single-image upload component
-- **VcImageTile** -- the internal tile component used for each image
-- **VcLabel** / **VcHint** -- use alongside VcGallery for field labeling
+- **VcImageTile** -- the internal tile component used for each image (topbar with name + drag handle, bottom tray with actions)
+- **VcFileUpload** -- the file upload drop zone used in empty gallery state
+- **VcLabel** -- used internally when `label` prop is set

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

@@ -1,111 +0,0 @@
-# useBladeContext (defineBladeContext / injectBladeContext)
-
-Exposes blade-level data to descendant widgets, extensions, and nested components via Vue's provide/inject mechanism. This pair of functions eliminates the need for prop drilling when child widgets or extension points need access to the parent blade's entity data, loading flags, or other shared state.
-
-The pattern follows a "define once, inject anywhere" approach: the blade component calls `defineBladeContext` during setup, and any descendant (no matter how deeply nested) can call `injectBladeContext` to read that data reactively.
-
-## When to Use
-
-- Share blade state (current entity, loading flags, disabled state) with child widgets without prop drilling
-- Access parent blade data from an extension or widget component
-- Expose selective fields to widgets (e.g., only the entity ID) via a computed getter
-- When NOT to use: for cross-blade communication between sibling blades (use `useBlade` / blade messaging instead)
-
-## Basic Usage
-
-```typescript
-// In a blade's <script setup>
-import { defineBladeContext, injectBladeContext } from '@vc-shell/framework';
-
-// Provide context — refs/computeds are auto-unwrapped for consumers
-defineBladeContext({ item, disabled, loading });
-
-// Or with a computed for selective exposure
-defineBladeContext(computed(() => ({ id: item.value?.id })));
-```
-
-```typescript
-// In a widget or nested component
-import { injectBladeContext } from '@vc-shell/framework';
-
-const ctx = injectBladeContext();
-// Refs are already unwrapped — access values directly, no .value needed
-const entityId = computed(() => ctx.value.id as string);
-const item = computed(() => ctx.value.item as { id: string; name: string });
-```
-
-## API
-
-### defineBladeContext
-
-| Parameter | Type | Required | Description |
-|---|---|---|---|
-| `data` | `MaybeRefOrGetter<Record<string, unknown>>` | Yes | Plain object, ref, or getter to expose |
-
-Returns `void`. Must be called in the blade's `<script setup>`.
-
-### injectBladeContext
-
-Takes no parameters. Returns `ComputedRef<Record<string, unknown>>`.
-
-Throws `InjectionError` if no ancestor blade has called `defineBladeContext`.
-
-## Recipe: Widget Consuming Blade Context
-
-A typical pattern is a sidebar widget that needs to load related data based on the current blade entity. The widget does not receive any props from the blade -- it reads the entity ID from the blade context:
-
-```vue
-<script setup lang="ts">
-// widgets/RelatedOrdersWidget.vue
-import { computed, watch } from "vue";
-import { injectBladeContext } from "@vc-shell/framework";
-
-const ctx = injectBladeContext();
-const customerId = computed(() => ctx.value.id as string | undefined);
-
-// Reload orders whenever the customer changes
-watch(customerId, async (id) => {
-  if (id) {
-    await loadOrders(id);
-  }
-});
-</script>
-```
-
-```vue
-<script setup lang="ts">
-// blades/CustomerDetailBlade.vue
-import { ref, computed } from "vue";
-import { defineBladeContext } from "@vc-shell/framework";
-
-const customer = ref({ id: "cust-1", name: "Acme Corp" });
-const loading = ref(false);
-
-// Expose the customer data to all descendant widgets
-defineBladeContext(computed(() => ({
-  id: customer.value?.id,
-  name: customer.value?.name,
-  loading: loading.value,
-})));
-</script>
-```
-
-## Details
-
-- **Automatic ref unwrapping**: `defineBladeContext` shallow-unwraps all ref/computed values in the provided object. Consumers get plain values directly (`ctx.value.item` instead of `ctx.value.item.value`). This works reactively — when the source ref changes, the context updates automatically.
-- **Reactivity**: The provided context is always wrapped in a `computed`, so consumers receive a `ComputedRef` regardless of whether the provider passed a plain object, a ref, or a getter. Changes propagate automatically.
-- **Injection key**: Uses `BladeContextKey` from `framework/injection-keys.ts`. This is a framework-level Symbol, so there is no risk of key collision with application code.
-- **Error handling**: `injectBladeContext` throws an `InjectionError` with a descriptive message if called outside a blade component tree. This fails fast during development rather than silently returning `undefined`.
-- **Scope**: The context is scoped to the Vue component subtree. Each blade in the stack has its own context, so nested blades do not leak data upward or sideways.
-
-## Tips
-
-- Prefer exposing a computed getter rather than the full reactive object when only a subset of fields is needed. This minimizes unnecessary re-renders in consuming widgets.
-- The context value is untyped (`Record<string, unknown>`). Use type assertions or a typed wrapper in your module if you need type safety (e.g., `ctx.value.id as string`).
-- If a blade does not call `defineBladeContext`, any descendant calling `injectBladeContext` will throw. Make sure all blades that host widgets define their context.
-
-## Related
-
-- `BladeContextKey` in `framework/injection-keys.ts`
-- `useBladeWidgets` -- widgets that consume blade context
-- `useBladeStack` -- manages the blade navigation stack