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

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

@@ -16,17 +16,26 @@ Uses `createSharedComposable` from VueUse, so all callers across the entire appl
 
 ```vue
 <script setup lang="ts">
-import { useUser } from '@vc-shell/framework';
+import { useUser } from "@vc-shell/framework";
 
 const { user, isAuthenticated, isAdministrator, loading } = useUser();
 </script>
 
 <template>
-  <div v-if="loading" class="tw-animate-pulse">Loading user...</div>
+  <div
+    v-if="loading"
+    class="tw-animate-pulse"
+  >
+    Loading user...
+  </div>
 
   <div v-else-if="isAuthenticated">
     <p>Welcome, {{ user?.userName }}</p>
-    <span v-if="isAdministrator" class="tw-badge tw-badge-primary">Admin</span>
+    <span
+      v-if="isAdministrator"
+      class="tw-badge tw-badge-primary"
+      >Admin</span
+    >
   </div>
 
   <div v-else>
@@ -43,15 +52,15 @@ None.
 
 ### Returns
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `user` | `ComputedRef<UserDetail \| undefined>` | Current user details (userName, email, id, etc.), or `undefined` if not authenticated. |
-| `loading` | `ComputedRef<boolean>` | Whether a user operation (loadUser, signOut) is in progress. |
-| `isAuthenticated` | `ComputedRef<boolean>` | Whether a user session is active. Derived from `user.userName != null`. |
-| `isAdministrator` | `ComputedRef<boolean \| undefined>` | Whether the current user has admin privileges. `undefined` if user is not loaded. |
-| `loadUser` | `() => Promise<UserDetail>` | Loads/reloads user info from the server. Deduplicates concurrent calls -- if two components call `loadUser()` at the same time, only one API request is made. |
-| `signOut` | `() => Promise<void>` | Signs out the current user, clears auth data from localStorage, and resets the user state. Handles both standard and external (SSO) sign-out flows. |
-| `getAccessToken` | `() => Promise<string \| null>` | Returns the current OAuth access token. Automatically refreshes using the refresh token if the access token has expired or will expire within 60 seconds. Returns `null` if no auth data exists. |
+| Property          | Type                                   | Description                                                                                                                                                                                      |
+| ----------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `user`            | `ComputedRef<UserDetail \| undefined>` | Current user details (userName, email, id, etc.), or `undefined` if not authenticated.                                                                                                           |
+| `loading`         | `ComputedRef<boolean>`                 | Whether a user operation (loadUser, signOut) is in progress.                                                                                                                                     |
+| `isAuthenticated` | `ComputedRef<boolean>`                 | Whether a user session is active. Derived from `user.userName != null`.                                                                                                                          |
+| `isAdministrator` | `ComputedRef<boolean \| undefined>`    | Whether the current user has admin privileges. `undefined` if user is not loaded.                                                                                                                |
+| `loadUser`        | `() => Promise<UserDetail>`            | Loads/reloads user info from the server. Deduplicates concurrent calls -- if two components call `loadUser()` at the same time, only one API request is made.                                    |
+| `signOut`         | `() => Promise<void>`                  | Signs out the current user, clears auth data from localStorage, and resets the user state. Handles both standard and external (SSO) sign-out flows.                                              |
+| `getAccessToken`  | `() => Promise<string \| null>`        | Returns the current OAuth access token. Automatically refreshes using the refresh token if the access token has expired or will expire within 60 seconds. Returns `null` if no auth data exists. |
 
 ## How It Works
 
@@ -63,14 +72,16 @@ The composable delegates to `_createInternalUserLogic()`, which manages:
 
 3. **Token refresh**: `getAccessToken()` checks the expiration time with a 60-second buffer. If the token is expired or about to expire and a refresh token is available, it makes a `POST /connect/token` request with `grant_type: refresh_token`.
 
-4. **Shared state**: `createSharedComposable` from VueUse ensures all calls to `useUser()` return the same reactive refs. The underlying `user` ref is module-level, so it persists across component lifecycles.
+4. **Shared state**: `createSharedComposable` from VueUse wraps `_createInternalUserLogic` so every call to `useUser()` or `useUserManagement()` reads from the same singleton internal logic. The `user` ref lives inside that singleton. App bootstrap registers `useUserManagement()` outside any component scope, which pins the singleton for the app lifetime — transient component mount/unmount cycles don't discard it.
 
 ## Recipe: Route Guard Based on Authentication
 
 ```typescript
