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

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

@@ -75,21 +75,21 @@ 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 \| { succeeded: boolean; error?: any }>` | 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
 
@@ -139,7 +139,7 @@ async function handleReset() {
   // 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?.map((e) => e.description).join(", ") ?? "Password does not meet requirements.";
     return;
   }
 
@@ -167,7 +167,7 @@ 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.hasLoginForm);
 });
 </script>
 
@@ -181,10 +181,10 @@ onMounted(async () => {
     </form>
 
     <div
-      v-for="provider in loginTypes.filter((t) => t.loginProvider !== 'password')"
-      :key="provider.loginProvider"
+      v-for="provider in loginTypes.filter((t) => !t.hasLoginForm)"
+      :key="provider.authenticationType"
     >
-      <VcButton @click="redirectToSSO(provider)"> Sign in with {{ provider.loginProvider }} </VcButton>
+      <VcButton @click="redirectToSSO(provider)"> Sign in with {{ provider.authenticationType }} </VcButton>
     </div>
   </div>
 </template>

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

@@ -6,7 +6,7 @@ group: services
 
 # useWidgets
 
-Provides access to the `IWidgetService` singleton for managing blade widget registrations, activation state, and external widgets. This is the low-level composable for direct widget service interaction. It exposes the full widget lifecycle API: registering widgets to specific blades, querying registered widgets, tracking active widget state, and managing external (cross-module) widget registrations.
+Provides access to the `IWidgetService` singleton for managing blade widget registrations and external widgets. This is the low-level composable for direct widget service interaction. It exposes the widget lifecycle API: registering widgets to specific blades, querying and updating registered widgets, and managing external (cross-module) widget registrations.
 
 Also exports `provideWidgetService()` for framework-level initialization and `registerWidget()` / `registerExternalWidget()` for global pre-registration before the service is created.
 
@@ -27,10 +27,8 @@ const widgetService = useWidgets();
 // Query all widgets registered for a specific blade
 const widgets = widgetService.getWidgets("order-details");
 
-// Check if a widget is currently active (visible and expanded)
-if (widgetService.isActiveWidget("order-status-widget")) {
-  // widget is currently in focus
-}
+// Query external widgets contributed by other modules
+const externalWidgets = widgetService.getExternalWidgetsForBlade("order-details");
 ```
 
 ## API
@@ -41,21 +39,15 @@ 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.                                         |
+| `updateWidget`               | `({ id, bladeId, widget }: { id: string; bladeId: string; widget: Partial<IWidget> }) => void` | Updates properties of a registered widget (trigger, badge, etc.).                            |
+| `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.                                     |
+| `cloneWidget`                | `<T extends IWidget \| IExternalWidgetRegistration>(widget: T) => T`                           | Returns a deep-ish clone of a widget or external widget registration.                        |
 
 ### Additional Exports
 
@@ -77,7 +69,7 @@ The widget system has three layers:
 
 3. **Runtime access** (`useWidgets()`): Components inject the service and use it to query or modify widget state.
 
-The service tracks active widgets (which widget is currently expanded/focused) separately from registrations, enabling the widget panel to highlight the active widget and call its update function.
+The service stores widget registrations per blade and returns cloned widget definitions on query. It does not track active/expanded/focused state.
 
 <!-- internal:end -->
 
@@ -117,11 +109,10 @@ import ShippingTracker from "./widgets/ShippingTracker.vue";
 export default {
   install() {
     registerExternalWidget({
-      widgetId: "shipping-tracker",
-      bladeId: "order-details", // target blade from another module
+      id: "shipping-tracker",
+      targetBlades: ["order-details"], // target blades from other modules
       component: markRaw(ShippingTracker),
       title: "Shipping",
-      icon: "fas fa-truck",
     });
   },
 };

package/runtime/knowledge/docs/core/directives/loading/loading.docs.md

@@ -25,7 +25,7 @@ Unlike a standalone loading component, `v-loading` scopes the overlay to the ele
 | ----------------------- | ---------------- | ------------------------------------ |
 | `v-loading="true"`      | `boolean`        | Show/hide the loading overlay        |
 | `v-loading="options"`   | `LoadingOptions` | Show with configuration (see below)  |
-| `v-loading:1000="true"` | `arg: string`    | Set custom z-index (default: `9999`) |
+| `v-loading:1000="true"` | `arg: string`    | Set custom z-index (default: `9000`) |
 
 ### LoadingOptions
 
@@ -108,7 +108,7 @@ async function loadOrder() {
   <!-- Use a lower z-index so popups can render above the spinner -->
   <div v-loading:500="isLoading">Content</div>
 
-  <!-- Default z-index is 9999 -->
+  <!-- Default z-index is 9000 -->
   <div v-loading="isLoading">Content</div>
 </template>
 ```

