@vc-shell/vc-app-skill 2.6.0-rc.1-pr368.9a75b13 → 2.6.1-pr374.43f2115

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vc-shell/vc-app-skill",
-  "version": "2.6.0-rc.1-pr368.9a75b13",
+  "version": "2.6.1-pr374.43f2115",
   "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.1

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 ce2647528 on 2026-09-29T10:57:40.943Z

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/useResponsive/useResponsive.docs.md

@@ -50,12 +50,12 @@ None. The composable reads breakpoint state from the framework's provide/inject
 | Property    | Type           | Default | Description                                                           |
 | ----------- | -------------- | ------- | --------------------------------------------------------------------- |
 | `isMobile`  | `Ref<boolean>` | `false` | `true` when viewport width < 1024px                                   |
-| `isDesktop` | `Ref<boolean>` | `true`  | `true` when viewport width > 1024px                                   |
+| `isDesktop` | `Ref<boolean>` | `true`  | `true` when viewport width >= 1024px                                  |
 | `isPhone`   | `Ref<boolean>` | `false` | `true` when viewport width < 480px                                    |
 | `isTablet`  | `Ref<boolean>` | `false` | `true` when 480px <= viewport width < 1024px                          |
 | `isTouch`   | `boolean`      | `false` | `true` on touch-capable devices (not reactive — set once at app init) |
 
-Breakpoint thresholds: phone < 480px, tablet 480–1023px, desktop > 1024px (bound to `bp.greater("desktop")`, strictly greater than 1024px). These match the framework's `setupBreakpoints()` configuration.
+Breakpoint thresholds: phone < 480px, tablet 480–1023px, desktop >= 1024px (bound to `bp.greaterOrEqual("desktop")`, so exactly 1024px is desktop). These match the framework's `setupBreakpoints()` configuration.
 
 Note: `isMobile` is the union of `isPhone` and `isTablet` — it covers all viewports below the desktop threshold.
 

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