-import { useUser } from '@vc-shell/framework';
+import { useUser } from "@vc-shell/framework";
 
-const router = createRouter({ /* ... */ });
+const router = createRouter({
+  /* ... */
+});
 
 router.beforeEach(async (to) => {
   const { isAuthenticated, loadUser } = useUser();
@@ -85,7 +96,7 @@ router.beforeEach(async (to) => {
   }
 
   if (to.meta.requiresAuth && !isAuthenticated.value) {
-    return { name: 'SignIn' };
+    return { name: "SignIn" };
   }
 });
 ```
@@ -95,25 +106,33 @@ router.beforeEach(async (to) => {
 ```vue
 <template>
   <div class="tw-flex tw-items-center tw-gap-2">
-    <VcAvatar :name="user?.userName" size="sm" />
+    <VcAvatar
+      :name="user?.userName"
+      size="sm"
+    />
     <div>
       <p class="tw-text-sm tw-font-medium">{{ user?.userName }}</p>
       <p class="tw-text-xs tw-text-gray-500">{{ user?.email }}</p>
     </div>
-    <VcButton size="sm" variant="ghost" @click="handleSignOut">Sign Out</VcButton>
+    <VcButton
+      size="sm"
+      variant="ghost"
+      @click="handleSignOut"
+      >Sign Out</VcButton
+    >
   </div>
 </template>
 
 <script setup lang="ts">
-import { useUser } from '@vc-shell/framework';
-import { useRouter } from 'vue-router';
+import { useUser } from "@vc-shell/framework";
+import { useRouter } from "vue-router";
 
 const { user, signOut } = useUser();
 const router = useRouter();
 
 async function handleSignOut() {
   await signOut();
-  router.push({ name: 'SignIn' });
+  router.push({ name: "SignIn" });
 }
 </script>
 ```
@@ -121,7 +140,7 @@ async function handleSignOut() {
 ## Recipe: Adding Access Token to Custom API Calls
 
 ```typescript
-import { useUser } from '@vc-shell/framework';
+import { useUser } from "@vc-shell/framework";
 
 const { getAccessToken } = useUser();
 
@@ -130,7 +149,7 @@ async function fetchCustomEndpoint(url: string) {
 
   const response = await fetch(url, {
     headers: {
-      Authorization: token ? `Bearer ${token}` : '',
+      Authorization: token ? `Bearer ${token}` : "",
     },
   });
 
@@ -140,7 +159,7 @@ async function fetchCustomEndpoint(url: string) {
 
 ## Tips
 
-- **`loadUser` deduplicates concurrent calls.** If your app loads multiple blades simultaneously and each calls `loadUser()`, only one API request is made. All calls resolve with the same result.
+- **`loadUser` deduplicates concurrent calls across composables.** If multiple blades call `loadUser()` simultaneously — or if `useUser()` and `useUserManagement()` are both used in the same flow — only one API request is made. `useUser` and `useUserManagement` share the singleton internal logic, so request deduplication works across both.
 - **Token refresh is transparent.** `getAccessToken()` handles expiration checking and refresh internally. You never need to manually check token expiration or call a refresh endpoint.
 - **`isAuthenticated` checks `userName`, not the token.** A user is considered authenticated if `user.value?.userName` is not null. This means the user could have an expired token but still appear "authenticated" until the next API call fails.
 - **`signOut` clears localStorage.** After sign-out, the `vc_auth_data` key is removed from localStorage. Any cached tokens are gone permanently.

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

@@ -2,7 +2,7 @@
 
 Shared composable exposing the full user management API: sign-in, sign-out, password reset, token validation, and login type discovery. This composable extends the same internal logic as `useUser` but surfaces the administrative and authentication-flow methods that `useUser` intentionally hides. The separation ensures that regular blades only have access to read-only user state, while auth pages and admin screens get the full API.
 
-Uses `createSharedComposable` from VueUse, so all callers share the same state instance. Internally, it calls `_createInternalUserLogic()` -- the same factory used by `useUser` -- so both composables operate on the same underlying user ref and auth data.
+Both `useUser()` and `useUserManagement()` read from the same singleton internal logic, so everything is shared: the `user` ref, `authData`, the `loading` ref, in-flight request deduplication (`loadUser`), and the underlying `SecurityClient` instance. The two composables are thin selectors over a single source of truth — picking a narrow read-only slice or the full management slice.
 
 ## When to Use
 
@@ -17,29 +17,45 @@ Uses `createSharedComposable` from VueUse, so all callers share the same state i
 
 ```vue
 <script setup lang="ts">
-import { useUserManagement } from '@vc-shell/framework';
-import { ref } from 'vue';
+import { useUserManagement } from "@vc-shell/framework";
+import { ref } from "vue";
 
 const { signIn, loading, isAuthenticated } = useUserManagement();
-const username = ref('');
-const password = ref('');
-const errorMessage = ref('');
+const username = ref("");
+const password = ref("");
+const errorMessage = ref("");
 
 async function handleLogin() {
-  errorMessage.value = '';
+  errorMessage.value = "";
   const result = await signIn(username.value, password.value);
   if (!result.succeeded) {
-    errorMessage.value = result.error ?? 'Login failed';
+    errorMessage.value = result.error ?? "Login failed";
   }
 }
 </script>
 
 <template>
   <form @submit.prevent="handleLogin">
-    <VcInput v-model="username" label="Username" />
-    <VcInput v-model="password" label="Password" type="password" />
-    <p v-if="errorMessage" class="tw-text-red-500">{{ errorMessage }}</p>
-    <VcButton type="submit" :loading="loading">Sign In</VcButton>
+    <VcInput
+      v-model="username"
+      label="Username"
+    />
+    <VcInput
+      v-model="password"
+      label="Password"
+      type="password"
+    />
+    <p
+      v-if="errorMessage"
+      class="tw-text-red-500"
+    >
+      {{ errorMessage }}
+    </p>
+    <VcButton
+      type="submit"
+      :loading="loading"
+      >Sign In</VcButton
+    >
   </form>
 </template>
 ```
@@ -52,25 +68,25 @@ None.
 
 ### Returns
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `user` | `ComputedRef<UserDetail \| undefined>` | Current user details. |
-| `loading` | `ComputedRef<boolean>` | Whether any operation is in progress. |
-| `isAdministrator` | `ComputedRef<boolean \| undefined>` | Admin status of the current user. |
-| `isAuthenticated` | `ComputedRef<boolean>` | Whether user session is active. |
-| `signIn` | `(username: string, password: string) => Promise<SignInResult>` | Authenticates with username/password. Performs cookie-based login, obtains an OAuth token with offline_access scope, and loads user details. Returns `{ succeeded: true }` on success or `{ succeeded: false, error: string }` on failure. |
-| `signOut` | `() => Promise<void>` | Clears session, auth data, and localStorage. Handles both standard and external SSO sign-out. |
-| `loadUser` | `() => Promise<UserDetail>` | Loads/reloads user info from the server. Deduplicates concurrent calls. |
-| `validateToken` | `(userId: string, token: string) => Promise<boolean>` | Validates a password-reset token. Returns `true` if valid. |
-| `validatePassword` | `(password: string) => Promise<IdentityResult>` | Validates a password against the platform's password policy (length, complexity, etc.). |
-| `resetPasswordByToken` | `(userId: string, password: string, token: string) => Promise<SecurityResult>` | Resets a user's password using a reset token. Returns `{ succeeded: true }` on success. |
-| `requestPasswordReset` | `(loginOrEmail: string) => Promise<RequestPasswordResult>` | Sends a password-reset email to the user. Returns `{ succeeded: true }` on success. |
-| `changeUserPassword` | `(oldPassword: string, newPassword: string) => Promise<SecurityResult \| undefined>` | Changes the current user's password. Requires the old password for verification. |
-| `getLoginType` | `() => Promise<LoginType[]>` | Returns available login types (password-based, external SSO providers, etc.). Used to render the appropriate sign-in UI. |
+| Property               | Type                                                                                 | Description                                                                                                                                                                                                                                |
+| ---------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `user`                 | `ComputedRef<UserDetail \| undefined>`                                               | Current user details.                                                                                                                                                                                                                      |
+| `loading`              | `ComputedRef<boolean>`                                                               | Whether any operation is in progress.                                                                                                                                                                                                      |
+| `isAdministrator`      | `ComputedRef<boolean \| undefined>`                                                  | Admin status of the current user.                                                                                                                                                                                                          |
+| `isAuthenticated`      | `ComputedRef<boolean>`                                                               | Whether user session is active.                                                                                                                                                                                                            |
+| `signIn`               | `(username: string, password: string) => Promise<SignInResult>`                      | Authenticates with username/password. Performs cookie-based login, obtains an OAuth token with offline_access scope, and loads user details. Returns `{ succeeded: true }` on success or `{ succeeded: false, error: string }` on failure. |
+| `signOut`              | `() => Promise<void>`                                                                | Clears session, auth data, and localStorage. Handles both standard and external SSO sign-out.                                                                                                                                              |
+| `loadUser`             | `() => Promise<UserDetail>`                                                          | Loads/reloads user info from the server. Deduplicates concurrent calls.                                                                                                                                                                    |
+| `validateToken`        | `(userId: string, token: string) => Promise<boolean>`                                | Validates a password-reset token. Returns `true` if valid.                                                                                                                                                                                 |
+| `validatePassword`     | `(password: string) => Promise<IdentityResult>`                                      | Validates a password against the platform's password policy (length, complexity, etc.).                                                                                                                                                    |
+| `resetPasswordByToken` | `(userId: string, password: string, token: string) => Promise<SecurityResult>`       | Resets a user's password using a reset token. Returns `{ succeeded: true }` on success.                                                                                                                                                    |
+| `requestPasswordReset` | `(loginOrEmail: string) => Promise<RequestPasswordResult>`                           | Sends a password-reset email to the user. Returns `{ succeeded: true }` on success.                                                                                                                                                        |
+| `changeUserPassword`   | `(oldPassword: string, newPassword: string) => Promise<SecurityResult \| undefined>` | Changes the current user's password. Requires the old password for verification.                                                                                                                                                           |
+| `getLoginType`         | `() => Promise<LoginType[]>`                                                         | Returns available login types (password-based, external SSO providers, etc.). Used to render the appropriate sign-in UI.                                                                                                                   |
 
 ## How It Works
 
-The composable creates (or reuses) the internal user logic via `_createInternalUserLogic()`. The `signIn` flow has three phases:
+The composable reads from the singleton internal user logic (instantiated lazily on first call to `useUser()` or `useUserManagement()`). The `signIn` flow has three phases:
 
 1. **Cookie login**: Calls `securityClient.login()` to establish a server-side session cookie.
 2. **OAuth token**: Fetches an OAuth token via `POST /connect/token` with `grant_type: password` and `scope: offline_access`. The refresh token enables automatic token renewal.
@@ -82,9 +98,9 @@ Token data is stored in localStorage under `vc_auth_data` and survives page relo
 
 ```vue
 <script setup lang="ts">
-import { useUserManagement } from '@vc-shell/framework';
-import { ref } from 'vue';
-import { useRoute, useRouter } from 'vue-router';
+import { useUserManagement } from "@vc-shell/framework";
+import { ref } from "vue";
+import { useRoute, useRouter } from "vue-router";
 
 const { validateToken, validatePassword, resetPasswordByToken, loading } = useUserManagement();
 const route = useRoute();
@@ -92,39 +108,39 @@ const router = useRouter();
 
 const userId = route.query.userId as string;
 const token = route.query.token as string;
-const newPassword = ref('');
-const confirmPassword = ref('');
-const error = ref('');
+const newPassword = ref("");
+const confirmPassword = ref("");
+const error = ref("");
 const tokenValid = ref(false);
 
 // Validate the token on mount
 onMounted(async () => {
   tokenValid.value = await validateToken(userId, token);
   if (!tokenValid.value) {
-    error.value = 'This reset link has expired or is invalid.';
+    error.value = "This reset link has expired or is invalid.";
   }
 });
 
 async function handleReset() {
-  error.value = '';
+  error.value = "";
 
   if (newPassword.value !== confirmPassword.value) {
-    error.value = 'Passwords do not match.';
+    error.value = "Passwords do not match.";
     return;
   }
 
   // Validate against password policy
   const validation = await validatePassword(newPassword.value);
   if (!validation.succeeded) {
-    error.value = validation.errors?.join(', ') ?? 'Password does not meet requirements.';
+    error.value = validation.errors?.join(", ") ?? "Password does not meet requirements.";
     return;
   }
 
   const result = await resetPasswordByToken(userId, newPassword.value, token);
   if (result.succeeded) {
-    router.push({ name: 'SignIn', query: { message: 'Password reset successfully' } });
+    router.push({ name: "SignIn", query: { message: "Password reset successfully" } });
   } else {
-    error.value = result.errors?.join(', ') ?? 'Reset failed.';
+    error.value = result.errors?.join(", ") ?? "Reset failed.";
   }
 }
 </script>
@@ -134,8 +150,8 @@ async function handleReset() {
 
 ```vue
 <script setup lang="ts">
-import { useUserManagement } from '@vc-shell/framework';
-import { ref, onMounted } from 'vue';
+import { useUserManagement } from "@vc-shell/framework";
+import { ref, onMounted } from "vue";
 
 const { getLoginType, signIn } = useUserManagement();
 const loginTypes = ref<LoginType[]>([]);
@@ -144,20 +160,24 @@ const showPasswordForm = ref(false);
 onMounted(async () => {
   loginTypes.value = await getLoginType();
   // Show password form only if password auth is available
-  showPasswordForm.value = loginTypes.value.some((t) => t.loginProvider === 'password');
+  showPasswordForm.value = loginTypes.value.some((t) => t.loginProvider === "password");
 });
 </script>
 
 <template>
   <div>
-    <form v-if="showPasswordForm" @submit.prevent="handlePasswordLogin">
+    <form
+      v-if="showPasswordForm"
+      @submit.prevent="handlePasswordLogin"
+    >
       <!-- standard username/password form -->
     </form>
 
-    <div v-for="provider in loginTypes.filter((t) => t.loginProvider !== 'password')" :key="provider.loginProvider">
-      <VcButton @click="redirectToSSO(provider)">
-        Sign in with {{ provider.loginProvider }}
-      </VcButton>
+    <div
+      v-for="provider in loginTypes.filter((t) => t.loginProvider !== 'password')"
+      :key="provider.loginProvider"
+    >
+      <VcButton @click="redirectToSSO(provider)"> Sign in with {{ provider.loginProvider }} </VcButton>
     </div>
   </div>
 </template>

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

@@ -12,16 +12,16 @@ Registers Core Web Vitals observers (FCP, LCP, CLS, INP, TTFB) and reports metri
 ## Quick Start
 
 ```typescript
-import { useWebVitals } from '@vc-shell/framework';
+import { useWebVitals } from "@vc-shell/framework";
 
 // Option 1: Default behavior -- logs to console.warn in dev mode, silent in production
 useWebVitals();
 
 // Option 2: Custom callback for production analytics
 useWebVitals((metric) => {
-  analytics.track('web-vital', {
-    name: metric.name,     // "FCP", "LCP", "CLS", "INP", or "TTFB"
-    value: metric.value,   // milliseconds (or unitless for CLS)
+  analytics.track("web-vital", {
+    name: metric.name, // "FCP", "LCP", "CLS", "INP", or "TTFB"
+    value: metric.value, // milliseconds (or unitless for CLS)
     rating: metric.rating, // "good", "needs-improvement", or "poor"
   });
 });
@@ -32,7 +32,7 @@ Call this once after `app.mount()` in your application entry point:
 ```typescript
 // main.ts
 const app = createApp(App);
-app.mount('#app');
+app.mount("#app");
 
 // Register Web Vitals observers after mount
 useWebVitals();
@@ -42,17 +42,17 @@ useWebVitals();
 
 ### Parameters
 
-| Parameter | Type | Required | Description |
-|---|---|---|---|
-| `callback` | `(metric: IWebVitalsMetric) => void` | No | Custom handler for each metric. Defaults to `console.warn` formatted output in dev mode; no-op in production. |
+| Parameter  | Type                                 | Required | Description                                                                                                   |
+| ---------- | ------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------- |
+| `callback` | `(metric: IWebVitalsMetric) => void` | No       | Custom handler for each metric. Defaults to `console.warn` formatted output in dev mode; no-op in production. |
 
 ### IWebVitalsMetric
 
-| Field | Type | Description |
-|---|---|---|
-| `name` | `string` | Metric name: `"FCP"` (First Contentful Paint), `"LCP"` (Largest Contentful Paint), `"CLS"` (Cumulative Layout Shift), `"INP"` (Interaction to Next Paint), `"TTFB"` (Time to First Byte) |
-| `value` | `number` | Metric value in milliseconds for all metrics except CLS, which is a unitless score |
-| `rating` | `"good" \| "needs-improvement" \| "poor"` | Performance rating based on Google's thresholds (e.g., LCP < 2500ms = "good") |
+| Field    | Type                                      | Description                                                                                                                                                                              |
+| -------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`   | `string`                                  | Metric name: `"FCP"` (First Contentful Paint), `"LCP"` (Largest Contentful Paint), `"CLS"` (Cumulative Layout Shift), `"INP"` (Interaction to Next Paint), `"TTFB"` (Time to First Byte) |
+| `value`  | `number`                                  | Metric value in milliseconds for all metrics except CLS, which is a unitless score                                                                                                       |
+| `rating` | `"good" \| "needs-improvement" \| "poor"` | Performance rating based on Google's thresholds (e.g., LCP < 2500ms = "good")                                                                                                            |
 
 ### Returns
 
@@ -75,7 +75,7 @@ The default callback formats CLS values to 4 decimal places (since CLS is a dime
 ## Recipe: Sending Web Vitals to Application Insights
 
 ```typescript
-import { useWebVitals, useAppInsights } from '@vc-shell/framework';
+import { useWebVitals, useAppInsights } from "@vc-shell/framework";
 
 const { appInsights } = useAppInsights();
 
@@ -96,14 +96,14 @@ This sends each Web Vital as a custom metric to Application Insights, where you
 ## Recipe: Conditional Reporting Based on Rating
 
 ```typescript
-import { useWebVitals } from '@vc-shell/framework';
+import { useWebVitals } from "@vc-shell/framework";
 
 useWebVitals((metric) => {
   // Only report poor metrics to reduce noise
-  if (metric.rating === 'poor') {
-    fetch('/api/telemetry/web-vitals', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
+  if (metric.rating === "poor") {
+    fetch("/api/telemetry/web-vitals", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
         metric: metric.name,
         value: metric.value,

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

@@ -14,15 +14,15 @@ Also exports `provideWidgetService()` for framework-level initialization and `re
 ## Quick Start
 
 ```typescript
-import { useWidgets } from '@vc-shell/framework';
+import { useWidgets } from "@vc-shell/framework";
 
 const widgetService = useWidgets();
 
 // Query all widgets registered for a specific blade
-const widgets = widgetService.getWidgets('order-details');
+const widgets = widgetService.getWidgets("order-details");
 
 // Check if a widget is currently active (visible and expanded)
-if (widgetService.isActiveWidget('order-status-widget')) {
+if (widgetService.isActiveWidget("order-status-widget")) {
   // widget is currently in focus
 }
 ```
@@ -35,29 +35,29 @@ None.
 
 ### Returns (`IWidgetService`)
 
-| Property / Method | Type | Description |
-|-------------------|------|-------------|
-| `registerWidget` | `(widget: IWidget, bladeId: string) => void` | Registers a widget for a specific blade. The widget will appear in that blade's widget area. |
-| `unregisterWidget` | `(widgetId: string, bladeId: string) => void` | Removes a widget from a blade by ID. |
-| `getWidgets` | `(bladeId: string) => IWidget[]` | Returns all widgets registered for a specific blade. |
-| `clearBladeWidgets` | `(bladeId: string) => void` | Removes all widgets for a blade (used during blade teardown). |
-| `registeredWidgets` | `IWidgetRegistration[]` | All widget registrations across all blades. |
-| `isActiveWidget` | `(id: string) => boolean` | Checks if a widget is currently active (selected/expanded). |
-| `setActiveWidget` | `(args) => void` | Sets a widget as active with its exposed instance. |
-| `updateActiveWidget` | `() => void` | Triggers the active widget's update function. Deprecated -- use headless widgets instead. |
-| `isWidgetRegistered` | `(id: string) => boolean` | Checks if a widget ID exists in any blade's registry. |
-| `updateWidget` | `(args) => void` | Updates properties of a registered widget (trigger, badge, etc.). |
-| `resolveWidgetProps` | `(widget, bladeData) => Record<string, unknown>` | Resolves widget props from blade data. Deprecated. |
-| `getExternalWidgetsForBlade` | `(bladeId: string) => IExternalWidgetRegistration[]` | Gets external widgets that target a specific blade (registered by other modules). |
-| `getAllExternalWidgets` | `() => IExternalWidgetRegistration[]` | Gets all registered external widgets across all modules. |
+| Property / Method            | Type                                                 | Description                                                                                  |
+| ---------------------------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `registerWidget`             | `(widget: IWidget, bladeId: string) => void`         | Registers a widget for a specific blade. The widget will appear in that blade's widget area. |
+| `unregisterWidget`           | `(widgetId: string, bladeId: string) => void`        | Removes a widget from a blade by ID.                                                         |
+| `getWidgets`                 | `(bladeId: string) => IWidget[]`                     | Returns all widgets registered for a specific blade.                                         |
+| `clearBladeWidgets`          | `(bladeId: string) => void`                          | Removes all widgets for a blade (used during blade teardown).                                |
+| `registeredWidgets`          | `IWidgetRegistration[]`                              | All widget registrations across all blades.                                                  |
+| `isActiveWidget`             | `(id: string) => boolean`                            | Checks if a widget is currently active (selected/expanded).                                  |
+| `setActiveWidget`            | `(args) => void`                                     | Sets a widget as active with its exposed instance.                                           |
+| `updateActiveWidget`         | `() => void`                                         | Triggers the active widget's update function. Deprecated -- use headless widgets instead.    |
+| `isWidgetRegistered`         | `(id: string) => boolean`                            | Checks if a widget ID exists in any blade's registry.                                        |
+| `updateWidget`               | `(args) => void`                                     | Updates properties of a registered widget (trigger, badge, etc.).                            |
+| `resolveWidgetProps`         | `(widget, bladeData) => Record<string, unknown>`     | Resolves widget props from blade data. Deprecated.                                           |
+| `getExternalWidgetsForBlade` | `(bladeId: string) => IExternalWidgetRegistration[]` | Gets external widgets that target a specific blade (registered by other modules).            |
+| `getAllExternalWidgets`      | `() => IExternalWidgetRegistration[]`                | Gets all registered external widgets across all modules.                                     |
 
 ### Additional Exports
 
-| Export | Description |
-|--------|-------------|
-| `provideWidgetService()` | Creates and provides the widget service via Vue injection. Idempotent -- returns existing service if already provided. Cleans up via `onScopeDispose`. |
-| `registerWidget(widget, bladeId)` | Global pre-registration. Widgets registered this way are picked up when `provideWidgetService()` creates the service. Use in module `install()`. |
-| `registerExternalWidget(registration)` | Global pre-registration for cross-module widgets. These widgets are rendered in blades owned by other modules. |
+| Export                                 | Description                                                                                                                                            |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `provideWidgetService()`               | Creates and provides the widget service via Vue injection. Idempotent -- returns existing service if already provided. Cleans up via `onScopeDispose`. |
+| `registerWidget(widget, bladeId)`      | Global pre-registration. Widgets registered this way are picked up when `provideWidgetService()` creates the service. Use in module `install()`.       |
+| `registerExternalWidget(registration)` | Global pre-registration for cross-module widgets. These widgets are rendered in blades owned by other modules.                                         |
 
 ## How It Works
 
@@ -75,20 +75,20 @@ The service tracks active widgets (which widget is currently expanded/focused) s
 
 ```typescript
 // my-module/index.ts
-import { registerWidget } from '@vc-shell/framework';
-import { markRaw } from 'vue';
-import OrderStatusWidget from './widgets/OrderStatusWidget.vue';
+import { registerWidget } from "@vc-shell/framework";
+import { markRaw } from "vue";
+import OrderStatusWidget from "./widgets/OrderStatusWidget.vue";
 
 export default {
   install() {
     registerWidget(
       {
-        id: 'order-status',
-        title: 'Order Status',
+        id: "order-status",
+        title: "Order Status",
         component: markRaw(OrderStatusWidget),
-        icon: 'fas fa-clipboard-check',
+        icon: "fas fa-clipboard-check",
       },
-      'order-details', // blade ID where this widget appears
+      "order-details", // blade ID where this widget appears
     );
   },
 };
@@ -100,18 +100,18 @@ A shipping module can add a widget to the order module's detail blade:
 
 ```typescript
 // shipping-module/index.ts
-import { registerExternalWidget } from '@vc-shell/framework';
-import { markRaw } from 'vue';
-import ShippingTracker from './widgets/ShippingTracker.vue';
+import { registerExternalWidget } from "@vc-shell/framework";
+import { markRaw } from "vue";
+import ShippingTracker from "./widgets/ShippingTracker.vue";
 
 export default {
   install() {
     registerExternalWidget({
-      widgetId: 'shipping-tracker',
-      bladeId: 'order-details', // target blade from another module
+      widgetId: "shipping-tracker",
+      bladeId: "order-details", // target blade from another module
       component: markRaw(ShippingTracker),
-      title: 'Shipping',
-      icon: 'fas fa-truck',
+      title: "Shipping",
+      icon: "fas fa-truck",
     });
   },
 };
@@ -121,21 +121,16 @@ export default {
 
 ```vue
 <script setup lang="ts">
-import { useWidgets } from '@vc-shell/framework';
-import { computed } from 'vue';
+import { useWidgets } from "@vc-shell/framework";
+import { computed } from "vue";
 
 const props = defineProps<{ bladeId: string }>();
 const widgetService = useWidgets();
 
 const bladeWidgets = computed(() => widgetService.getWidgets(props.bladeId));
-const externalWidgets = computed(() =>
-  widgetService.getExternalWidgetsForBlade(props.bladeId),
-);
-
-const allWidgets = computed(() => [
-  ...bladeWidgets.value,
-  ...externalWidgets.value,
-]);
+const externalWidgets = computed(() => widgetService.getExternalWidgetsForBlade(props.bladeId));
+
+const allWidgets = computed(() => [...bladeWidgets.value, ...externalWidgets.value]);
 </script>
 ```