@ds-mo/ui 2.3.0 → 2.4.0

package/dist/types/components/AppShell/AppShell.d.ts

@@ -11,6 +11,8 @@ export declare class AppShell {
      * When set, overrides the built-in radial wash.
      */
     gradientSrc: string;
+    /** When `true` (default), registers global shell keyboard shortcuts. Tool chords (⌘/Ctrl+K/A/S/M/N) toggle their drawer open and closed; ⌘/Ctrl+[ toggles panel nav; ⌘/Ctrl+] closes any open tool drawer. */
+    shortcutsEnabled: boolean;
     el: HTMLElement;
     private resizeObserver;
     private readonly panelNavTransition;
@@ -40,6 +42,7 @@ export declare class AppShell {
     /** Fixed-attachment wash/grid size — always the viewport, never the shell element box. */
     private resolveViewportDimensions;
     private chromeLayerActive;
+    handleWindowKeyDown(e: KeyboardEvent): void;
     private syncChrome;
     render(): any;
 }

package/dist/types/components/PanelNav/PanelNav.d.ts

@@ -90,7 +90,6 @@ export declare class PanelNav {
     /** Centralised toggle: updates `collapsed`, emits `dsNavToggle`, optionally persists. */
     private applyToggle;
     private getAllItems;
-    private getRovingTotal;
     private getFooterRovingIndex;
     private getUserRovingIndex;
     private getRovingElement;
@@ -101,6 +100,8 @@ export declare class PanelNav {
     private handleBodyScroll;
     private handleItemClick;
     private handleToggle;
+    /** Toggle expanded/collapsed panel nav — used by shell keyboard shortcuts. */
+    toggleCollapsed(): Promise<void>;
     private handleFooterAction;
     private handleUserAction;
     private clearEdgeOverlayTimer;

package/dist/types/components/PanelTools/PanelTools.d.ts

@@ -45,6 +45,10 @@ export declare class PanelTools {
     private isViewActive;
     private headerLabel;
     private handleToolChange;
+    /** Toggle any rail tool open/closed — shell shortcuts ⌘/Ctrl+K/A/S/M/N call this. */
+    activateTool(id: PanelToolsToolId): Promise<void>;
+    /** Close the tools drawer when open — used by shell keyboard shortcuts. */
+    closeDrawer(): Promise<void>;
     private focusRailAt;
     private handleRailKeyDown;
     private renderRailAction;

package/dist/types/components/PanelTools/panel-tools-utils.d.ts

@@ -1,7 +1,13 @@
-import type { PanelToolsItem } from './panel-tools-types';
+import type { PanelToolsItem, PanelToolsToolId } from './panel-tools-types';
 export declare function parsePanelToolsItems(items: PanelToolsItem[], itemsJson: string): PanelToolsItem[];
 export declare function shouldResyncPanelToolsItems(prev: PanelToolsItem[], next: PanelToolsItem[]): boolean;
 export type PanelToolsMotion = 'opening' | 'closing' | 'idle';
 /** True when the drawer clip is fully closed — safe to skip painting slot content. */
 export declare function panelToolsDrawerResting(open: boolean, motion: PanelToolsMotion): boolean;
+/** Toggle or switch rail tool selection — repeat activation closes the active tool. */
+export declare function resolvePanelToolActivation(open: boolean, activeTool: PanelToolsToolId | '', id: PanelToolsToolId): {
+    open: boolean;
+    activeTool: PanelToolsToolId;
+    selected: boolean;
+};
 //# sourceMappingURL=panel-tools-utils.d.ts.map

package/dist/types/components.d.ts

@@ -118,6 +118,11 @@ export namespace Components {
           * @default 'dashboard'
          */
         "navStyle": NavChromeStyle;
+        /**
+          * When `true` (default), registers global shell keyboard shortcuts. Tool chords (⌘/Ctrl+K/A/S/M/N) toggle their drawer open and closed; ⌘/Ctrl+[ toggles panel nav; ⌘/Ctrl+] closes any open tool drawer.
+          * @default true
+         */
+        "shortcutsEnabled": boolean;
     }
     interface DsBadge {
         /**
@@ -697,6 +702,10 @@ export namespace Components {
           * @default ''
          */
         "storageKey": string;
+        /**
+          * Toggle expanded/collapsed panel nav — used by shell keyboard shortcuts.
+         */
+        "toggleCollapsed": () => Promise<void>;
         /**
           * Single character shown in the collapsed avatar
           * @default ''
@@ -709,11 +718,19 @@ export namespace Components {
         "userName": string;
     }
     interface DsPanelTools {
+        /**
+          * Toggle any rail tool open/closed — shell shortcuts ⌘/Ctrl+K/A/S/M/N call this.
+         */
+        "activateTool": (id: PanelToolsToolId) => Promise<void>;
         /**
           * Active tool view — `search`, `agents`, `messages`, `stacks`, or `activity`.
           * @default ''
          */
         "activeTool": PanelToolsToolId | '';
+        /**
+          * Close the tools drawer when open — used by shell keyboard shortcuts.
+         */
+        "closeDrawer": () => Promise<void>;
         /**
           * Rail items rendered in the right column. Set via JS property: `el.items = [...]`. Replace the array reference to update.
           * @default []
@@ -1838,6 +1855,11 @@ declare namespace LocalJSX {
           * @default 'dashboard'
          */
         "navStyle"?: NavChromeStyle;
+        /**
+          * When `true` (default), registers global shell keyboard shortcuts. Tool chords (⌘/Ctrl+K/A/S/M/N) toggle their drawer open and closed; ⌘/Ctrl+[ toggles panel nav; ⌘/Ctrl+] closes any open tool drawer.
+          * @default true
+         */
+        "shortcutsEnabled"?: boolean;
     }
     interface DsBadge {
         /**
@@ -2942,6 +2964,7 @@ declare namespace LocalJSX {
         "gradient": boolean;
         "grid": boolean;
         "gradientSrc": string;
+        "shortcutsEnabled": boolean;
     }
     interface DsBadgeAttributes {
         "variant": BadgeVariant;

package/dist/types/nav/shell-shortcuts.d.ts

@@ -0,0 +1,10 @@
+import type { PanelToolsToolId } from '../components/PanelTools/panel-tools-types';
+export type ShellShortcutAction = 'toggle-panel-nav' | 'close-panel-tools' | `open-tool:${PanelToolsToolId}`;
+/** Tool shortcut chords (⌘/Ctrl+K/A/S/M/N) toggle open/closed via `ds-panel-tools.activateTool`. */
+/** True when Cmd (macOS) or Ctrl (Windows/Linux) is held without Alt/Shift. */
+export declare function isShellShortcutModifier(e: Pick<KeyboardEvent, 'metaKey' | 'ctrlKey' | 'altKey' | 'shiftKey'>): boolean;
+/** Skip shell shortcuts while typing in an editable control. */
+export declare function isEditableShortcutTarget(target: EventTarget | null): boolean;
+/** Resolve a shell chrome shortcut, or `null` when the chord is not handled. */
+export declare function resolveShellShortcut(e: Pick<KeyboardEvent, 'key' | 'code' | 'metaKey' | 'ctrlKey' | 'altKey' | 'shiftKey'>): ShellShortcutAction | null;
+//# sourceMappingURL=shell-shortcuts.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ds-mo/ui",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "CompoMo — composable web components styled with TokoMo design tokens",
   "keywords": [
     "web-components",
@@ -69,7 +69,7 @@
     "pretest": "node scripts/generate-icon-catalog.mjs",
     "build": "stencil build && node scripts/patch-index-types.mjs && node scripts/verify-icons-externalized.mjs && node scripts/write-build-stamp.mjs",
     "verify:pack": "node scripts/verify-npm-pack.mjs && node scripts/verify-nav-import.mjs",
-    "test": "node --import tsx/esm --test tests/panel-nav-utils.test.ts tests/panel-tools.test.ts tests/shell-view-transition.test.ts tests/shell-gradient.test.ts tests/shell-chrome-metrics.test.ts tests/shell-chrome-layer.test.ts tests/chrome-transition.test.ts tests/bar-nav-overflow-hysteresis.test.ts tests/badge-gradient-ring.test.ts tests/scroll-edge-fade.test.ts tests/resolve-css-length-px.test.ts tests/resolve-css-time-ms.test.ts tests/overlay-positioning.test.ts tests/menu-position.test.ts tests/bar-nav-utils.test.ts tests/bar-nav-tabs-menu-utils.test.ts tests/bar-nav-dom-utils.test.ts tests/icon-catalog.test.ts",
+    "test": "node --import tsx/esm --test tests/panel-nav-utils.test.ts tests/panel-tools.test.ts tests/shell-shortcuts.test.ts tests/shell-view-transition.test.ts tests/shell-gradient.test.ts tests/shell-chrome-metrics.test.ts tests/shell-chrome-layer.test.ts tests/chrome-transition.test.ts tests/bar-nav-overflow-hysteresis.test.ts tests/badge-gradient-ring.test.ts tests/scroll-edge-fade.test.ts tests/resolve-css-length-px.test.ts tests/resolve-css-time-ms.test.ts tests/overlay-positioning.test.ts tests/menu-position.test.ts tests/bar-nav-utils.test.ts tests/bar-nav-tabs-menu-utils.test.ts tests/bar-nav-dom-utils.test.ts tests/icon-catalog.test.ts",
     "test:e2e": "npm run build && playwright test",
     "test:e2e:install": "playwright install chromium",
     "build:docs": "stencil build --docs",

package/src/angular/proxies.ts

@@ -36,14 +36,14 @@ export declare interface DsAccordion extends Components.DsAccordion {
 
 
 @ProxyCmp({
-  inputs: ['gradient', 'gradientSrc', 'grid', 'navStyle']
+  inputs: ['gradient', 'gradientSrc', 'grid', 'navStyle', 'shortcutsEnabled']
 })
 @Component({
   selector: 'ds-app-shell',
   changeDetection: ChangeDetectionStrategy.OnPush,
   template: '<ng-content></ng-content>',
   // eslint-disable-next-line @angular-eslint/no-inputs-metadata-property
-  inputs: ['gradient', 'gradientSrc', 'grid', 'navStyle'],
+  inputs: ['gradient', 'gradientSrc', 'grid', 'navStyle', 'shortcutsEnabled'],
   standalone: false
 })
 export class DsAppShell {
@@ -639,7 +639,8 @@ export declare interface DsPagination extends Components.DsPagination {
 
 
 @ProxyCmp({
-  inputs: ['activeId', 'breakpoint', 'collapsed', 'currentUrl', 'disableViewTransition', 'groups', 'navStyle', 'routerMode', 'storageKey', 'userInitial', 'userName']
+  inputs: ['activeId', 'breakpoint', 'collapsed', 'currentUrl', 'disableViewTransition', 'groups', 'navStyle', 'routerMode', 'storageKey', 'userInitial', 'userName'],
+  methods: ['toggleCollapsed']
 })
 @Component({
   selector: 'ds-panel-nav',
@@ -695,7 +696,8 @@ export declare interface DsPanelNav extends Components.DsPanelNav {
 
 
 @ProxyCmp({
-  inputs: ['activeTool', 'items', 'itemsJson', 'open']
+  inputs: ['activeTool', 'items', 'itemsJson', 'open'],
+  methods: ['activateTool', 'closeDrawer']
 })
 @Component({
   selector: 'ds-panel-tools',

package/src/wc/components/AppShell/AppShell.tsx

@@ -1,5 +1,10 @@
-import { Component, Prop, Element, Watch, h, Host } from '@stencil/core';
+import { Component, Prop, Element, Watch, Listen, h, Host } from '@stencil/core';
 import type { NavChromeStyle } from '../../nav/nav-chrome';
+import {
+  isEditableShortcutTarget,
+  resolveShellShortcut,
+} from '../../nav/shell-shortcuts';
+import type { PanelToolsToolId } from '../PanelTools/panel-tools-types';
 import {
   CHROME_TRANSITION_END,
   CHROME_TRANSITION_START,
@@ -48,6 +53,9 @@ export class AppShell {
    */
   @Prop() gradientSrc: string = '';
 
+  /** When `true` (default), registers global shell keyboard shortcuts. Tool chords (⌘/Ctrl+K/A/S/M/N) toggle their drawer open and closed; ⌘/Ctrl+[ toggles panel nav; ⌘/Ctrl+] closes any open tool drawer. */
+  @Prop({ attribute: 'shortcuts-enabled' }) shortcutsEnabled: boolean = true;
+
   @Element() el!: HTMLElement;
 
   private resizeObserver: ResizeObserver | null = null;
@@ -242,6 +250,35 @@ export class AppShell {
     return this.gradient || this.grid;
   }
 
+  @Listen('keydown', { target: 'window', capture: true })
+  handleWindowKeyDown(e: KeyboardEvent) {
+    if (!this.shortcutsEnabled) return;
+    if (isEditableShortcutTarget(e.target)) return;
+
+    const action = resolveShellShortcut(e);
+    if (!action) return;
+
+    e.preventDefault();
+
+    const panel = this.el.querySelector('ds-panel-nav') as HTMLDsPanelNavElement | null;
+    const tools = this.el.querySelector('ds-panel-tools') as HTMLDsPanelToolsElement | null;
+
+    if (action === 'toggle-panel-nav') {
+      void panel?.toggleCollapsed();
+      return;
+    }
+
+    if (action === 'close-panel-tools') {
+      void tools?.closeDrawer();
+      return;
+    }
+
+    if (action.startsWith('open-tool:') && tools) {
+      const toolId = action.slice('open-tool:'.length) as PanelToolsToolId;
+      void tools.activateTool(toolId);
+    }
+  }
+
   private syncChrome() {
     const panelNav = this.el.querySelector('ds-panel-nav') as HTMLElement | null;
     const bar = this.el.querySelector('ds-bar-nav') as HTMLElement | null;

package/src/wc/components/PanelNav/PanelNav.tsx

@@ -1,4 +1,4 @@
-import { Component, Prop, Event, EventEmitter, Watch, State, Element, h, Host } from '@stencil/core';
+import { Component, Prop, Event, EventEmitter, Watch, State, Element, Method, h, Host } from '@stencil/core';
 import type { ChromeTransitionDetail } from '../../nav/chrome-transition';
 import type { NavChromeStyle } from '../../nav/nav-chrome';
 import {
@@ -288,10 +288,6 @@ export class PanelNav {
     return this.parsedGroups.flatMap(g => g.items);
   }
 
-  private getRovingTotal(): number {
-    return 1 + this.getAllItems().length + 2;
-  }
-
   private getFooterRovingIndex(): number {
     return 1 + this.getAllItems().length;
   }
@@ -351,35 +347,29 @@ export class PanelNav {
       return;
     }
 
-    const total = this.getRovingTotal();
     const footerIdx = this.getFooterRovingIndex();
     const userIdx = this.getUserRovingIndex();
-    let next: number;
+    let next: number | undefined;
 
     switch (e.key) {
       case 'ArrowDown':
-        e.preventDefault();
+        if (index === userIdx) return;
         if (index === footerIdx) next = userIdx;
-        else if (index === userIdx) next = 0;
-        else next = (index + 1) % total;
+        else next = index + 1;
         break;
       case 'ArrowUp':
-        e.preventDefault();
-        if (index === 0) next = userIdx;
-        else if (index === userIdx) next = footerIdx;
-        else next = (index - 1 + total) % total;
+        if (index === 0) return;
+        if (index === userIdx) next = footerIdx;
+        else if (index === footerIdx) next = footerIdx - 1;
+        else next = index - 1;
         break;
       case 'ArrowRight':
-        if (index === footerIdx) {
-          e.preventDefault();
-          next = userIdx;
-        } else return;
+        if (index === footerIdx) next = userIdx;
+        else return;
         break;
       case 'ArrowLeft':
-        if (index === userIdx) {
-          e.preventDefault();
-          next = footerIdx;
-        } else return;
+        if (index === userIdx) next = footerIdx;
+        else return;
         break;
       case 'Home':
         e.preventDefault();
@@ -393,6 +383,8 @@ export class PanelNav {
         return;
     }
 
+    if (next === undefined || next === index) return;
+    e.preventDefault();
     this.focusRovingAt(next);
   }
 
@@ -417,6 +409,12 @@ export class PanelNav {
     this.applyToggle(!this.collapsed);
   }
 
+  /** Toggle expanded/collapsed panel nav — used by shell keyboard shortcuts. */
+  @Method()
+  async toggleCollapsed() {
+    this.handleToggle();
+  }
+
   private handleFooterAction() {
     this.dsNavFooterAction.emit();
   }

package/src/wc/components/PanelTools/PanelTools.tsx

@@ -1,4 +1,4 @@
-import { Component, Prop, Event, EventEmitter, Element, State, Watch, h, Host } from '@stencil/core';
+import { Component, Prop, Event, EventEmitter, Element, State, Watch, Method, h, Host } from '@stencil/core';
 import type { ChromeTransitionDetail } from '../../nav/chrome-transition';
 import {
   PANEL_TOOLS_LABELS,
@@ -6,7 +6,7 @@ import {
   type PanelToolsItem,
   type PanelToolsToolId,
 } from './panel-tools-types';
-import { parsePanelToolsItems, panelToolsDrawerResting } from './panel-tools-utils';
+import { parsePanelToolsItems, panelToolsDrawerResting, resolvePanelToolActivation } from './panel-tools-utils';
 
 @Component({
   tag: 'ds-panel-tools',
@@ -142,20 +142,36 @@ export class PanelTools {
   }
 
   private handleToolChange = (id: PanelToolsToolId) => {
-    const selected = !this.isRailSelected(id);
-    if (selected) {
-      this.open = true;
-      this.activeTool = id;
-    } else {
-      this.open = false;
-    }
-    this.dsToolChange.emit({ id, selected });
+    const next = resolvePanelToolActivation(this.open, this.activeTool, id);
+    this.open = next.open;
+    this.activeTool = next.activeTool;
+    this.dsToolChange.emit({ id, selected: next.selected });
   };
 
+  /** Toggle any rail tool open/closed — shell shortcuts ⌘/Ctrl+K/A/S/M/N call this. */
+  @Method()
+  async activateTool(id: PanelToolsToolId) {
+    const item = this.railItems.find(entry => entry.id === id);
+    if (!item || item.inactive) return;
+    this.handleToolChange(id);
+  }
+
+  /** Close the tools drawer when open — used by shell keyboard shortcuts. */
+  @Method()
+  async closeDrawer() {
+    if (!this.open) return;
+    const id = this.activeTool;
+    this.open = false;
+    if (id) {
+      this.dsToolChange.emit({ id, selected: false });
+    }
+  }
+
   private focusRailAt(index: number) {
     const items = this.orderedRailItems;
     if (!items.length) return;
-    const bounded = ((index % items.length) + items.length) % items.length;
+    const bounded = Math.max(0, Math.min(index, items.length - 1));
+    if (bounded === this.rovingIndex) return;
     this.rovingIndex = bounded;
     const actions = Array.from(
       this.el.querySelectorAll<HTMLElement>('.panel-tools__rail-action .button-icon'),
@@ -174,12 +190,14 @@ export class PanelTools {
     }
 
     if (e.key === 'ArrowDown') {
+      if (index >= items.length - 1) return;
       e.preventDefault();
       this.focusRailAt(index + 1);
       return;
     }
 
     if (e.key === 'ArrowUp') {
+      if (index <= 0) return;
       e.preventDefault();
       this.focusRailAt(index - 1);
     }

package/src/wc/components/PanelTools/panel-tools-utils.ts

@@ -1,5 +1,5 @@
 import { parseJsonArrayProp } from '../BarNav/bar-nav-utils';
-import type { PanelToolsItem } from './panel-tools-types';
+import type { PanelToolsItem, PanelToolsToolId } from './panel-tools-types';
 
 export function parsePanelToolsItems(
   items: PanelToolsItem[],
@@ -36,3 +36,15 @@ export type PanelToolsMotion = 'opening' | 'closing' | 'idle';
 export function panelToolsDrawerResting(open: boolean, motion: PanelToolsMotion): boolean {
   return !open && motion === 'idle';
 }
+
+/** Toggle or switch rail tool selection — repeat activation closes the active tool. */
+export function resolvePanelToolActivation(
+  open: boolean,
+  activeTool: PanelToolsToolId | '',
+  id: PanelToolsToolId,
+): { open: boolean; activeTool: PanelToolsToolId; selected: boolean } {
+  if (open && activeTool === id) {
+    return { open: false, activeTool: id, selected: false };
+  }
+  return { open: true, activeTool: id, selected: true };
+}

package/src/wc/components.d.ts

@@ -118,6 +118,11 @@ export namespace Components {
           * @default 'dashboard'
          */
         "navStyle": NavChromeStyle;
+        /**
+          * When `true` (default), registers global shell keyboard shortcuts. Tool chords (⌘/Ctrl+K/A/S/M/N) toggle their drawer open and closed; ⌘/Ctrl+[ toggles panel nav; ⌘/Ctrl+] closes any open tool drawer.
+          * @default true
+         */
+        "shortcutsEnabled": boolean;
     }
     interface DsBadge {
         /**
@@ -697,6 +702,10 @@ export namespace Components {
           * @default ''
          */
         "storageKey": string;
+        /**
+          * Toggle expanded/collapsed panel nav — used by shell keyboard shortcuts.
+         */
+        "toggleCollapsed": () => Promise<void>;
         /**
           * Single character shown in the collapsed avatar
           * @default ''
@@ -709,11 +718,19 @@ export namespace Components {
         "userName": string;
     }
     interface DsPanelTools {
+        /**
+          * Toggle any rail tool open/closed — shell shortcuts ⌘/Ctrl+K/A/S/M/N call this.
+         */
+        "activateTool": (id: PanelToolsToolId) => Promise<void>;
         /**
           * Active tool view — `search`, `agents`, `messages`, `stacks`, or `activity`.
           * @default ''
          */
         "activeTool": PanelToolsToolId | '';
+        /**
+          * Close the tools drawer when open — used by shell keyboard shortcuts.
+         */
+        "closeDrawer": () => Promise<void>;
         /**
           * Rail items rendered in the right column. Set via JS property: `el.items = [...]`. Replace the array reference to update.
           * @default []
@@ -1838,6 +1855,11 @@ declare namespace LocalJSX {
           * @default 'dashboard'
          */
         "navStyle"?: NavChromeStyle;
+        /**
+          * When `true` (default), registers global shell keyboard shortcuts. Tool chords (⌘/Ctrl+K/A/S/M/N) toggle their drawer open and closed; ⌘/Ctrl+[ toggles panel nav; ⌘/Ctrl+] closes any open tool drawer.
+          * @default true
+         */
+        "shortcutsEnabled"?: boolean;
     }
     interface DsBadge {
         /**
@@ -2942,6 +2964,7 @@ declare namespace LocalJSX {
         "gradient": boolean;
         "grid": boolean;
         "gradientSrc": string;
+        "shortcutsEnabled": boolean;
     }
     interface DsBadgeAttributes {
         "variant": BadgeVariant;

package/src/wc/nav/shell-shortcuts.ts

@@ -0,0 +1,63 @@
+import type { PanelToolsToolId } from '../components/PanelTools/panel-tools-types';
+
+export type ShellShortcutAction =
+  | 'toggle-panel-nav'
+  | 'close-panel-tools'
+  | `open-tool:${PanelToolsToolId}`;
+
+const TOOL_SHORTCUT_KEYS: Record<string, PanelToolsToolId> = {
+  k: 'search',
+  a: 'agents',
+  s: 'stacks',
+  m: 'messages',
+  n: 'activity',
+};
+
+/** Tool shortcut chords (⌘/Ctrl+K/A/S/M/N) toggle open/closed via `ds-panel-tools.activateTool`. */
+
+/** True when Cmd (macOS) or Ctrl (Windows/Linux) is held without Alt/Shift. */
+export function isShellShortcutModifier(
+  e: Pick<KeyboardEvent, 'metaKey' | 'ctrlKey' | 'altKey' | 'shiftKey'>,
+): boolean {
+  return (e.metaKey || e.ctrlKey) && !e.altKey && !e.shiftKey;
+}
+
+/** Skip shell shortcuts while typing in an editable control. */
+export function isEditableShortcutTarget(target: EventTarget | null): boolean {
+  if (!target || typeof target !== 'object') return false;
+  if (!('closest' in target) || typeof target.closest !== 'function') return false;
+
+  const el = target as Element & { isContentEditable?: boolean };
+
+  const editable = el.closest(
+    'input, textarea, select, [contenteditable=""], [contenteditable="true"], [contenteditable="plaintext-only"]',
+  );
+  if (editable) return true;
+
+  const role = el.getAttribute('role');
+  if (role === 'textbox' || role === 'combobox' || role === 'searchbox') return true;
+
+  return Boolean(el.isContentEditable);
+}
+
+function normalizedShortcutKey(e: Pick<KeyboardEvent, 'key' | 'code'>): string {
+  if (e.key === '[' || e.code === 'BracketLeft') return '[';
+  if (e.key === ']' || e.code === 'BracketRight') return ']';
+  return e.key.length === 1 ? e.key.toLowerCase() : e.key.toLowerCase();
+}
+
+/** Resolve a shell chrome shortcut, or `null` when the chord is not handled. */
+export function resolveShellShortcut(
+  e: Pick<KeyboardEvent, 'key' | 'code' | 'metaKey' | 'ctrlKey' | 'altKey' | 'shiftKey'>,
+): ShellShortcutAction | null {
+  if (!isShellShortcutModifier(e)) return null;
+
+  const key = normalizedShortcutKey(e);
+  if (key === '[') return 'toggle-panel-nav';
+  if (key === ']') return 'close-panel-tools';
+
+  const toolId = TOOL_SHORTCUT_KEYS[key];
+  if (toolId) return `open-tool:${toolId}`;
+
+  return null;
+}