package/runtime/knowledge/docs/core/notifications/composables/useBladeNotifications.docs.md

@@ -0,0 +1,183 @@
+---
+title: useBladeNotifications
+category: composables
+group: notifications
+---
+
+# useBladeNotifications
+
+Subscribes a blade to one or more push-notification types from the platform's SignalR stream. The composable returns a reactive list of matching unread messages, an unread count, and a `markAsRead` action. The subscription is bound to the current effect scope, so it disappears the moment the blade closes — no manual unsubscribe.
+
+This is the **Level 2** entry point in the notification system. Level 1 — `defineAppModule({ notifications })` — registers types globally with their toast configuration and is the always-on path. Level 2 layers blade-specific behavior on top of that: refresh a list, update a progress UI, mark a job complete.
+
+## When to use
+
+- A list blade needs to refresh when an entity is created, updated, or deleted elsewhere.
+- A long-running operation has a dedicated blade and the blade should update as `processedCount` / `errorCount` flow in.
+- A blade wants to surface an inline "N new" badge for messages of a specific type.
+- When NOT to use: app-wide toasts already come from the Level 1 module config — the blade does not need to subscribe just to show a toast. Reach for the blade subscription only when you also need to _react_ to the event in code.
+
+## Quick Start
+
+```ts
+import { useBladeNotifications } from "@vc-shell/framework";
+
+useBladeNotifications({
+  types: ["OfferDeletedDomainEvent"],
+  onMessage: () => reload(),
+});
+```
+
+That is the full recipe for "refresh this list when an offer is deleted somewhere in the app." The handler runs once per matching message; the framework cleans up the subscription when the blade unmounts.
+
+## API
+
+### Parameters
+
+```typescript
+interface BladeNotificationOptions<T extends PushNotification = PushNotification> {
+  types: string[];
+  filter?: (msg: T) => boolean;
+  onMessage?: (msg: T) => void;
+}
+```
+
+| Field       | Type                  | Required | Description                                                                                             |
+| ----------- | --------------------- | -------- | ------------------------------------------------------------------------------------------------------- |
+| `types`     | `string[]`            | Yes      | Notification types to subscribe to. Must match the `notifyType` field on incoming messages.             |
+| `filter`    | `(msg: T) => boolean` | No       | Narrow the subscription further (for example, only events for the entity this blade is editing).        |
+| `onMessage` | `(msg: T) => void`    | No       | Callback fired once per matching message. Use it to refresh data, mark progress, or update local state. |
+
+### Returns
+
+```typescript
+interface BladeNotificationReturn<T extends PushNotification = PushNotification> {
+  messages: ComputedRef<T[]>;
+  unreadCount: ComputedRef<number>;
+  markAsRead: (msg: T) => void;
+}
+```
+
+| Property      | Type                  | Description                                                                                                             |
+| ------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `messages`    | `ComputedRef<T[]>`    | Realtime messages matching `types` and `filter` that are still unread. Updates reactively as new messages arrive.       |
+| `unreadCount` | `ComputedRef<number>` | `messages.value.length`. Bind to a badge.                                                                               |
+| `markAsRead`  | `(msg: T) => void`    | Mark a specific message as read. Removes it from `messages` (and reduces the global unread badge in the bell dropdown). |
+
+## Typed payloads
+
+Notification payloads often extend `PushNotification` with domain fields. Pass the type parameter so `onMessage` and `messages` are typed:
+
+```ts
+import type { PushNotification } from "@vc-shell/framework";
+
+interface ImportPushNotification extends PushNotification {
+  jobId: string;
+  profileId: string;
+  profileName?: string;
+  processedCount: number;
+  errorCount: number;
+  finished: boolean;
+}
+
+const { messages, markAsRead } = useBladeNotifications<ImportPushNotification>({
+  types: ["ImportPushNotification"],
+  onMessage: (message) => {
+    if (message.finished) {
+      reload();
+      markAsRead(message);
+    }
+  },
+});
+```
+
+## Common patterns
+
+### Refresh a list on any matching event
+
+```ts
+useBladeNotifications({
+  types: ["OfferDeletedDomainEvent"],
+  onMessage: () => reload(),
+});
+```
+
+Drop-in for a list blade that needs to stay in sync with deletions happening anywhere in the app.
+
+### Filter to the entity this blade owns
+
+```ts
+useBladeNotifications<ImportPushNotification>({
+  types: ["ImportPushNotification"],
+  onMessage: (message) => {
+    if (message.profileId !== param.value) return; // not our job
+    if (!message.finished) updateProgress(message);
+    else finalizeImport(message);
+  },
+});
+```
+
+Two open import blades will both receive the stream; each one filters by its own `profileId` so they do not step on each other.
+
+### Drive a manual progress toast
+
+When the platform sends progress updates for a long-running job, you may want to render one persistent toast that you update as messages arrive — instead of letting Level 1 spawn a new toast per event.
+
+Set the Level 1 type to `silent` and drive the toast yourself:
+
+```ts title="src/modules/import/index.ts"
+defineAppModule({
+  notifications: {
+    ImportPushNotification: { toast: { mode: "silent" } },
+  },
+  // ...
+});
+```
+
+```ts title="pages/import-process.vue"
+import { useBladeNotifications, notification } from "@vc-shell/framework";
+
+let toastId: string | undefined;
+
+useBladeNotifications<ImportPushNotification>({
+  types: ["ImportPushNotification"],
+  onMessage: (message) => {
+    const content = message.profileName ? `${message.profileName}: ${message.title}` : message.title;
+
+    if (!toastId) {
+      toastId = notification(content, { timeout: false });
+    } else if (!message.finished) {
+      notification.update(toastId, { content });
+    } else {
+      notification.update(toastId, {
+        content,
+        timeout: 5000,
+        type: message.errorCount ? "error" : "success",
+        onClose: () => (toastId = undefined),
+      });
+    }
+  },
+});
+```
+
+The `notification()` helper returns the toast id; `notification.update` mutates it in place. The bell-dropdown history still grows — `silent` only suppresses the auto-toast.
+
+## Lifecycle
+
+`useBladeNotifications` calls `useNotificationStore().subscribe(...)` and registers `onScopeDispose(unsub)` against the current effect scope. Inside a Vue `setup()` (component or `<script setup>`) the scope is the component's; the subscription dies with the component.
+
+If you call the composable from a manually managed `effectScope()`, the cleanup runs when that scope is stopped. Calling it outside any scope is a bug — the subscription would never be released.
+
+## Tips
+
+- **Listen, do not declare.** `useBladeNotifications` does not register the notification type with the framework. Types must already be declared by some module via `defineAppModule({ notifications })`, otherwise nothing reaches `onMessage`.
+- **`messages` shows only unread.** `markAsRead(msg)` removes a message from `messages` (and from the global unread count). The notification stays in history.
+- **One subscription per call.** Calling `useBladeNotifications` multiple times in the same blade creates independent subscriptions. Combine handlers if you only need one.
+- **Type strings are case-sensitive.** The string in `types` must exactly equal the `notifyType` field on incoming messages.
+
+## Related
+
+- [useNotificationStore](./useNotificationStore.md) — direct store access for app-shell features (dropdown, badge).
+- [useNotificationContext](./useNotificationContext.md) — read the current notification inside a custom template.
+- [useBroadcastFilter](./useBroadcastFilter.md) — control which `SendSystemEvents` broadcasts reach the store.
+- [Notifications overview.](../notifications.md)

