@vc-shell/vc-app-skill 2.0.10-pr247.f47cc74 → 2.0.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vc-shell/vc-app-skill",
-  "version": "2.0.10-pr247.f47cc74",
+  "version": "2.0.11",
   "description": "AI coding skill for scaffolding and generating VirtoCommerce Shell applications. Works with Claude Code, OpenCode, Gemini, Codex, Cursor.",
   "bin": "./bin/install.cjs",
   "files": [

package/runtime/VERSION

@@ -1 +1 @@
-2.0.10
+2.0.11

package/runtime/knowledge/docs/_BUILD_HASH.md

@@ -1 +1 @@
-Synced from framework at commit fde3a68db on 2026-06-15T11:34:22.939Z
+Synced from framework at commit f2225cc27 on 2026-06-22T15:40:33.524Z

package/runtime/knowledge/docs/core/blade-navigation/table-query-state/useTableQueryState.docs.md

@@ -0,0 +1,95 @@
+---
+title: useTableQueryState
+category: composables
+group: data
+---
+
+# useTableQueryState
+
+Reads the table view state (`sort`, `search`, `page`) that `VcDataTable` persists to the URL query for URL-addressable blades. A list page calls `read()` in `setup` to seed its own refs from the restored state before its loader runs, so a reload makes one request.
+
+Read-only: writing the view state to the URL stays inside `VcDataTable`. This composable only exposes the restored values to the page.
+
+## When to Use
+
+- A list blade is URL-addressable (workspace or routable) and uses `VcDataTable` with a `state-key`
+- You want a single, coordinated load on reload (sort + search + page restored together)
+- You are wiring the page's combined loader watcher and need the restored seed values
+
+## When NOT to Use
+
+- The table is standalone or its blade has no URL — there is nothing to restore (`read()` returns `{}`)
+- You only need the live view state — that already lives in your own `sortField`/`searchValue`/`currentPage` refs
+- You want to _write_ to the URL — that is automatic; do not persist manually
+
+## Basic Usage
+
+```ts
+import { ref, watch } from "vue";
+import { useDataTableSort, useTableQueryState, useFunctions } from "@vc-shell/framework";
+
+const PAGE_SIZE = 20;
+const { debounce } = useFunctions();
+const { sortField, sortOrder, sortExpression } = useDataTableSort({
+  initialField: "createdDate",
+  initialDirection: "DESC",
+});
+const searchValue = ref<string>();
+const currentPage = ref(1);
+
+// Seed refs from the URL before the loader runs.
+const restored = useTableQueryState("offers_list").read();
+if (restored.sort) {
+  const [field, dir] = restored.sort.split(":");
+  sortField.value = field;
+  sortOrder.value = dir === "DESC" ? -1 : 1;
+}
+if (restored.search) searchValue.value = restored.search;
+if (restored.page) currentPage.value = restored.page;
+
+function load() {
+  return loadItems({
+    sort: sortExpression.value,
+    keyword: searchValue.value || undefined,
+    skip: (currentPage.value - 1) * PAGE_SIZE,
+  });
+}
+
+load();
+watch(searchValue, () => (currentPage.value = 1));
+watch([sortExpression, searchValue, currentPage], debounce(load, 300));
+```
+
+## API
+
+### Parameters
+
+| Parameter  | Type                  | Default     | Description                                                               |
+| ---------- | --------------------- | ----------- | ------------------------------------------------------------------------- |
+| `stateKey` | `string \| undefined` | `undefined` | The same `state-key` passed to `VcDataTable` for this table (namespacing) |
+
+### Returns
+
+| Property | Type                    | Description                                                                                            |
+| -------- | ----------------------- | ------------------------------------------------------------------------------------------------------ |
+| `read`   | `() => TableQueryPatch` | Reads the restored `{ sort?, search?, page? }` from the URL. Returns `{}` when no service is available |
+
+`TableQueryPatch`: `{ sort?: string; search?: string; page?: number }` — `sort` is a `"field:ASC"` / `"field:DESC"` expression, `page` is 1-based.
+
+## Details
+
+- **Read in `setup`**: `VcDataTable` does not emit restore events on init; the page reads the state and seeds its refs in `setup`. This avoids a separate load per restored field.
+- **No-op without a service**: When no blade provides the persistence service (standalone table, non-URL blade), `read()` returns `{}`, so you can call it unconditionally.
+- **Write-back is automatic**: View state → URL (debounced `router.replace`) is handled by `VcDataTable` via `useTableQueryPersistence`. Pages do not persist manually.
+
+## Tips
+
+- Call `read()` once, synchronously, before the loader. Seeding after it runs causes an extra load.
+- Use `useDataTablePagination`'s `setPage(n)` to seed the page without firing `onPageChange`.
+- Pass the same `state-key` you give `VcDataTable`, so the URL keys match.
+
+## Related
+
+- [`useDataTableSort`](../../../ui/composables/useDataTableSort.docs.md) — sort state composable for `VcDataTable`
+- [`useDataTablePagination`](../../../ui/composables/useDataTablePagination.docs.md) — pagination state composable (`setPage` for restore seed)
+- `VcDataTable` → _URL query persistence_ — the write-back side of this contract

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

@@ -115,6 +115,6 @@ This results in page names like `[Operations Console] Dashboard` instead of just
 ## Related
 
 - `vue3-application-insights` -- underlying plugin that initializes the Application Insights SDK
-- [useUserManagement](../useUserManagement/useUserManagement.docs.md) -- provides current user context for telemetry enrichment
+- `useUserManagement` -- provides current user context for telemetry enrichment
 - [useErrorHandler](../useErrorHandler/useErrorHandler.docs.md) -- automatically tracks exceptions to Application Insights
 - [useWebVitals](../useWebVitals/useWebVitals.docs.md) -- Core Web Vitals can be piped to Application Insights via a custom callback

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

@@ -103,15 +103,16 @@ Without the generic, `options.value` defaults to `Record<string, unknown> | unde
 
 These are reactive `ComputedRef` values that reflect the current blade's state. Accessing them outside blade context throws a runtime error.
 
-| Property   | Type                                               | Description                                                                                                                                                |
-| ---------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `id`       | `ComputedRef<string>`                              | The current blade's unique ID within the blade stack                                                                                                       |
-| `param`    | `ComputedRef<string \| undefined>`                 | Route parameter passed when the blade was opened                                                                                                           |
-| `options`  | `ComputedRef<TOptions \| undefined>`               | Additional options object passed to the blade. Type is `Record<string, unknown>` by default; provide a generic to get a typed ref: `useBlade<MyOptions>()` |
-| `query`    | `ComputedRef<Record<string, string> \| undefined>` | URL query parameters scoped to this blade                                                                                                                  |
-| `closable` | `ComputedRef<boolean>`                             | `true` when this blade has a parent (i.e., can be closed)                                                                                                  |
-| `expanded` | `ComputedRef<boolean>`                             | `true` when this blade is the active (rightmost) blade                                                                                                     |
-| `name`     | `ComputedRef<string>`                              | The blade's registered component name                                                                                                                      |
+| Property           | Type                                               | Description                                                                                                                                                                                                                                                                                    |
+| ------------------ | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`               | `ComputedRef<string>`                              | The current blade's unique ID within the blade stack                                                                                                                                                                                                                                           |
+| `param`            | `ComputedRef<string \| undefined>`                 | Route parameter passed when the blade was opened                                                                                                                                                                                                                                               |
+| `activeChildParam` | `ComputedRef<string \| undefined>`                 | The `param` of the direct child blade opened from this blade (the entity currently shown in the details pane), or `undefined`. Reactive and reload-safe. Bind it to a list table's `:active-item-id` to highlight the open entity's row — it stays correct across reloads, unlike a local ref. |
+| `options`          | `ComputedRef<TOptions \| undefined>`               | Additional options object passed to the blade. Type is `Record<string, unknown>` by default; provide a generic to get a typed ref: `useBlade<MyOptions>()`                                                                                                                                     |
+| `query`            | `ComputedRef<Record<string, string> \| undefined>` | URL query parameters scoped to this blade                                                                                                                                                                                                                                                      |
+| `closable`         | `ComputedRef<boolean>`                             | `true` when this blade has a parent (i.e., can be closed)                                                                                                                                                                                                                                      |
+| `expanded`         | `ComputedRef<boolean>`                             | `true` when this blade is the active (rightmost) blade                                                                                                                                                                                                                                         |
+| `name`             | `ComputedRef<string>`                              | The blade's registered component name                                                                                                                                                                                                                                                          |
 
 #### Navigation Methods (work everywhere)
 
@@ -387,6 +388,30 @@ onDeactivated(() => {
 });
 ```
 
+### Highlight the row of the open child blade
+
+Bind `activeChildParam` to the table's `active-item-id` so the row of the currently open details blade is highlighted — including after a page reload:
+
+```vue
+<script setup lang="ts">
+const { openBlade, activeChildParam } = useBlade();
+
+function onRowClick(e: { data: { id: string } }) {
+  openBlade({ name: "Details", param: e.data.id });
+}
+</script>
+
+<template>
+  <VcDataTable
+    :items="items"
+    :active-item-id="activeChildParam"
+    @row-click="onRowClick"
+  >
+    <!-- columns -->
+  </VcDataTable>
+</template>
+```
+
 ### Error Management
 
 Display or clear error banners on the blade:

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

@@ -0,0 +1,34 @@
+---
+title: usePlatformLocaleSync
+category: composables
+group: user
+---
+
+# usePlatformLocaleSync
+
+One-way reactive bridge from the VirtoCommerce platform's locale storage key (`NG_TRANSLATE_LANG_KEY`, set by AngularJS + angular-translate) to the shell's language service.
+
+Call this composable only when the shell runs embedded inside the platform — `useShellBootstrap` invokes it automatically when `options.isEmbedded === true`. In standalone mode the shell owns its own locale via `VC_LANGUAGE_SETTINGS`, and this composable should not be used.
+
+## When to Use
+
+- Never call directly from feature code. This is a framework-internal sync primitive.
+- It is invoked once per `VcApp` mount from `useShellBootstrap`.
+
+## Behaviour
+
+- Reads `localStorage["NG_TRANSLATE_LANG_KEY"]` via VueUse's `useLocalStorage`, which subscribes to `storage` events for cross-tab reactivity.
+- On setup, if the value is non-empty, calls `LanguageService.setLocale(value)`. `setLocale` normalises the value (e.g. `en-US` → `en-us`), falls back to `en` for unsupported locales, updates `vue-i18n`, reconfigures `vee-validate`, and persists to `VC_LANGUAGE_SETTINGS`.
+- On subsequent changes of the platform key, re-applies the value.
+- Skips empty strings (platform clearing the key does not blank the shell locale).
+- Skips values equal to `currentLocale` to avoid redundant re-configuration.
+
+## How It Works
+
+`useLocalStorage("NG_TRANSLATE_LANG_KEY", "")` returns a `Ref<string>` that VueUse keeps in sync with `localStorage` and the DOM `storage` event (which fires in tabs other than the writer). The composable applies the current ref value once synchronously and then registers a `watch` on it; any cross-tab mutation flows through the ref into `setLocale`.
+
+The watcher is bound to the active effect scope (typically `VcApp`'s setup). When `VcApp` unmounts, the watcher stops; `useLocalStorage` cleans up its own `storage` listener.
+
+## Relationship to `VC_LANGUAGE_SETTINGS`
+
+The sync is strictly one-directional. `setLocale` writes to `VC_LANGUAGE_SETTINGS` as a side effect, but this composable never writes to `NG_TRANSLATE_LANG_KEY`. In embedded mode the in-shell `LanguageSelector` is unreachable (it lives inside `UserDropdownButton`, which is hidden when `isEmbedded` is `true`), so there is no competing writer from the shell side.

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

@@ -200,7 +200,7 @@ const { isMobile } = useResponsive();
 
 ## Migration
 
-See [migration guide #36](../../../../migration/36-use-responsive.md) for automated codemod and manual migration instructions.
+See [migration guide #36](https://github.com/VirtoCommerce/vc-shell/blob/main/migration/36-use-responsive.md) for automated codemod and manual migration instructions.
 
 ## Related
 

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

@@ -167,5 +167,5 @@ trackRequest("my-request-2");
 ## Related
 
 - [`useConnectionStatus`](../useConnectionStatus/useConnectionStatus.docs.md) — offline detection (binary online/offline)
-- [`registerInterceptors`](../../interceptors/index.ts) — the fetch wrapper that calls `trackRequest`/`untrackRequest`
+- [`registerInterceptors`](https://github.com/VirtoCommerce/vc-shell/blob/main/framework/core/interceptors/index.ts) — the fetch wrapper that calls `trackRequest`/`untrackRequest`
 - `notification` from `@shared/components/notifications` — the notification system used to display the warning

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

@@ -173,6 +173,6 @@ async function fetchCustomEndpoint(url: string) {
 
 ## Related
 
-- [useUserManagement](../useUserManagement/useUserManagement.docs.md) -- extended API with sign-in, password reset, token validation (for auth pages)
+- `useUserManagement` -- extended API with sign-in, password reset, token validation (for auth pages)
 - [usePermissions](../usePermissions/) -- permission checks based on user roles
 - `UserDetail` from `@core/api/platform` -- the user detail type returned by the API

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

@@ -0,0 +1,184 @@
+---
+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 concept page.](../../concepts/notifications.md)
+- [Notifications plugin reference.](../../plugins/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 `IndexProgressPushNotification` or similar maintenance events for non-admin roles.
+- 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 !== "IndexProgressPushNotification");
+```
+
+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.
+- **Filter exceptions go straight to the console.** If your predicate throws, the message is dropped. Wrap the logic if you are reading off 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)