@vc-shell/vc-app-skill 2.6.0-rc.1-pr368.e4295d2 → 2.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vc-shell/vc-app-skill",
-  "version": "2.6.0-rc.1-pr368.e4295d2",
+  "version": "2.6.0",
   "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.6.0-rc.1
+2.6.0

package/runtime/knowledge/docs/_BUILD_HASH.md

@@ -1 +1 @@
-Synced from framework at commit 371aa8ec5 on 2026-09-08T10:09:34.584Z
+Synced from framework at commit 1919c06af on 2026-09-22T14:57:56.467Z

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

@@ -71,13 +71,13 @@ function openMenu() {
 
 ### Parameters (Options Object)
 
-| Parameter           | Type                        | Default            | Description                                                                                                      |
-| ------------------- | --------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------- |
-| `containerSelector` | `string`                    | `'[role="menu"]'`  | CSS selector to auto-find the container on mount. Set to empty string to disable auto-attach.                    |
-| `itemSelector`      | `string`                    | `'[tabindex="0"]'` | CSS selector for focusable items inside the container.                                                           |
-| `onEnter`           | `(el: HTMLElement) => void` | `undefined`        | Called when Enter or Space is pressed on a focused item. Falls back to `el.click()` if not provided.             |
-| `onEscape`          | `() => void`                | `undefined`        | Called when Escape is pressed. Typically used to close the menu or popover.                                      |
-| `loop`              | `boolean`                   | `true`             | When `true`, pressing ArrowDown on the last item wraps to the first, and ArrowUp on the first wraps to the last. |
+| Parameter           | Type                        | Default            | Description                                                                                                           |
+| ------------------- | --------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| `containerSelector` | `string`                    | `'[role="menu"]'`  | CSS selector to auto-find the container on mount. Set to empty string to disable auto-attach.                         |
+| `itemSelector`      | `string`                    | `'[tabindex="0"]'` | CSS selector for focusable items inside the container.                                                                |
+| `onEnter`           | `(el: HTMLElement) => void` | `undefined`        | Called when Enter or Space is pressed on a focused item. Falls back to `el.click()` if not provided.                  |
+| `onEscape`          | `() => void`                | `undefined`        | Called when Escape is pressed, and makes the composable consume the key. Typically used to close the menu or popover. |
+| `loop`              | `boolean`                   | `true`             | When `true`, pressing ArrowDown on the last item wraps to the first, and ArrowUp on the first wraps to the last.      |
 
 ### Returns
 
@@ -101,7 +101,7 @@ The composable listens for `keydown` events on the container element and handles
 - **ArrowDown / Tab**: Move focus to the next item (`focusNextElement`)
 - **ArrowUp / Shift+Tab**: Move focus to the previous item (`focusPreviousElement`)
 - **Enter / Space**: Activate the focused item (calls `onEnter` callback, or `el.click()`)
-- **Escape**: Call `onEscape` callback
+- **Escape**: Call `onEscape` callback. When a callback is given the event is consumed (`preventDefault` + `stopPropagation`), so a sidebar or dialog listening on `document` does not also close behind the overlay. With no `onEscape`, the key passes through untouched.
 
 On each key event, the composable re-queries the container for matching items (`itemSelector`), so it naturally handles dynamic lists where items are added or removed. The focused index is validated against the current item count before every operation to prevent stale-index bugs.
 

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

@@ -0,0 +1,219 @@
+---
+title: useKeyboardShortcuts
+category: composables
+group: utilities
+---
+
+!!! tip "Long page"
+Use the section headings to jump directly to what you need: [Primary pattern: declare a shortcut on a toolbar item](#primary-pattern-declare-a-shortcut-on-a-toolbar-item), [Quick Start](#quick-start), [Built-in blade shortcuts](#built-in-blade-shortcuts), or [API Reference](#api-reference).
+
+# useKeyboardShortcuts
+
+`useKeyboardShortcuts` is the framework's keyboard-shortcut toolkit: the `hotkey` fluent builder for describing a combination, and OS-aware formatting for the tooltip and `aria-keyshortcuts` that a toolbar button shows automatically once it declares one. There is no manual `keydown` wiring in module code -- a shortcut is a plain field on a toolbar item, and the blade navigation layer dispatches it globally.
+
+## Primary pattern: declare a shortcut on a toolbar item
+
+Add `shortcut: hotkey.mod.s` to any `IBladeToolbar` entry. `hotkey.mod.s` resolves to `{ key: "s", mod: true }` -- `mod` is the platform's primary modifier (Cmd on macOS, Ctrl elsewhere), so one definition covers both operating systems.
+
+```vue title="orders-details.vue"
+<script setup lang="ts">
+import { ref } from "vue";
+import { hotkey, VcBlade, type IBladeToolbar } from "@vc-shell/framework";
+
+const bladeToolbar = ref<IBladeToolbar[]>([
+  {
+    id: "save",
+    title: "Save",
+    icon: "lucide-save",
+    shortcut: hotkey.mod.s,
+    clickHandler: () => save(),
+  },
+]);
+</script>
+
+<template>
+  <VcBlade :toolbar-items="bladeToolbar" />
+</template>
+```
+
+That single field is the whole integration. The rendered "Save" button now shows a `⌘S` / `Ctrl+S` tooltip, sets `aria-keyshortcuts="Meta+S"`, and the blade navigation layer fires `clickHandler` when the user presses the combination while the blade is active -- no listener, no cleanup.
+
+## When to reach for it
+
+- **Declaring a shortcut on a toolbar item.** The common case: add `shortcut: hotkey.mod.s` next to `clickHandler` on an `IBladeToolbar` entry (array pattern or `useToolbar().registerToolbarItem`, see [useToolbar](../useToolbar/)).
+- **Formatting a shortcut for custom UI.** Call `useKeyboardShortcuts()` and use `formatShortcut(def)` when you need the OS-aware label somewhere other than the built-in toolbar tooltip (a help panel, a command palette row).
+- **Detecting the platform.** `isMac` is exposed for any OS-conditional copy or icon choice tied to a shortcut.
+- **Not for building your own key listener.** There is no public "register a global shortcut" API outside toolbar items -- see [Common mistakes](#common-mistakes).
+
+## Quick Start
+
+### Import vs `useKeyboardShortcuts()` destructure
+
+`hotkey` is a context-free singleton -- import it directly wherever you only need to build a definition:
+
+```typescript
+import { hotkey } from "@vc-shell/framework";
+
+const saveShortcut = hotkey.mod.s; // { key: "s", mod: true }
+```
+
+Reach for the composable form only when you also need `formatShortcut` or `isMac` (both are bound together so `formatShortcut` doesn't need an `isMac` argument at the call site):
+
+```typescript
+import { useKeyboardShortcuts } from "@vc-shell/framework";
+
+const { hotkey, formatShortcut, isMac } = useKeyboardShortcuts();
+
+const saveShortcut = hotkey.mod.s;
+const { parts, aria } = formatShortcut(saveShortcut);
+// isMac ? parts = ["⌘", "S"] : parts = ["Ctrl", "S"]
+// aria = "Meta+S" on macOS, "Control+S" elsewhere
+```
+
+Both forms return the same `hotkey` singleton -- the composable exists for convenience when a component already needs `isMac`/`formatShortcut`, not because `hotkey` itself carries state.
+
+## Built-in blade shortcuts
+
+Two shortcuts are wired up by the framework at the blade navigation root -- no client code required, and no toolbar item needed to get them:
+
+| Shortcut     | Effect                  | Gate                                                                        |
+| ------------ | ----------------------- | --------------------------------------------------------------------------- |
+| `Esc`        | Closes the active blade | Only if the blade is closable (has a `parentId`; workspace roots ignore it) |
+| `Cmd/Ctrl+\` | Toggles expand/maximize | Only on desktop and only if the blade is closable                           |
+
+Both are evaluated against the currently active blade, and both are skipped while the corresponding condition doesn't hold -- `Esc` on a non-closable workspace root does nothing, and `Cmd/Ctrl+\` does nothing on mobile viewports even on a closable blade.
+
+**An explicit toolbar shortcut always wins.** The dispatcher checks the active blade's toolbar items before either built-in, so a toolbar item declared with `shortcut: hotkey.escape` (for example, a "Cancel" button) intercepts `Esc` and the built-in close never runs.
+
+## OS adaptation
+
+`formatShortcut(def)` returns two independent representations from one `ShortcutDefinition`, so you never branch on OS yourself:
+
+- `parts` -- an array of OS-native keycap labels for display. macOS renders modifier glyphs in Apple's canonical order (`⌃ ⌥ ⇧ ⌘`) with no separator; Windows/Linux render words (`Ctrl`, `Alt`, `Shift`) with a `+` between chips.
+- `aria` -- a single canonical string in W3C `aria-keyshortcuts` format (`"Control+Shift+S"`), OS-independent by design -- this is what assistive tech reads, not what's painted on screen.
+
+```typescript
+import { useKeyboardShortcuts } from "@vc-shell/framework";
+
+const { hotkey, formatShortcut, isMac } = useKeyboardShortcuts();
+const { parts } = formatShortcut(hotkey.mod.s);
+
+// isMac === true  → parts = ["⌘", "S"]      → tooltip renders "⌘S" (no separator)
+// isMac === false → parts = ["Ctrl", "S"]   → tooltip renders "Ctrl+S" (with separator)
+```
+
+The toolbar button itself (`ToolbarBaseButton`) already does this for you: it calls `formatShortcut` internally and renders the result through the `ShortcutKbd` chip component inside a tooltip. `isMac` also determines `matchesEvent`'s runtime resolution of `mod` -- the same flag drives both what the user sees and what actually fires.
+
+## Accessibility
+
+- **`aria-keyshortcuts`.** Set automatically on the button element whenever `shortcut` is present, using the canonical `aria` string from `formatShortcut` (for example `aria-keyshortcuts="Meta+S"`). No shortcut, no attribute -- it's never rendered empty.
+- **Tooltip discovery.** A sighted user discovers the shortcut through the `<kbd>` chips shown on hover/focus of the toolbar button (`ShortcutKbd`, wrapped in `VcTooltip`). This is the only visual affordance; there is no separate "shortcuts list" surface in v1.
+- **No button, no discovery.** Both `aria-keyshortcuts` and the tooltip are properties of the rendered toolbar button -- they exist only because `shortcut` lives on an `IBladeToolbar` item that renders as a button. There is currently no way to advertise a shortcut that isn't attached to a visible button (see [Common mistakes](#common-mistakes)).
+- **Accessible name still comes from the title.** `shortcut` does not change how the button's accessible name is computed -- it still comes from the visible `title` text. Keep `title` non-empty; `shortcut` is additive, not a substitute for a labeled button.
+- **Suppressed behind a modal.** Blade shortcuts (toolbar and built-in) do not fire while a modal (`aria-modal="true"`) is open, so a shortcut never acts on a blade hidden behind it.
+
+## Common mistakes
+
+### Expecting a bare key to fire while an input is focused
+
+```typescript
+// Wrong -- assumes "e" fires globally
+registerToolbarItem({ id: "edit", title: "Edit", shortcut: { key: "e" }, clickHandler: () => edit() });
+```
+
+A shortcut with no modifier is suppressed while focus is inside a text input, textarea, select, or a `contenteditable` element -- otherwise typing the letter "e" into a form field would trigger the button. This guard only applies to bare keys; add a modifier (`hotkey.mod.e`) if the shortcut must also fire while a field is focused.
+
+```typescript
+// Correct -- a modified combination is not suppressed by input focus
+registerToolbarItem({ id: "edit", title: "Edit", shortcut: hotkey.mod.e, clickHandler: () => edit() });
+```
+
+### Two toolbar items sharing the same combination
+
+```typescript
+// Wrong -- both items declare mod+s on the same blade
+const bladeToolbar = ref<IBladeToolbar[]>([
+  { id: "save", title: "Save", shortcut: hotkey.mod.s, clickHandler: () => save() },
+  { id: "save-as", title: "Save As", shortcut: hotkey.mod.s, clickHandler: () => saveAs() },
+]);
+```
+
+The dispatcher walks a blade's toolbar items in declaration order and fires the _first_ item whose shortcut matches, then stops -- `save-as` never receives `Cmd/Ctrl+S` as long as `save` is registered ahead of it. In development, the dispatcher emits a deduplicated `console.warn` on keydown for this case (first item wins, second is named in the warning), for a toolbar item with an unrecognized `shortcut.key`, and for a toolbar item that overrides a built-in (`Esc`, `Cmd/Ctrl+\`). Production stays silent -- these are warnings, not thrown errors -- so still treat shortcut collisions within a blade's toolbar as a review-time concern: keep combinations unique per blade.
+
+```typescript
+// Correct -- distinct combinations
+const bladeToolbar = ref<IBladeToolbar[]>([
+  { id: "save", title: "Save", shortcut: hotkey.mod.s, clickHandler: () => save() },
+  { id: "save-as", title: "Save As", shortcut: hotkey.mod.shift.s, clickHandler: () => saveAs() },
+]);
+```
+
+### Expecting a button-less shortcut
+
+```typescript
+// Wrong -- there is no API to register a shortcut without a toolbar item
+onMounted(() => {
+  window.addEventListener("keydown", (e) => {
+    if (e.metaKey && e.key === "s") save();
+  });
+});
+```
+
+Rolling your own `keydown` listener bypasses `isTextInputFocused` suppression, the active-blade scoping, and the tooltip/`aria-keyshortcuts` discovery that toolbar shortcuts get for free -- and it risks double-firing alongside the framework dispatcher. In v1, every shortcut must be attached to a visible `IBladeToolbar` item; there is no headless/button-less registration path. If the action genuinely has no natural button, add one (it can be low-priority/overflowed) rather than reaching for a manual listener.
+
+## API Reference
+
+### `hotkey`
+
+A fluent builder, importable directly or via the composable. Modifier and key names are finite string unions, so a typo (`hotkey.mdo.s`) is a compile error, not a silent no-op.
+
+```typescript
+hotkey.mod.s; // { key: "s", mod: true }
+hotkey.mod.shift.s; // { key: "s", mod: true, shift: true }
+hotkey.ctrl.alt.delete; // { key: "delete", ctrl: true, alt: true }
+hotkey.escape; // { key: "escape" }
+```
+
+Chainable modifiers: `mod`, `ctrl`, `meta`, `alt`, `shift` (any order, any combination). Terminal keys: letters `a`-`z`, digits `0`-`9`, `enter`, `escape`, `tab`, `space`, `delete`, `backspace`, `arrowup`/`arrowdown`/`arrowleft`/`arrowright`, `f1`-`f12`, `backslash`, `period`, `comma`, `slash`.
+
+### `useKeyboardShortcuts()`
+
+Context-free -- no inject/lifecycle, usable in or out of a component `setup()`.
+
+#### Returns: `UseKeyboardShortcutsReturn`
+
+| Property         | Type                                                             | Description                                                               |
+| ---------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `hotkey`         | `HotkeyBuilder`                                                  | The same singleton as the named `hotkey` import                           |
+| `formatShortcut` | `(def: ShortcutDefinition) => { parts: string[]; aria: string }` | `isMac`-bound: formats a definition into display chips and an aria string |
+| `isMac`          | `boolean`                                                        | `true` when the user agent reports macOS/iOS                              |
+
+### `formatShortcut(def, isMac)`
+
+The standalone function (also exported directly) if you need to format for an explicit `isMac` value instead of the detected one:
+
+```typescript
+import { formatShortcut } from "@vc-shell/framework";
+
+formatShortcut({ key: "s", mod: true }, true); // { parts: ["⌘", "S"], aria: "Meta+S" }
+formatShortcut({ key: "s", mod: true }, false); // { parts: ["Ctrl", "S"], aria: "Control+S" }
+```
+
+### `ShortcutDefinition`
+
+| Property | Type      | Required | Description                                                                         |
+| -------- | --------- | -------- | ----------------------------------------------------------------------------------- |
+| `key`    | `string`  | Yes      | Single key: `"s"`, `"1"`, `"enter"`, `"escape"`, `"f2"`, `"arrowup"`, `"backslash"` |
+| `mod`    | `boolean` | No       | Platform primary modifier -- Cmd on macOS, Ctrl elsewhere                           |
+| `ctrl`   | `boolean` | No       | Literal Ctrl, regardless of platform                                                |
+| `meta`   | `boolean` | No       | Literal Cmd/Win key, regardless of platform                                         |
+| `alt`    | `boolean` | No       | Alt/Option                                                                          |
+| `shift`  | `boolean` | No       | Shift                                                                               |
+
+Building definitions by hand (`{ key: "s", mod: true }`) works identically to `hotkey.mod.s` -- the builder is sugar over this shape, useful when a definition needs to be constructed dynamically.
+
+## Related
+
+- [useToolbar](../useToolbar/) -- registers the toolbar items that carry `shortcut`; see its `IBladeToolbar`/`IToolbarItem` reference for the full item shape
+- [Blade Navigation Composables](../../blade-navigation/) -- the blade stack that scopes shortcut dispatch to the active blade and hosts the two built-in shortcuts
+- `IBladeToolbar` in [Core types](../../types/) -- the `shortcut?: ShortcutDefinition` field lives here

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

@@ -0,0 +1,151 @@
+---
+title: useLatestRequest
+category: composables
+group: utilities
+---
+
+# useLatestRequest
+
+Latest-wins sequencing for overlapping async work: lets a caller drop a response
+that a newer request already superseded.
+
+`useAsync` covers loading state, error state and error notifications, but it has
+no notion of a superseded call — a slow earlier response can overwrite a newer
+one. This composable fills that gap.
+
+## When to Use
+
+- A search field that fires a request per keystroke, where the slowest response must not win
+- A master/detail pair, where clicking row A then row B must not leave A's details on screen
+- Any load that can still be in flight when its blade closes
+- When NOT to use: for a single request with no concurrent sibling — plain `useAsync` is enough
+
+!!! note "Discards, does not cancel"
+The superseded request still completes; its result is thrown away. The generated
+API clients build their own `RequestInit` and accept no `AbortSignal`, so there
+is nothing to cancel through. Aborting would additionally save the round trip and
+belongs with a client that takes a signal.
+
+## Quick Start
+
+```typescript
+import { useLatestRequest } from "@vc-shell/framework";
+
+const search = useLatestRequest();
+const items = ref([]);
+
+async function load(criteria) {
+  const result = await search.latest(client.search(criteria));
+  if (!result) return; // a newer search already won
+  items.value = result;
+}
+```
+
+`latest()` owns the bookkeeping: it marks the request as the newest, releases it
+when it settles — including on a throw — and hands back `undefined` if a newer
+request started meanwhile. There is no `finally` to forget.
+
+!!! note "When `undefined` is ambiguous"
+`undefined` means superseded. A request whose own successful result can be
+`undefined` cannot distinguish the two, and should use `begin()` below.
+
+## API Reference
+
+### Returns
+
+| Member       | Type                                                  | Description                                                                       |
+| ------------ | ----------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `latest`     | `<T>(request: Promise<T>) => Promise<T \| undefined>` | Runs a request, resolving to `undefined` if a newer one superseded it             |
+| `begin`      | `() => LatestRequest`                                 | Starts a request and supersedes any earlier one. The manual form behind `latest`  |
+| `invalidate` | `() => void`                                          | Supersedes the in-flight request without starting a new one                       |
+| `dispose`    | `() => void`                                          | Permanently supersedes everything. Runs automatically when the owning scope stops |
+| `pending`    | `Readonly<Ref<boolean>>`                              | `true` while the newest request is still running                                  |
+
+### `LatestRequest`
+
+Returned by `begin()`, for the cases `latest()` cannot serve: the request and the
+check living in different functions, or a result that is legitimately `undefined`.
+
+| Member      | Type            | Description                                                                        |
+| ----------- | --------------- | ---------------------------------------------------------------------------------- |
+| `isCurrent` | `() => boolean` | `false` once a newer request started, or after `invalidate()` / `dispose()`        |
+| `complete`  | `() => void`    | Marks this request finished. Idempotent; only the current request clears `pending` |
+
+## Features
+
+### `pending` tracks the newest request only
+
+A superseded request finishing does **not** clear `pending` — the newer one is
+still running, and clearing there would hide the spinner while the screen is
+still waiting for data.
+
+### Automatic disposal
+
+When called inside a component or effect scope, the tracker disposes itself when
+that scope stops, so a response landing after its blade closed can never write
+into a dead scope. Call `dispose()` by hand only outside a scope.
+
+## Recipes
+
+### Driving a spinner
+
+```typescript
+const details = useLatestRequest();
+// `pending` is a ref, so watch it, render it, or hand it to useLoading.
+const loading = details.pending;
+```
+
+### Dropping a request on selection change
+
+```typescript
+watch(selectedId, () => {
+  // Nothing new starts yet; whatever is in flight stops being current.
+  details.invalidate();
+});
+```
+
+## Common Mistakes
+
+**Wrong: checking before the await**
+
+```typescript
+const request = search.begin();
+if (!request.isCurrent()) return; // always true here — nothing has superseded it yet
+const result = await client.search(criteria);
+items.value = result; // still overwrites newer data
+```
+
+**Right: checking after**
+
+```typescript
+const request = search.begin();
+const result = await client.search(criteria);
+if (!request.isCurrent()) return;
+items.value = result;
+```
+
+**Wrong: completing only on success**
+
+```typescript
+const request = search.begin();
+const result = await client.search(criteria); // throws → pending stays true forever
+request.complete();
+```
+
+**Right: completing in `finally`**
+
+```typescript
+const request = search.begin();
+try {
+  const result = await client.search(criteria);
+  if (!request.isCurrent()) return;
+  items.value = result;
+} finally {
+  request.complete();
+}
+```
+
+## Related
+
+- [useAsync](./useAsync.md) — loading state, error state and error notifications for a single call
+- [useLoading](./useLoading.md) — aggregates several loading flags

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

@@ -7,15 +7,17 @@ internal: true
 
 # useSlowNetworkDetection
 
-Detects slow network conditions and shows a persistent warning notification so users know why the UI is unresponsive. Two detection channels work together: a **proactive** channel reads `navigator.connection.effectiveType` to catch weak connections before any request is made, and a **reactive** channel flags API requests that have been pending for more than 10 seconds. The notification auto-dismisses with a 3-second delay after conditions clear, preventing flicker. When the browser goes fully offline, the slow-network notification is suppressed in favor of the existing offline notification from `useConnectionStatus`.
+Detects slow network conditions and publishes them as the `vc-slow-network` class on `<html>`, which the framework renders as a 2px sweep along the top edge of the viewport. Two detection channels work together: a **proactive** channel reads `navigator.connection.effectiveType` to catch weak connections before any request is made, and a **reactive** channel flags idempotent API requests that have been pending for more than 10 seconds. The class is removed with a 3-second delay after conditions clear, preventing flicker. When the browser goes fully offline, the class is dropped in favor of the offline notification from `useConnectionStatus`.
+
+A slow network is a state, not an event, so it is never announced as a toast: a dismissable one reappears on every action that outruns the threshold, and a sticky one sits on the screen for the whole session on a 2g connection (VCST-6045).
 
 Like `useConnectionStatus`, this is a module-level singleton — calling it from multiple components shares the same state and listeners.
 
 ## When to Use
 
 - Reactively check `isSlowNetwork` to show skeleton loaders, disable auto-refresh, or display inline warnings
-- The notification is automatic — no extra code needed beyond calling the composable once at app startup (already done in `framework/index.ts`)
-- Use `trackRequest` / `untrackRequest` only if you have custom fetch logic outside the standard interceptor (the built-in fetch interceptor already tracks all `/api/*` requests)
+- The `vc-slow-network` class is automatic — no extra code needed beyond calling the composable once at app startup (already done in `framework/index.ts`)
+- Use `trackRequest` / `untrackRequest` only if you have custom fetch logic outside the standard interceptor (the built-in fetch interceptor already tracks idempotent `/api/*` requests)
 - When NOT to use: for offline detection (use `useConnectionStatus` instead) or for measuring exact latency/bandwidth
 
 ## Quick Start
@@ -61,11 +63,12 @@ const { isSlowNetwork } = useSlowNetworkDetection();
 
 These are module-private `const` declarations, not exported symbols — do not `import` them. They document the thresholds baked into the composable.
 
-| Name                        | Value               | Purpose                                             |
-| --------------------------- | ------------------- | --------------------------------------------------- |
-| `SLOW_REQUEST_THRESHOLD_MS` | `10000`             | Time before a pending request is considered slow    |
-| `DISMISS_DELAY_MS`          | `3000`              | Delay before hiding the notification after recovery |
-| `SLOW_EFFECTIVE_TYPES`      | `["slow-2g", "2g"]` | Connection types flagged as slow                    |
+| Name                        | Value               | Purpose                                          |
+| --------------------------- | ------------------- | ------------------------------------------------ |
+| `SLOW_REQUEST_THRESHOLD_MS` | `10000`             | Time before a pending request is considered slow |
+| `DISMISS_DELAY_MS`          | `3000`              | Delay before dropping the class after recovery   |
+| `SLOW_EFFECTIVE_TYPES`      | `["slow-2g", "2g"]` | Connection types flagged as slow                 |
+| `SLOW_NETWORK_CLASS`        | `"vc-slow-network"` | Class the state is published as, on `<html>`     |
 
 ## How It Works
 
@@ -75,15 +78,15 @@ On first call, the composable checks `navigator.connection.effectiveType` (Netwo
 
 ### Channel 2: Request timers (reactive)
 
-The fetch interceptor in `framework/core/interceptors/index.ts` calls `trackRequest(id)` before every `/api/*` request and `untrackRequest(id)` in the `finally` block. Each tracked request gets a 10-second timer. If the response arrives in time, the timer is cancelled. If not, `isSlowNetwork` becomes `true` and stays `true` until all slow requests complete.
+The fetch interceptor in `framework/core/interceptors/index.ts` calls `trackRequest(id)` before every idempotent `/api/*` request (GET and HEAD) and `untrackRequest(id)` in the `finally` block. An upload or any other mutation is left out: its duration is the operator's uplink, not a stalled server, and a large file would otherwise claim the network is slow every time. Each tracked request gets a 10-second timer. If the response arrives in time, the timer is cancelled. If not, `isSlowNetwork` becomes `true` and stays `true` until all slow requests complete.
 
-### Notification lifecycle
+### Class lifecycle
 
-1. `isSlowNetwork` becomes `true` → show `notification.warning` (deduplicated by fixed ID, persists until removed)
-2. `isSlowNetwork` becomes `false` → start a 3-second dismiss timer
-3. If `isSlowNetwork` goes back to `true` within those 3 seconds → cancel dismiss, notification stays
-4. If the browser goes offline → immediately hide the slow notification (the offline notification takes over)
-5. If the browser comes back online and `isSlowNetwork` is still `true` → re-show
+1. `isSlowNetwork` becomes `true` → add `vc-slow-network` to `<html>`, and the bar appears
+2. `isSlowNetwork` becomes `false` → start a 3-second removal timer
+3. If `isSlowNetwork` goes back to `true` within those 3 seconds → cancel removal, the class stays
+4. If the browser goes offline → remove the class at once (the offline notification takes over)
+5. If the browser comes back online and `isSlowNetwork` is still `true` → add it again
 <!-- internal:end -->
 
 ## Recipe: Custom Slow-Network Behavior in a Blade
@@ -131,8 +134,9 @@ async function fetchFromExternalApi(url: string) {
 ## Tips
 
 - **Singleton by design.** Multiple calls to `useSlowNetworkDetection()` share the same state. No overhead from calling it in many components.
-- **The notification cannot stack.** It uses a fixed `notificationId`, so even if multiple requests become slow simultaneously, only one notification is shown.
-- **The 3-second dismiss delay prevents flicker.** Without it, a burst of requests completing one-by-one would cause the notification to flash on and off rapidly.
+- **The state cannot stack.** A class is present or it is not, so concurrent slow requests read as one state.
+- **The 3-second removal delay prevents flicker.** Without it, a burst of requests completing one-by-one would toggle the class on and off rapidly.
+- **The bar lives in one CSS rule.** `framework/assets/styles/index.scss` draws it next to the `html.vc-offline` rule, so an app can restyle or suppress it without touching the composable. Under `prefers-reduced-motion` it becomes a static line.
 - **`navigator.connection` has limited support.** Only Chromium-based browsers support it. Firefox and Safari users will only get the request-timer channel, which is still effective.
 - **The composable does not block requests.** Unlike the offline guard in the interceptor, slow-network detection is purely informational — it never prevents or delays a fetch.
 
@@ -171,4 +175,4 @@ trackRequest("my-request-2");
 
 - [`useConnectionStatus`](../useConnectionStatus/useConnectionStatus.docs.md) — offline detection (binary online/offline)
 - [`registerInterceptors`](https://github.com/VirtoCommerce/vc-shell/blob/main/framework/core/interceptors/index.ts) — the fetch wrapper that calls `trackRequest`/`untrackRequest`
-- `notification` from `@core/notifications/notification` — the notification system used to display the warning
+- `framework/assets/styles/index.scss` — the top-edge sweep this class renders as, alongside the `html.vc-offline` rule

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

@@ -234,20 +234,23 @@ Use the `"star-and-text"` or `"text"` variant in table cell slots for a compact
 
 ## Props
 
-| Prop          | Type                                   | Default   | Description                              |
-| ------------- | -------------------------------------- | --------- | ---------------------------------------- |
-| `modelValue`  | `number`                               | --        | Current rating value to display          |
-| `max`         | `number`                               | `5`       | Maximum rating value (defines the scale) |
-| `variant`     | `"stars" \| "star-and-text" \| "text"` | `"stars"` | Display variant                          |
-| `label`       | `string`                               | --        | Field label text above the rating        |
-| `tooltip`     | `string`                               | --        | Tooltip shown on the label               |
-| `placeholder` | `string`                               | --        | Text shown when `modelValue` is falsy    |
+| Prop           | Type                                   | Default   | Description                                                             |
+| -------------- | -------------------------------------- | --------- | ----------------------------------------------------------------------- |
+| `modelValue`   | `number`                               | --        | Current rating value to display                                         |
+| `max`          | `number`                               | `5`       | Maximum rating value (defines the scale)                                |
+| `variant`      | `"stars" \| "star-and-text" \| "text"` | `"stars"` | Display variant                                                         |
+| `label`        | `string`                               | --        | Field label text above the rating                                       |
+| `tooltip`      | `string`                               | --        | Tooltip shown on the label                                              |
+| `placeholder`  | `string`                               | --        | Text shown when `modelValue` is falsy                                   |
+| `error`        | `boolean`                              | --        | Marks the field invalid without a message                               |
+| `errorMessage` | `string`                               | --        | Validation message shown below the rating; also marks the field invalid |
 
 ## Slots
 
-| Slot      | Scope | Description                                                                            |
-| --------- | ----- | -------------------------------------------------------------------------------------- |
-| `details` | --    | Additional content below the rating (available in `star-and-text` and `text` variants) |
+| Slot      | Scope | Description                                                                                                                             |
+| --------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `details` | --    | Additional content below the rating (available in `star-and-text` and `text` variants)                                                  |
+| `error`   | --    | Replaces the default validation message element. Keep the slotted element's `id`, or the control's `aria-describedby` points at nothing |
 
 ## CSS Variables
 
@@ -266,6 +269,8 @@ Use the `"star-and-text"` or `"text"` variant in table cell slots for a compact
 - When no value is present, the `aria-label` falls back to the placeholder text or "No rating".
 - The label is rendered via `VcLabel` with optional tooltip, maintaining consistent label semantics.
 - Star icons are decorative and do not receive focus since the component is display-only.
+- A validation message is rendered below the rating and referenced from the control through `aria-describedby`, so a screen reader is told what is wrong rather than only that something is.
+- Invalid state comes from `useFormField`, so it reflects a surrounding `VcInputGroup` as well as the component's own `error` / `errorMessage`.
 
 ## Related Components