package/runtime/knowledge/docs/core/notifications/composables/useBroadcastFilter.docs.md

@@ -0,0 +1,117 @@
+---
+title: useBroadcastFilter
+category: composables
+group: notifications
+---
+
+# useBroadcastFilter
+
+Controls which **broadcast** push notifications reach the store. The platform SignalR hub delivers messages through two channels: `Send` (targeted to a specific user) and `SendSystemEvents` (broadcast to everyone connected). Broadcasts run through the filter installed here; targeted messages are always accepted.
+
+This is the standard mechanism for scoping a multi-tenant app — show a seller only the broadcasts that mention them, hide events from other tenants. Without a filter every broadcast lands in every user's history.
+
+## When to use
+
+- Multi-tenant apps where the same broadcast topic carries events for different tenants (sellers, organizations, departments) and each user should only see their slice.
+- Apps that want to drop noisy maintenance broadcasts for non-admin roles. (Note: `IndexProgressPushNotification` is already globally dropped via `EXCLUDED_NOTIFICATION_TYPES` and needs no filter.)
+- When NOT to use: filtering targeted notifications. The platform already delivers `Send` messages only to the addressed user; `useBroadcastFilter` does not see them.
+
+## Quick Start
+
+```ts
+import { useBroadcastFilter, useUser } from "@vc-shell/framework";
+import { onMounted } from "vue";
+
+const { user } = useUser();
+const { setBroadcastFilter } = useBroadcastFilter();
+
+onMounted(() => {
+  setBroadcastFilter((msg) => msg.creator === user.value?.userName);
+});
+```
+
+Install the filter once at app bootstrap (or whenever the active user changes). Every incoming broadcast is run through it; messages that return `false` are dropped before they touch history, toasts, or subscribers.
+
+## API
+
+### Returns
+
+```typescript
+interface UseBroadcastFilterReturn {
+  setBroadcastFilter(fn: (msg: PushNotification) => boolean): void;
+  clearBroadcastFilter(): void;
+}
+```
+
+| Method                 | Type                                           | Description                                                                               |
+| ---------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `setBroadcastFilter`   | `((msg: PushNotification) => boolean) => void` | Install the filter. Replaces any previous filter — there is at most one active at a time. |
+| `clearBroadcastFilter` | `() => void`                                   | Remove the filter. All subsequent broadcasts are accepted.                                |
+
+The filter returns `true` to **accept** a message, `false` to **drop** it.
+
+## Common patterns
+
+### Scope by current user
+
+```ts
+onMounted(() => {
+  setBroadcastFilter((msg) => msg.creator === user.value?.userName);
+});
+```
+
+`creator` is the user that originated the event on the platform side. This is the canonical "show me my own broadcasts" filter in multi-tenant back-office apps.
+
+### Scope by tenant id
+
+```ts
+onMounted(() => {
+  setBroadcastFilter((msg) => (msg as TenantPush).sellerId === currentSellerId.value);
+});
+```
+
+When your broadcast payloads carry a tenant id, gate on it instead of `creator`. The cast clarifies typing without expanding `PushNotification` for every caller.
+
+### Re-install on user switch
+
+```ts
+import { watch } from "vue";
+
+watch(
+  () => user.value?.userName,
+  (name) => {
+    if (!name) clearBroadcastFilter();
+    else setBroadcastFilter((msg) => msg.creator === name);
+  },
+  { immediate: true },
+);
+```
+
+If the app supports user switching without a full reload (impersonation, multi-account), re-install the filter on every change. There is only one slot — installing again replaces the previous filter.
+
+### Drop a noisy type entirely
+
+```ts
+setBroadcastFilter((msg) => msg.notifyType !== "BulkActionPushNotification");
+```
+
+Broadcast-only suppression. To suppress targeted messages too, set `toast: false` or `toast: { mode: "silent" }` on the type's `defineAppModule({ notifications })` config — that controls the toast surface; the history still records the event.
+
+## Behavior
+
+- The filter applies only to messages ingested with the `broadcast: true` flag (the SignalR `SendSystemEvents` channel).
+- Targeted messages (`Send`) bypass the filter entirely.
+- Installing a filter mid-session does not retroactively prune `history` or `realtime`. Past broadcasts stay; only future ones are filtered.
+- The filter is a single function. To compose multiple predicates, `&&` them inside one callback.
+
+## Tips
+
+- **Install once, early.** Setting the filter in `App.vue` `onMounted` (after authentication) is the canonical placement, so messages arriving before the first blade mounts are already scoped.
+- **A throwing predicate is not caught.** `ingest` calls the filter without a try/catch, so an exception propagates up through ingestion — it is not logged and the message is not silently dropped. Guard field access inside the predicate (e.g. optional chaining) when reading potentially missing fields.
+- **Do not query the store from inside the filter.** The store is `useBroadcastFilter`'s parent — calling back into it during ingestion causes re-entrancy.
+
+## Related
+
+- [useNotificationStore](./useNotificationStore.md) — exposes the same set/clear methods plus the rest of the store API.
+- [useBladeNotifications](./useBladeNotifications.md) — blade-scoped subscription that sees broadcasts after filtering.
+- [Notifications concept page — broadcasts.](../../concepts/notifications.md#broadcast-vs-targeted)

package/runtime/knowledge/docs/core/notifications/composables/useNotificationContext.docs.md

@@ -0,0 +1,150 @@
+---
+title: useNotificationContext
+category: composables
+group: notifications
+---
+
+# useNotificationContext
+
+Reads the current `PushNotification` payload inside a custom notification template. The framework provides the message via Vue's `inject()` from the dropdown or toast surface that hosts the template — the composable returns a reactive `ComputedRef` over it.
+
+This is the one piece you write when a notification type registered with `defineAppModule({ notifications: { Type: { template } } })` needs a richer rendering than the default `NotificationTemplate` chrome — for example, formatting a domain-specific status, deriving a colored accent, or wiring a click handler that opens the relevant blade.
+
+## When to use
+
+- Implementing the `template` component for a notification type registered through `defineAppModule({ notifications })`.
+- Reading typed payload fields (status, entity name, job id) to drive the template's layout, color, or actions.
+- When NOT to use: anywhere outside a notification template. The composable throws if the inject context is not present.
+
+## Quick Start
+
+```vue
+<script lang="ts" setup>
+import { PushNotification, NotificationTemplate, useNotificationContext } from "@vc-shell/framework";
+import { computed } from "vue";
+
+interface IOrderPushNotification extends PushNotification {
+  orderId: string;
+  total: number;
+}
+
+const notificationRef = useNotificationContext<IOrderPushNotification>();
+const notification = computed(() => notificationRef.value);
+</script>
+
+<template>
+  <NotificationTemplate
+    :title="notification.title ?? ''"
+    :notification="notification"
+  >
+    <p>Order {{ notification.orderId }} — ${{ notification.total }}</p>
+  </NotificationTemplate>
+</template>
+```
+
+## API
+
+### Parameters
+
+None. The composable is always called without arguments. Generic type parameter narrows the payload shape:
+
+```typescript
+function useNotificationContext<T extends PushNotification = PushNotification>(): ComputedRef<T>;
+```
+
+### Returns
+
+`ComputedRef<T>` — reactive reference to the current `PushNotification` (or your extended subtype via the generic). Update reactively if the same template instance is reused for a refreshed payload (for example, when a progress message is updated through `notification.update`).
+
+## Common patterns
+
+### Compute display strings from payload fields
+
+```vue
+<script lang="ts" setup>
+import { PushNotification, useNotificationContext, NotificationTemplate } from "@vc-shell/framework";
+import { computed } from "vue";
+import { useI18n } from "vue-i18n";
+
+interface IProductPush extends PushNotification {
+  productName?: string;
+  newStatus?: string;
+}
+
+const ctx = useNotificationContext<IProductPush>();
+const notification = computed(() => ctx.value);
+const { t } = useI18n({ useScope: "global" });
+
+const title = computed(() => (notification.value.productName ? `${t("PRODUCTS.PUSH.PRODUCT")} "${notification.value.productName}" ${t("PRODUCTS.PUSH.UPDATE")}` : (notification.value.title ?? "")));
+</script>
+```
+
+### Open a blade on click
+
+```vue
+<script lang="ts" setup>
+import { useBlade, useNotificationContext, NotificationTemplate } from "@vc-shell/framework";
+import { computed } from "vue";
+
+const { openBlade } = useBlade();
+const ctx = useNotificationContext<IOrderPush>();
+const notification = computed(() => ctx.value);
+
+function onClick() {
+  if (!notification.value.orderId) return;
+  openBlade({ name: "OrderDetails", param: notification.value.orderId });
+}
+</script>
+
+<template>
+  <NotificationTemplate
+    :title="notification.title ?? ''"
+    :notification="notification"
+    @click="onClick"
+  >
+    <p>{{ notification.description }}</p>
+  </NotificationTemplate>
+</template>
+```
+
+`NotificationTemplate` re-emits the click event so the host (dropdown row, toast) can close itself before your handler runs.
+
+### Color the template by status
+
+```ts
+const notificationStyle = computed(() => {
+  switch (notification.value.newStatus) {
+    case "Approved":
+      return { color: "var(--success-400)", icon: "lucide-check-circle" };
+    case "RequestChanges":
+      return { color: "var(--danger-400)", icon: "lucide-alert-circle" };
+    case "WaitForApproval":
+      return { color: "var(--warning-600)", icon: "lucide-clock" };
+    default:
+      return { color: "var(--primary-400)", icon: "lucide-bell" };
+  }
+});
+```
+
+`NotificationTemplate` accepts `:color` and `:icon` props that line up with these computeds — the dropdown row and the toast use the same template, so the styling stays consistent across surfaces.
+
+## Where the template runs
+
+Notification templates render in two places:
+
+- **In the bell dropdown**, as one row in the history list.
+- **As a toast**, when the type's `toast.mode` is `"auto"` or `"progress"` (set the mode to `"silent"` to render only in the dropdown).
+
+The template component must be **the same** in both — register it once on `defineAppModule({ notifications })` and the framework reuses it everywhere.
+
+## Tips
+
+- **Always type the generic.** `useNotificationContext<MyPushType>()` enables autocompletion on payload fields. Without it everything degrades to `PushNotification`.
+- **`computed(() => ctx.value)` is idiomatic** in the example apps because consumers want a regular `Ref` shape to pass into child components and template bindings. Direct access via `ctx.value` is fine too.
+- **Do not subscribe inside a template.** The template renders one message; if you need to react to other notifications, do that in a blade with `useBladeNotifications`.
+
+## Related
+
+- [useBladeNotifications](./useBladeNotifications.md) — subscribe to types inside a blade.
+- [useNotificationStore](./useNotificationStore.md) — access the underlying store.
+- [Notifications concept page.](../../concepts/notifications.md)