@vc-shell/vc-app-skill 2.2.0 → 2.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vc-shell/vc-app-skill",
-  "version": "2.2.0",
+  "version": "2.3.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.2.0
+2.3.0

package/runtime/knowledge/docs/_BUILD_HASH.md

@@ -1 +1 @@
-Synced from framework at commit 694fdf620 on 2026-07-20T17:03:47.353Z
+Synced from framework at commit eb3675e7a on 2026-07-28T09:06:26.940Z

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

@@ -172,6 +172,8 @@ const {
 
 By default, `useAsync` shows a toast notification on failure. The notification is **deferred** via `setTimeout(0)` so that the `ErrorInterceptor` can cancel it when a blade error banner is already displayed -- this prevents duplicate toast + banner for the same error.
 
+No toast is scheduled at all while the session is flagged as expired. When a platform API call returns 401, the fetch interceptor signs the user out and redirects to the login page; every data load in flight on the page being left fails at the same time. Suppressing those toasts keeps the single "session expired" message from being buried under a cascade of load errors. The `error` ref is still populated as usual -- only the toast is skipped -- and the flag is cleared when a new sign-in begins.
+
 ```typescript
 // Default: shows toast on error
 const { action: save } = useAsync(async () => {
@@ -419,6 +421,7 @@ const { action: save, loading: saveLoading } = useAsync(async () => saveData());
 - Errors are parsed via `parseError()` into `DisplayableError` objects that have a user-friendly `message` property.
 - Toast notifications are deferred with `setTimeout(0)` and registered via `setPendingErrorNotification`. The `ErrorInterceptor` (blade-level `onErrorCaptured`) can call `cancelPendingErrorNotification` to suppress the toast when a blade error banner is shown instead.
 - The notification module is lazy-imported to avoid circular dependencies with `@core/composables`.
+- `isSessionExpired()` from `@core/utilities/sessionExpiration` gates the notification. The flag is set by the fetch interceptor on the 401 that kills the session and cleared by `useUser.signIn`. It is imported directly, not through the `@core/utilities` barrel, for the same circular-dependency reason as `pendingErrorNotifications`.
 
 <!-- internal:end -->
 

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

@@ -234,6 +234,24 @@ registerToolbarItem({
 });
 ```
 
+### Keyboard shortcut for a button
+
+Add `shortcut: hotkey.mod.s` to give a button a `Cmd/Ctrl+S`-style shortcut. The button automatically shows an OS-aware `⌘S`/`Ctrl+S` tooltip and sets `aria-keyshortcuts` -- no extra wiring:
+
+```typescript
+import { hotkey } from "@vc-shell/framework";
+
+registerToolbarItem({
+  id: "save",
+  title: "Save",
+  icon: "fas fa-save",
+  clickHandler: () => save(),
+  shortcut: hotkey.mod.s,
+});
+```
+
+See [useKeyboardShortcuts](../useKeyboardShortcuts/) for the full `hotkey` builder, OS adaptation, and accessibility details.
+
 ## Common mistakes
 
 ### Reaching for `useToolbar` before considering the array pattern
@@ -334,18 +352,19 @@ function helperFunction() {
 
 ### IToolbarItem
 
-| Property       | Type                                                                                                              | Required | Description                                                    |
-| -------------- | ----------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------- |
-| `id`           | `string`                                                                                                          | Yes      | Unique identifier for the button                               |
-| `title`        | `string \| Ref<string> \| ComputedRef<string>`                                                                    | No       | Button label (supports reactive values)                        |
-| `icon`         | `string \| (() => string)`                                                                                        | No       | Icon class (e.g., `"fas fa-save"`) or a function returning one |
-| `clickHandler` | `(app?) => void`                                                                                                  | No       | Click callback                                                 |
-| `disabled`     | `boolean \| ComputedRef<boolean \| undefined>`                                                                    | No       | Whether the button is disabled                                 |
-| `isVisible`    | `boolean \| Ref<boolean \| undefined> \| ComputedRef<boolean \| undefined> \| ((blade?) => boolean \| undefined)` | No       | Controls button visibility                                     |
-| `priority`     | `number`                                                                                                          | No       | Sort order (higher = displayed first, default `0`)             |
-| `separator`    | `"left" \| "right" \| "both"`                                                                                     | No       | Adds a visual divider next to the button                       |
-| `permissions`  | `string \| string[]`                                                                                              | No       | Required permission(s) to display the button                   |
-| `bladeId`      | `string`                                                                                                          | No       | Target blade ID (auto-resolved from context)                   |
+| Property       | Type                                                                                                              | Required | Description                                                                                                                 |
+| -------------- | ----------------------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `id`           | `string`                                                                                                          | Yes      | Unique identifier for the button                                                                                            |
+| `title`        | `string \| Ref<string> \| ComputedRef<string>`                                                                    | No       | Button label (supports reactive values)                                                                                     |
+| `icon`         | `string \| (() => string)`                                                                                        | No       | Icon class (e.g., `"fas fa-save"`) or a function returning one                                                              |
+| `clickHandler` | `(app?) => void`                                                                                                  | No       | Click callback                                                                                                              |
+| `disabled`     | `boolean \| ComputedRef<boolean \| undefined>`                                                                    | No       | Whether the button is disabled                                                                                              |
+| `isVisible`    | `boolean \| Ref<boolean \| undefined> \| ComputedRef<boolean \| undefined> \| ((blade?) => boolean \| undefined)` | No       | Controls button visibility                                                                                                  |
+| `priority`     | `number`                                                                                                          | No       | Sort order (higher = displayed first, default `0`)                                                                          |
+| `separator`    | `"left" \| "right" \| "both"`                                                                                     | No       | Adds a visual divider next to the button                                                                                    |
+| `permissions`  | `string \| string[]`                                                                                              | No       | Required permission(s) to display the button                                                                                |
+| `bladeId`      | `string`                                                                                                          | No       | Target blade ID (auto-resolved from context)                                                                                |
+| `shortcut`     | `ShortcutDefinition`                                                                                              | No       | Keyboard shortcut that triggers `clickHandler`; build with `hotkey.*`. See [useKeyboardShortcuts](../useKeyboardShortcuts/) |
 
 `IToolbarItem` is the shape consumed by `ToolbarService`. The blade-level array binding uses `IBladeToolbar` (see [Core types](../../types/)), a near-identical shape that the framework normalizes into `IToolbarItem` before render.
 
@@ -354,4 +373,5 @@ function helperFunction() {
 - [useBlade](../useBlade/) -- blade context that toolbar items are scoped to
 - [usePermissions](../usePermissions/) -- conditionally register toolbar items based on permissions
 - [useAsync](../useAsync/) -- wraps async operations with loading state for disabling buttons
+- [useKeyboardShortcuts](../useKeyboardShortcuts/) -- the `hotkey` builder and OS-aware formatting behind the `shortcut` field
 - `IBladeToolbar` in [Core types](../../types/) — the shape used by the `:toolbar-items` array binding

package/runtime/knowledge/docs/shell/components/error-interceptor/error-interceptor.docs.md

@@ -21,6 +21,7 @@ The component is renderless -- it renders its default slot and passes the curren
 2. When inside a blade (`hasBlade = true`), errors are intercepted and forwarded to `bladeStack.setBladeError()`. This displays the error in the blade's built-in error banner and prevents the error from propagating to the global error handler (avoiding duplicate toast notifications).
 3. When not inside a blade or when `capture` is true, errors are captured and exposed via the slot's `error` prop.
 4. Pending `useAsync` error notifications are cancelled via `cancelPendingErrorNotification` when the blade banner takes over.
+5. If the session has expired (a platform API call returned 401 and the app is redirecting to login), the banner is skipped -- the deferred toast is still cancelled in step 4, so the failed load leaves no trace on the page being abandoned.
 
 ## Props
 
@@ -74,6 +75,7 @@ The component is renderless -- it renders its default slot and passes the curren
 - **Inside a blade**: Errors set `BladeDescriptor.error` via the stack. The blade header renders the error banner. Calling `reset` clears the blade error.
 - **Outside a blade** (with `capture`): Errors are stored in a local ref and exposed via slot props. No blade banner is involved.
 - **Error propagation**: When inside a blade, the error is stopped from propagating (prevents duplicate toasts from the global handler). The `capture` prop also stops propagation.
+- **Expired session**: While the session is flagged as expired, no blade banner is set. A dead auth cookie fails every data load on the page at once, and one redirect to login is more useful than a banner on each blade being left behind.
 
 ## Exports
 
@@ -93,4 +95,5 @@ The component must be imported before use, as shown above.
 
 - `framework/core/composables/useErrorHandler/` -- the underlying composable
 - `framework/core/utilities/pendingErrorNotifications.ts` -- cancels deferred toasts
+- `framework/core/utilities/sessionExpiration.ts` -- the expired-session flag that suppresses the banner
 - `framework/core/blade-navigation/` -- BladeStack error management (types the interceptor injects)