@ds-mo/ui 12.3.0 → 12.4.0

package/dist/mcp-data/registry/shell-app.json

@@ -16,7 +16,7 @@
       "summary": "The single required workspace root for standard authenticated application pages, coordinating primary and secondary navigation, tools chrome, responsive composition, content geometry, shared styling, and shell behavior.",
       "useWhen": [
         "Building any standard authenticated product or workspace page with CompoMo.",
-        "PanelNav, BarNav, PanelTools, page content, shared chrome, responsive behavior, and shell shortcuts must be composed as one application frame.",
+        "PanelNav, BarNav, ShellTools, mobile navigation, page content, shared chrome, responsive behavior, and shell shortcuts must be composed as one application frame.",
         "Future application templates need the supported base-page composition boundary."
       ],
       "avoidWhen": [
@@ -28,6 +28,10 @@
         "component:ds-panel-nav",
         "component:ds-bar-nav",
         "component:ds-panel-tools",
+        "component:ds-shell-tools",
+        "component:ds-shell-mobile-nav",
+        "component:ds-shell-mobile-section-nav",
+        "component:ds-shell-mobile-bar",
         "component:ds-shell-page",
         "component:ds-swatch-picker"
       ],
@@ -38,16 +42,17 @@
       "accessibility": [
         "Keep primary destinations in PanelNav and secondary route sections in BarNav.",
         "Ensure the default content region contains the page's single main landmark.",
-        "Keep PanelNav, BarNav, and PanelTools chrome available in the shell's supported desktop and tablet compositions.",
+        "Keep PanelNav, BarNav, and PanelTools-compatible chrome available in desktop and tablet compositions and the persistent mobile bar available below 768px.",
         "Do not override browser keyboard chords when enabling shell shortcuts.",
         "Require Search and Help as the minimum PanelTools actions and provide accessible labels for every tool.",
         "Preserve focus and accessible names across navigation, collapse, overflow, and responsive presentation changes."
       ],
       "states": [
         "Render exactly one ShellApp as the workspace root and never nest it.",
-        "PanelNav, BarNav, and PanelTools are required shell regions; PanelTools contains at least Search and Help even when no additional product tools apply.",
+        "PanelNav, BarNav, and ShellTools are the responsive shell regions; ShellTools contains at least Search and Help even when no additional product tools apply.",
         "The application router owns the current route, authorization filtering, Dashboard or Settings context, destination collections, section collections, and localized content labels.",
-        "ShellApp propagates navStyle and coordinates layout, gradient alignment, transitions, metrics, shortcuts, and responsive composition.",
+        "ShellApp propagates navStyle and resolved responsive mode and coordinates layout, gradient alignment, transitions, metrics, shortcuts, and mobile-stage visibility.",
+        "The application controls mobileDestination and mobileNavigationOpen and keeps router state independent from global tool-surface changes.",
         "Set gradientPreset to the single resolved global chrome preference: neutral by default, none for solid chrome, or cool, neutral, warm, and fresh for token-based washes.",
         "The application owns gradient preference persistence, cross-tab synchronization, and server or account precedence; ShellApp owns rendering the resolved preset across authenticated routes.",
         "Dashboard represents day-to-day operational work while Settings represents administrative and configuration work; route state selects the context.",
@@ -60,9 +65,10 @@
         "ShellApp owns the fixed system breakpoints and resolves desktop at 1200px and wider, tablet from 768px through 1199px, and mobile below 768px.",
         "On desktop, PanelNav defaults expanded, permits user collapse or expansion, and respects the locally persisted desktop preference.",
         "On tablet, ShellApp keeps PanelNav permanently collapsed and prevents user expansion without overwriting the desktop preference.",
-        "On mobile, ShellApp remains the page root but replaces PanelNav and desktop navigation composition with a future dedicated mobile navigation design.",
+        "On mobile, ShellApp hides and inerts PanelNav and BarNav, uses a solid primary stage, and composes MobileNav, MobileSectionNav, ShellTools, and the persistent five-item MobileBar.",
+        "Mobile global surfaces conceal and inert the routed workspace without unmounting it, preserving nested routes and scroll state.",
         "Keep PanelNav width, BarNav height, PanelTools chrome, and main-content origin stable except during intentional responsive or collapse transitions.",
-        "The current runtime does not yet implement the complete desktop, tablet, and mobile composition contract; consuming applications must enforce missing breakpoint behavior until ShellApp provides it."
+        "The bottom bar remains visible at all route and tool depths in the foundation release."
       ],
       "frameworkCaveats": {
         "customElements": [
@@ -70,7 +76,7 @@
           "Stamp route-derived nav-style before components connect when deterministic first paint is required."
         ],
         "react": [
-          "Use generated wrappers and preserve native slot names for PanelNav, BarNav, PanelTools, and main content.",
+          "Use generated wrappers and preserve native slot names for desktop navigation, responsive tools, mobile navigation, and main content.",
           "Resolve all shell inputs from one router state before rendering the composition."
         ],
         "angular": [
@@ -109,6 +115,24 @@
           "mutable": false,
           "description": "Shell chrome wash preset. `none` renders solid chrome; the remaining\npresets use token-based washes that adapt to the active color theme."
         },
+        "mobileDestination": {
+          "type": "ShellMobileDestination",
+          "resolvedType": "\"agents\" | \"area\" | \"inbox\" | \"search\"",
+          "attribute": "mobile-destination",
+          "default": "'area'",
+          "required": false,
+          "mutable": false,
+          "description": "Controlled mobile surface shown above the persistent bottom bar."
+        },
+        "mobileNavigationOpen": {
+          "type": "boolean",
+          "resolvedType": "boolean",
+          "attribute": "mobile-navigation-open",
+          "default": "false",
+          "required": false,
+          "mutable": false,
+          "description": "Controlled full-stage mobile navigation-pane state."
+        },
         "navStyle": {
           "type": "NavChromeStyle",
           "resolvedType": "\"dashboard\" | \"settings\"",
@@ -128,7 +152,16 @@
           "description": "When `true` (default), registers global shell keyboard shortcuts. `[` toggles panel nav; `]` closes tools; K, A, S, M, N, and / toggle tool drawers. Modifiers are ignored so browser chords like ⌘N stay native."
         }
       },
-      "events": [],
+      "events": [
+        {
+          "name": "dsResponsiveModeChange",
+          "detail": "{ mode: ShellResponsiveMode }",
+          "bubbles": true,
+          "cancelable": true,
+          "composed": true,
+          "description": "Emitted after crossing the fixed 768px or 1200px shell boundaries."
+        }
+      ],
       "methods": [],
       "slots": []
     },
@@ -142,6 +175,24 @@
         "mutable": false,
         "description": "Shell chrome wash preset. `none` renders solid chrome; the remaining\npresets use token-based washes that adapt to the active color theme."
       },
+      "mobileDestination": {
+        "type": "ShellMobileDestination",
+        "resolvedType": "\"agents\" | \"area\" | \"inbox\" | \"search\"",
+        "attribute": "mobile-destination",
+        "default": "'area'",
+        "required": false,
+        "mutable": false,
+        "description": "Controlled mobile surface shown above the persistent bottom bar."
+      },
+      "mobileNavigationOpen": {
+        "type": "boolean",
+        "resolvedType": "boolean",
+        "attribute": "mobile-navigation-open",
+        "default": "false",
+        "required": false,
+        "mutable": false,
+        "description": "Controlled full-stage mobile navigation-pane state."
+      },
       "navStyle": {
         "type": "NavChromeStyle",
         "resolvedType": "\"dashboard\" | \"settings\"",
@@ -161,7 +212,16 @@
         "description": "When `true` (default), registers global shell keyboard shortcuts. `[` toggles panel nav; `]` closes tools; K, A, S, M, N, and / toggle tool drawers. Modifiers are ignored so browser chords like ⌘N stay native."
       }
     },
-    "events": [],
+    "events": [
+      {
+        "name": "dsResponsiveModeChange",
+        "detail": "{ mode: ShellResponsiveMode }",
+        "bubbles": true,
+        "cancelable": true,
+        "composed": true,
+        "description": "Emitted after crossing the fixed 768px or 1200px shell boundaries."
+      }
+    ],
     "methods": [],
     "slots": [],
     "exports": {
@@ -201,12 +261,12 @@
   "files": [
     {
       "path": "src/wc/components/ShellApp/ShellApp.css",
-      "content": ":host {\n  display: block;\n  height: 100%;\n  min-height: 0;\n  box-sizing: border-box;\n  overflow: hidden;\n  overscroll-behavior: none;\n  --ds-shell-panel-tools-width: var(--dimension-panel-width-xs);\n}\n\n.shell-app {\n  display: flex;\n  flex-direction: column;\n  height: 100%;\n  min-height: 0;\n  box-sizing: border-box;\n  overflow: hidden;\n  overscroll-behavior: none;\n  font-family: var(--typography-font-family, system-ui);\n}\n\n:host {\n  --_shell-chrome-bg: var(--color-background-secondary);\n}\n\n.shell-app__row {\n  display: flex;\n  flex: 1 1 auto;\n  min-height: 0;\n  height: 100%;\n  position: relative;\n}\n\n/*\n * One chrome layer behind the shell row. Wash uses background-attachment: fixed\n * so the pattern is locked to the viewport — panel/tools collapse only changes the\n * transparent window, not the pattern phase. JS sets wash background-size from\n * readShellViewportDimensions(), not the shell element box.\n */\n.shell-app__chrome {\n  position: absolute;\n  inset: 0;\n  pointer-events: none;\n  z-index: 0;\n  background-color: var(--_shell-chrome-bg);\n}\n\n:host(.shell-app--gradient) .shell-app__chrome::before {\n  content: '';\n  position: absolute;\n  inset: 0;\n  pointer-events: none;\n  background-position: 0 0;\n  background-attachment: fixed;\n  z-index: 1;\n  opacity: var(--ds-shell-gradient-opacity, 1);\n  background-image: var(--ds-shell-gradient-image, none);\n  background-size: var(--ds-shell-gradient-size, auto);\n  background-repeat: no-repeat;\n}\n\n.shell-app__panel {\n  flex: 0 0 auto;\n  min-height: 0;\n  height: 100%;\n  position: relative;\n  /* Above main so resize handle line can paint over the workspace edge */\n  z-index: 2;\n}\n\n.shell-app__panel ::slotted(ds-panel-nav) {\n  display: block;\n  height: 100%;\n}\n\n.shell-app__main {\n  flex: 1 1 auto;\n  min-width: 0;\n  min-height: 0;\n  display: grid;\n  grid-template-columns: minmax(0, 1fr) auto;\n  grid-template-rows: auto minmax(0, 1fr);\n  grid-template-areas:\n    'bar tools'\n    'content tools';\n  position: relative;\n  z-index: 1;\n}\n\n.shell-app__bar {\n  grid-area: bar;\n  flex: 0 0 auto;\n  min-width: 0;\n}\n\n.shell-app__bar ::slotted(ds-bar-nav) {\n  display: block;\n}\n\n.shell-app__content {\n  grid-area: content;\n  flex: 1 1 auto;\n  min-width: 0;\n  min-height: 0;\n  overflow: auto;\n  overscroll-behavior: none;\n  /* Limit reflow to the page column — not on __main (breaks tools flex shrink). */\n  contain: layout;\n}\n\n/* Opaque page surface — masks the fixed chrome layer in the content column. */\n.shell-app__content {\n  position: relative;\n  z-index: 1;\n  background-color: var(--color-background-primary);\n}\n\n.shell-app__tools {\n  grid-area: tools;\n  flex: 0 0 auto;\n  min-width: 0;\n  min-height: 0;\n  height: 100%;\n  display: flex;\n  position: relative;\n  z-index: 0;\n  overflow: hidden;\n}\n\n.shell-app__tools ::slotted(ds-panel-tools) {\n  display: block;\n  height: 100%;\n  min-height: 0;\n}\n\n:host(.shell-app--tools-fullscreen) .shell-app__panel,\n:host(.shell-app--tools-fullscreen) .shell-app__bar,\n:host(.shell-app--tools-fullscreen) .shell-app__content {\n  visibility: hidden;\n}\n",
+      "content": ":host {\n  display: block;\n  height: 100%;\n  min-height: 0;\n  box-sizing: border-box;\n  overflow: hidden;\n  overscroll-behavior: none;\n  --ds-shell-panel-tools-width: var(--dimension-panel-width-xs);\n}\n\n.shell-app {\n  display: flex;\n  flex-direction: column;\n  height: 100%;\n  min-height: 0;\n  box-sizing: border-box;\n  overflow: hidden;\n  overscroll-behavior: none;\n  font-family: var(--typography-font-family, system-ui);\n}\n\n:host {\n  --_shell-chrome-bg: var(--color-background-secondary);\n}\n\n.shell-app__row {\n  display: flex;\n  flex: 1 1 auto;\n  min-height: 0;\n  height: 100%;\n  position: relative;\n}\n\n/*\n * One chrome layer behind the shell row. Wash uses background-attachment: fixed\n * so the pattern is locked to the viewport — panel/tools collapse only changes the\n * transparent window, not the pattern phase. JS sets wash background-size from\n * readShellViewportDimensions(), not the shell element box.\n */\n.shell-app__chrome {\n  position: absolute;\n  inset: 0;\n  pointer-events: none;\n  z-index: 0;\n  background-color: var(--_shell-chrome-bg);\n}\n\n:host(.shell-app--gradient) .shell-app__chrome::before {\n  content: '';\n  position: absolute;\n  inset: 0;\n  pointer-events: none;\n  background-position: 0 0;\n  background-attachment: fixed;\n  z-index: 1;\n  opacity: var(--ds-shell-gradient-opacity, 1);\n  background-image: var(--ds-shell-gradient-image, none);\n  background-size: var(--ds-shell-gradient-size, auto);\n  background-repeat: no-repeat;\n}\n\n.shell-app__panel {\n  flex: 0 0 auto;\n  min-height: 0;\n  height: 100%;\n  position: relative;\n  /* Above main so resize handle line can paint over the workspace edge */\n  z-index: 2;\n}\n\n.shell-app__panel ::slotted(ds-panel-nav) {\n  display: block;\n  height: 100%;\n}\n\n.shell-app__main {\n  flex: 1 1 auto;\n  min-width: 0;\n  min-height: 0;\n  display: grid;\n  grid-template-columns: minmax(0, 1fr) auto;\n  grid-template-rows: auto minmax(0, 1fr);\n  grid-template-areas:\n    'bar tools'\n    'content tools';\n  position: relative;\n  z-index: 1;\n}\n\n.shell-app__mobile-section,\n.shell-app__mobile-navigation,\n.shell-app__mobile-bar {\n  display: none;\n}\n\n.shell-app__bar {\n  grid-area: bar;\n  flex: 0 0 auto;\n  min-width: 0;\n}\n\n.shell-app__bar ::slotted(ds-bar-nav) {\n  display: block;\n}\n\n.shell-app__content {\n  grid-area: content;\n  flex: 1 1 auto;\n  min-width: 0;\n  min-height: 0;\n  overflow: auto;\n  overscroll-behavior: none;\n  /* Limit reflow to the page column — not on __main (breaks tools flex shrink). */\n  contain: layout;\n}\n\n/* Opaque page surface — masks the fixed chrome layer in the content column. */\n.shell-app__content {\n  position: relative;\n  z-index: 1;\n  background-color: var(--color-background-primary);\n}\n\n.shell-app__tools {\n  grid-area: tools;\n  flex: 0 0 auto;\n  min-width: 0;\n  min-height: 0;\n  height: 100%;\n  display: flex;\n  position: relative;\n  z-index: 0;\n  overflow: hidden;\n}\n\n.shell-app__tools ::slotted(ds-panel-tools) {\n  display: block;\n  height: 100%;\n  min-height: 0;\n}\n\n.shell-app__tools ::slotted(ds-shell-tools) {\n  display: block;\n  height: 100%;\n  min-height: 0;\n}\n\n:host(.shell-app--tools-fullscreen) .shell-app__panel,\n:host(.shell-app--tools-fullscreen) .shell-app__bar,\n:host(.shell-app--tools-fullscreen) .shell-app__content {\n  visibility: hidden;\n}\n\n:host(.shell-app--mobile) {\n  --_shell-chrome-bg: var(--color-background-primary);\n}\n\n:host(.shell-app--mobile) .shell-app__chrome,\n:host(.shell-app--mobile) .shell-app__panel,\n:host(.shell-app--mobile) .shell-app__bar {\n  display: none;\n}\n\n:host(.shell-app--mobile) .shell-app__main {\n  width: 100%;\n  grid-template-columns: minmax(0, 1fr);\n  grid-template-rows: auto minmax(0, 1fr) auto;\n  grid-template-areas:\n    'mobile-section'\n    'stage'\n    'mobile-bar';\n  background: var(--color-background-primary);\n}\n\n:host(.shell-app--mobile) .shell-app__mobile-section {\n  grid-area: mobile-section;\n  display: block;\n  min-width: 0;\n  position: relative;\n  z-index: 1;\n}\n\n:host(.shell-app--mobile) .shell-app__content,\n:host(.shell-app--mobile) .shell-app__tools,\n:host(.shell-app--mobile) .shell-app__mobile-navigation {\n  grid-area: stage;\n  min-width: 0;\n  min-height: 0;\n  height: 100%;\n  position: relative;\n}\n\n:host(.shell-app--mobile) .shell-app__content {\n  z-index: 1;\n  overflow: auto;\n}\n\n:host(.shell-app--mobile) .shell-app__tools {\n  z-index: 2;\n  width: 100%;\n  overflow: hidden;\n  background: var(--color-background-primary);\n}\n\n:host(.shell-app--mobile) .shell-app__mobile-navigation {\n  display: block;\n  z-index: 3;\n  overflow: hidden;\n  background: var(--color-background-primary);\n}\n\n:host(.shell-app--mobile) .shell-app__mobile-bar {\n  grid-area: mobile-bar;\n  display: block;\n  min-width: 0;\n  position: relative;\n  z-index: 4;\n}\n\n:host(.shell-app--mobile) .shell-app__mobile-section[hidden],\n:host(.shell-app--mobile) .shell-app__tools[hidden],\n:host(.shell-app--mobile) .shell-app__mobile-navigation[hidden],\n:host(.shell-app--mobile) .shell-app__mobile-bar[hidden] {\n  display: none;\n}\n\n:host(.shell-app--mobile-tool-active) .shell-app__content,\n:host(.shell-app--mobile-navigation-open) .shell-app__content,\n:host(.shell-app--mobile-navigation-open) .shell-app__tools {\n  visibility: hidden;\n}\n",
       "type": "registry:ui"
     },
     {
       "path": "src/wc/components/ShellApp/ShellApp.tsx",
-      "content": "import { Component, Prop, Element, State, Watch, Listen, h, Host } from '@stencil/core';\nimport type { NavChromeStyle } from '../../shell/nav-chrome';\nimport {\n  isEditableShortcutTarget,\n  resolveShellShortcut,\n} from '../../shell/shell-shortcuts';\nimport type { PanelToolsToolId } from '../PanelTools/panel-tools-types';\nimport {\n  DEFAULT_SHELL_GRADIENT_PRESET,\n  normalizeShellGradientPreset,\n  type ShellGradientPreset,\n} from '../../shell/shell-gradient-presets';\nimport {\n  CHROME_TRANSITION_END,\n  CHROME_TRANSITION_START,\n  ChromeTransitionDepth,\n  createRafCoalescer,\n  readChromeTransitionSource,\n} from '../../shell/chrome-transition';\nimport {\n  isPanelNavCollapsed,\n  panelWidthPxFromTokens,\n  readPanelNavWidthTokens,\n  type PanelNavWidthTokens,\n} from '../../shell/shell-chrome-metrics';\nimport {\n  SHELL_GRADIENT_IMAGE_VAR,\n  SHELL_GRADIENT_OPACITY_VAR,\n  SHELL_GRADIENT_POSITION_BAR_VAR,\n  SHELL_GRADIENT_POSITION_PANEL_VAR,\n  SHELL_GRADIENT_SIZE_VAR,\n  buildShellRadialGradient,\n  readShellViewportDimensions,\n  shellGradientPositionBar,\n  shellGradientPositionPanel,\n  shellGradientPresetOpacity,\n  shellGradientSize,\n} from '../../shell/shell-gradient';\n\n@Component({\n  tag: 'ds-shell-app',\n  styleUrl: 'ShellApp.css',\n  scoped: true,\n})\nexport class ShellApp {\n  /** Chrome style propagated to slotted `ds-panel-nav` and `ds-bar-nav`. */\n  @Prop({ attribute: 'nav-style', reflect: true }) navStyle: NavChromeStyle = 'dashboard';\n\n  /**\n   * Shell chrome wash preset. `none` renders solid chrome; the remaining\n   * presets use token-based washes that adapt to the active color theme.\n   */\n  @Prop({ attribute: 'gradient-preset', reflect: true }) gradientPreset: ShellGradientPreset =\n    DEFAULT_SHELL_GRADIENT_PRESET;\n\n  /** When `true` (default), registers global shell keyboard shortcuts. `[` toggles panel nav; `]` closes tools; K, A, S, M, N, and / toggle tool drawers. Modifiers are ignored so browser chords like ⌘N stay native. */\n  @Prop({ attribute: 'shortcuts-enabled' }) shortcutsEnabled: boolean = true;\n\n  @Element() el!: HTMLElement;\n  @State() private toolsFullscreen = false;\n\n  private resizeObserver: ResizeObserver | null = null;\n  private readonly panelNavTransition = new ChromeTransitionDepth();\n  private readonly chromeSyncCoalescer = createRafCoalescer(() => this.syncChrome());\n  private panelWidthTokens: PanelNavWidthTokens = { expandedPx: 0, collapsedPx: 0 };\n  private cachedViewportWidth = 0;\n  private cachedViewportHeight = 0;\n  private onWindowResize = () => {\n    if (this.panelNavTransition.isActive) return;\n    this.scheduleChromeSync();\n  };\n  private onVisualViewportChange = () => {\n    if (this.panelNavTransition.isActive) return;\n    this.scheduleChromeSync();\n  };\n\n  componentDidLoad() {\n    this.syncSlottedNavStyle();\n    this.connectMetricsObserver();\n    this.connectViewportListeners();\n    this.el.addEventListener(CHROME_TRANSITION_START, this.onChromeTransitionStart);\n    this.el.addEventListener(CHROME_TRANSITION_END, this.onChromeTransitionEnd);\n    requestAnimationFrame(() => {\n      this.cachePanelWidthTokens();\n      this.scheduleChromeSync();\n    });\n    const tools = this.el.querySelector('ds-panel-tools');\n    this.toolsFullscreen = tools?.getAttribute('presentation') === 'fullscreen';\n  }\n\n  @Listen('dsPresentationChange')\n  handleToolsPresentation(event: CustomEvent<{ presentation?: string }>) {\n    this.toolsFullscreen = event.detail?.presentation === 'fullscreen';\n  }\n\n  disconnectedCallback() {\n    this.resizeObserver?.disconnect();\n    this.resizeObserver = null;\n    this.disconnectViewportListeners();\n    this.chromeSyncCoalescer.cancel();\n    this.el.removeEventListener(CHROME_TRANSITION_START, this.onChromeTransitionStart);\n    this.el.removeEventListener(CHROME_TRANSITION_END, this.onChromeTransitionEnd);\n  }\n\n  @Watch('navStyle')\n  @Watch('gradientPreset')\n  onShellPropsChange() {\n    this.syncSlottedNavStyle();\n    this.scheduleChromeSync();\n  }\n\n  private onChromeTransitionStart = (event: Event) => {\n    if (readChromeTransitionSource(event) !== 'panel-nav') return;\n\n    this.panelNavTransition.enter();\n    const viewport = readShellViewportDimensions();\n    this.cachedViewportWidth = viewport.width;\n    this.cachedViewportHeight = viewport.height;\n    this.syncChrome();\n  };\n\n  private onChromeTransitionEnd = (event: Event) => {\n    if (readChromeTransitionSource(event) !== 'panel-nav') return;\n\n    this.panelNavTransition.exit();\n    if (!this.panelNavTransition.isActive) {\n      this.scheduleChromeSync();\n    }\n  };\n\n  /** Coalesce ResizeObserver bursts to one layout read per frame. */\n  private scheduleChromeSync() {\n    this.chromeSyncCoalescer.schedule();\n  }\n\n  private syncSlottedNavStyle() {\n    const panel = this.el.querySelector('ds-panel-nav') as (HTMLElement & { navStyle: NavChromeStyle }) | null;\n    const bar = this.el.querySelector('ds-bar-nav') as (HTMLElement & { navStyle: NavChromeStyle }) | null;\n    if (panel) {\n      panel.setAttribute('nav-style', this.navStyle);\n      panel.navStyle = this.navStyle;\n    }\n    if (bar) {\n      bar.setAttribute('nav-style', this.navStyle);\n      bar.navStyle = this.navStyle;\n    }\n  }\n\n  private connectMetricsObserver() {\n    this.resizeObserver = new ResizeObserver(() => {\n      if (this.panelNavTransition.isActive) return;\n      this.scheduleChromeSync();\n    });\n    this.resizeObserver.observe(this.el);\n    const panelWrap = this.el.querySelector('.shell-app__panel');\n    if (panelWrap) this.resizeObserver.observe(panelWrap);\n  }\n\n  private connectViewportListeners() {\n    if (typeof window === 'undefined') return;\n\n    window.addEventListener('resize', this.onWindowResize, { passive: true });\n\n    const visual = window.visualViewport;\n    if (visual) {\n      visual.addEventListener('resize', this.onVisualViewportChange, { passive: true });\n      visual.addEventListener('scroll', this.onVisualViewportChange, { passive: true });\n    }\n  }\n\n  private disconnectViewportListeners() {\n    if (typeof window === 'undefined') return;\n\n    window.removeEventListener('resize', this.onWindowResize);\n\n    const visual = window.visualViewport;\n    if (visual) {\n      visual.removeEventListener('resize', this.onVisualViewportChange);\n      visual.removeEventListener('scroll', this.onVisualViewportChange);\n    }\n  }\n\n  private cachePanelWidthTokens() {\n    const navRoot = this.el.querySelector('ds-panel-nav .panel-nav') as HTMLElement | null;\n    if (!navRoot) return;\n    this.panelWidthTokens = readPanelNavWidthTokens(navRoot);\n  }\n\n  private applyGradientVars(target: HTMLElement, vars: Record<string, string | null>) {\n    const style = target.style;\n    for (const [name, value] of Object.entries(vars)) {\n      if (value === null) style.removeProperty(name);\n      else style.setProperty(name, value);\n    }\n  }\n\n  private clearGradientPaintVars(targets: HTMLElement[]) {\n    const keys = [\n      SHELL_GRADIENT_IMAGE_VAR,\n      SHELL_GRADIENT_SIZE_VAR,\n      SHELL_GRADIENT_OPACITY_VAR,\n    ];\n    for (const target of targets) {\n      for (const key of keys) target.style.removeProperty(key);\n    }\n  }\n\n  /** Panel/bar wash offsets for scroll fades and badge rings. */\n  private syncChromeLayoutVars(\n    panel: HTMLElement | null,\n    bar: HTMLElement | null,\n    panelPosition: string,\n    barPosition: string,\n  ) {\n    if (panel) {\n      panel.style.setProperty(SHELL_GRADIENT_POSITION_PANEL_VAR, panelPosition);\n    }\n    if (bar) {\n      bar.style.setProperty(SHELL_GRADIENT_POSITION_BAR_VAR, barPosition);\n    }\n  }\n\n  private resolvePanelWidthPx(panelNav: HTMLElement | null): number {\n    const navRoot = panelNav?.querySelector('.panel-nav') as HTMLElement | null;\n\n    if (this.panelNavTransition.isActive && this.panelWidthTokens.expandedPx > 0) {\n      const collapsed = isPanelNavCollapsed(panelNav, navRoot);\n      return panelWidthPxFromTokens(this.panelWidthTokens, collapsed);\n    }\n\n    const panelWrap = this.el.querySelector('.shell-app__panel') as HTMLElement | null;\n    const measured = panelWrap?.getBoundingClientRect().width ?? 0;\n    if (measured > 0) return measured;\n\n    if (this.panelWidthTokens.expandedPx > 0) {\n      const collapsed = isPanelNavCollapsed(panelNav, navRoot);\n      return panelWidthPxFromTokens(this.panelWidthTokens, collapsed);\n    }\n\n    return 0;\n  }\n\n  /** Fixed-attachment wash/grid size — always the viewport, never the shell element box. */\n  private resolveViewportDimensions(): { width: number; height: number } {\n    if (this.panelNavTransition.isActive && this.cachedViewportWidth > 0) {\n      return {\n        width: this.cachedViewportWidth,\n        height: this.cachedViewportHeight,\n      };\n    }\n\n    return readShellViewportDimensions();\n  }\n\n  private chromeLayerActive(): boolean {\n    return normalizeShellGradientPreset(this.gradientPreset) !== 'none';\n  }\n\n  @Listen('keydown', { target: 'window', capture: true })\n  handleWindowKeyDown(e: KeyboardEvent) {\n    if (!this.shortcutsEnabled) return;\n    if (isEditableShortcutTarget(e.target)) return;\n\n    const action = resolveShellShortcut(e);\n    if (!action) return;\n\n    e.preventDefault();\n\n    const panel = this.el.querySelector('ds-panel-nav') as HTMLDsPanelNavElement | null;\n    const tools = this.el.querySelector('ds-panel-tools') as HTMLDsPanelToolsElement | null;\n\n    if (action === 'toggle-panel-nav') {\n      void panel?.toggleCollapsed();\n      return;\n    }\n\n    if (action === 'close-panel-tools') {\n      void tools?.closeDrawer();\n      return;\n    }\n\n    if (action.startsWith('open-tool:') && tools) {\n      const toolId = action.slice('open-tool:'.length) as PanelToolsToolId;\n      void tools.activateTool(toolId);\n    }\n  }\n\n  private syncChrome() {\n    const panelNav = this.el.querySelector('ds-panel-nav') as HTMLElement | null;\n    const bar = this.el.querySelector('ds-bar-nav') as HTMLElement | null;\n    const targets = [this.el, panelNav, bar].filter((el): el is HTMLElement => el !== null);\n\n    const clearLayoutVars = () => {\n      if (panelNav) panelNav.style.removeProperty(SHELL_GRADIENT_POSITION_PANEL_VAR);\n      if (bar) bar.style.removeProperty(SHELL_GRADIENT_POSITION_BAR_VAR);\n    };\n\n    const preset = normalizeShellGradientPreset(this.gradientPreset);\n    if (preset === 'none') {\n      this.clearGradientPaintVars(targets);\n      clearLayoutVars();\n      return;\n    }\n\n    const viewport = this.resolveViewportDimensions();\n    const panelWidth = this.resolvePanelWidthPx(panelNav);\n\n    const panelPosition = shellGradientPositionPanel();\n    const barPosition = shellGradientPositionBar(panelWidth);\n\n    this.syncChromeLayoutVars(panelNav, bar, panelPosition, barPosition);\n\n    const image = buildShellRadialGradient(preset);\n\n    const size = shellGradientSize({\n      width: viewport.width,\n      height: viewport.height,\n    });\n    const opacity = shellGradientPresetOpacity(preset);\n\n    for (const target of targets) {\n      if (target === this.el) {\n        this.applyGradientVars(target, {\n          [SHELL_GRADIENT_IMAGE_VAR]: image,\n          [SHELL_GRADIENT_SIZE_VAR]: size,\n          [SHELL_GRADIENT_POSITION_PANEL_VAR]: panelPosition,\n          [SHELL_GRADIENT_POSITION_BAR_VAR]: barPosition,\n          [SHELL_GRADIENT_OPACITY_VAR]: opacity,\n        });\n        continue;\n      }\n\n      const isBar = target.tagName.toLowerCase() === 'ds-bar-nav';\n      this.applyGradientVars(target, {\n        [SHELL_GRADIENT_IMAGE_VAR]: image,\n        [SHELL_GRADIENT_SIZE_VAR]: size,\n        [SHELL_GRADIENT_OPACITY_VAR]: opacity,\n        [SHELL_GRADIENT_POSITION_PANEL_VAR]: isBar ? null : panelPosition,\n        [SHELL_GRADIENT_POSITION_BAR_VAR]: isBar ? barPosition : null,\n      });\n    }\n  }\n\n  render() {\n    const chromeActive = this.chromeLayerActive();\n    const shellCls: Record<string, boolean> = {\n      'shell-app': true,\n      'shell-app--gradient': chromeActive,\n      [`shell-app--${this.navStyle}`]: true,\n      'shell-app--tools-fullscreen': this.toolsFullscreen,\n    };\n\n    return (\n      <Host class={shellCls}>\n        <div class=\"shell-app__row\">\n          <div class=\"shell-app__chrome\" aria-hidden=\"true\" />\n          <div class=\"shell-app__panel\" aria-hidden={this.toolsFullscreen ? 'true' : undefined} inert={this.toolsFullscreen ? true : undefined}>\n            <slot name=\"panel\" />\n          </div>\n          <div class=\"shell-app__main\">\n            <div class=\"shell-app__bar\" aria-hidden={this.toolsFullscreen ? 'true' : undefined} inert={this.toolsFullscreen ? true : undefined}>\n              <slot name=\"bar\" />\n            </div>\n            <div class=\"shell-app__tools\">\n              <slot name=\"tools\" />\n            </div>\n            <div class=\"shell-app__content\" aria-hidden={this.toolsFullscreen ? 'true' : undefined} inert={this.toolsFullscreen ? true : undefined}>\n              <slot />\n            </div>\n          </div>\n        </div>\n      </Host>\n    );\n  }\n}\n",
+      "content": "import {\n  Component,\n  Prop,\n  Element,\n  Event,\n  EventEmitter,\n  State,\n  Watch,\n  Listen,\n  h,\n  Host,\n} from '@stencil/core';\nimport type { NavChromeStyle } from '../../shell/nav-chrome';\nimport {\n  isEditableShortcutTarget,\n  resolveShellShortcut,\n} from '../../shell/shell-shortcuts';\nimport type { PanelToolsToolId } from '../PanelTools/panel-tools-types';\nimport {\n  DEFAULT_SHELL_GRADIENT_PRESET,\n  normalizeShellGradientPreset,\n  type ShellGradientPreset,\n} from '../../shell/shell-gradient-presets';\nimport {\n  CHROME_TRANSITION_END,\n  CHROME_TRANSITION_START,\n  ChromeTransitionDepth,\n  createRafCoalescer,\n  readChromeTransitionSource,\n} from '../../shell/chrome-transition';\nimport {\n  isPanelNavCollapsed,\n  panelWidthPxFromTokens,\n  readPanelNavWidthTokens,\n  type PanelNavWidthTokens,\n} from '../../shell/shell-chrome-metrics';\nimport {\n  SHELL_GRADIENT_IMAGE_VAR,\n  SHELL_GRADIENT_OPACITY_VAR,\n  SHELL_GRADIENT_POSITION_BAR_VAR,\n  SHELL_GRADIENT_POSITION_PANEL_VAR,\n  SHELL_GRADIENT_SIZE_VAR,\n  buildShellRadialGradient,\n  readShellViewportDimensions,\n  shellGradientPositionBar,\n  shellGradientPositionPanel,\n  shellGradientPresetOpacity,\n  shellGradientSize,\n} from '../../shell/shell-gradient';\nimport {\n  resolveShellResponsiveMode,\n  type ShellMobileDestination,\n  type ShellResponsiveMode,\n} from '../../shell/shell-responsive';\n\n@Component({\n  tag: 'ds-shell-app',\n  styleUrl: 'ShellApp.css',\n  scoped: true,\n})\nexport class ShellApp {\n  /** Chrome style propagated to slotted `ds-panel-nav` and `ds-bar-nav`. */\n  @Prop({ attribute: 'nav-style', reflect: true }) navStyle: NavChromeStyle = 'dashboard';\n\n  /**\n   * Shell chrome wash preset. `none` renders solid chrome; the remaining\n   * presets use token-based washes that adapt to the active color theme.\n   */\n  @Prop({ attribute: 'gradient-preset', reflect: true }) gradientPreset: ShellGradientPreset =\n    DEFAULT_SHELL_GRADIENT_PRESET;\n\n  /** When `true` (default), registers global shell keyboard shortcuts. `[` toggles panel nav; `]` closes tools; K, A, S, M, N, and / toggle tool drawers. Modifiers are ignored so browser chords like ⌘N stay native. */\n  @Prop({ attribute: 'shortcuts-enabled' }) shortcutsEnabled: boolean = true;\n\n  /** Controlled mobile surface shown above the persistent bottom bar. */\n  @Prop({ attribute: 'mobile-destination' })\n  mobileDestination: ShellMobileDestination = 'area';\n\n  /** Controlled full-stage mobile navigation-pane state. */\n  @Prop({ attribute: 'mobile-navigation-open' })\n  mobileNavigationOpen: boolean = false;\n\n  /** Emitted after crossing the fixed 768px or 1200px shell boundaries. */\n  @Event() dsResponsiveModeChange!: EventEmitter<{ mode: ShellResponsiveMode }>;\n\n  @Element() el!: HTMLElement;\n  @State() private toolsFullscreen = false;\n  @State() private resolvedMode: ShellResponsiveMode = 'desktop';\n\n  private resizeObserver: ResizeObserver | null = null;\n  private hasLoaded = false;\n  private readonly panelNavTransition = new ChromeTransitionDepth();\n  private readonly chromeSyncCoalescer = createRafCoalescer(() => this.syncChrome());\n  private panelWidthTokens: PanelNavWidthTokens = { expandedPx: 0, collapsedPx: 0 };\n  private cachedViewportWidth = 0;\n  private cachedViewportHeight = 0;\n  private onWindowResize = () => {\n    this.updateResponsiveMode();\n    if (this.panelNavTransition.isActive) return;\n    this.scheduleChromeSync();\n  };\n  private onVisualViewportChange = () => {\n    if (this.panelNavTransition.isActive) return;\n    this.scheduleChromeSync();\n  };\n\n  componentWillLoad() {\n    if (typeof window !== 'undefined') {\n      this.resolvedMode = resolveShellResponsiveMode(window.innerWidth);\n    }\n  }\n\n  componentDidLoad() {\n    this.hasLoaded = true;\n    this.syncSlottedNavStyle();\n    this.syncSlottedMobileState();\n    this.connectMetricsObserver();\n    this.connectViewportListeners();\n    this.el.addEventListener(CHROME_TRANSITION_START, this.onChromeTransitionStart);\n    this.el.addEventListener(CHROME_TRANSITION_END, this.onChromeTransitionEnd);\n    requestAnimationFrame(() => {\n      this.cachePanelWidthTokens();\n      this.scheduleChromeSync();\n    });\n    const tools = this.el.querySelector('ds-shell-tools, ds-panel-tools');\n    this.toolsFullscreen = tools?.getAttribute('presentation') === 'fullscreen';\n  }\n\n  @Listen('dsPresentationChange')\n  handleToolsPresentation(event: CustomEvent<{ presentation?: string }>) {\n    this.toolsFullscreen = event.detail?.presentation === 'fullscreen';\n  }\n\n  disconnectedCallback() {\n    this.resizeObserver?.disconnect();\n    this.resizeObserver = null;\n    this.disconnectViewportListeners();\n    this.chromeSyncCoalescer.cancel();\n    this.el.removeEventListener(CHROME_TRANSITION_START, this.onChromeTransitionStart);\n    this.el.removeEventListener(CHROME_TRANSITION_END, this.onChromeTransitionEnd);\n  }\n\n  @Watch('navStyle')\n  @Watch('gradientPreset')\n  onShellPropsChange() {\n    this.syncSlottedNavStyle();\n    this.scheduleChromeSync();\n  }\n\n  @Watch('mobileDestination')\n  @Watch('mobileNavigationOpen')\n  onMobileStateChange(_next: unknown, previous: unknown) {\n    this.syncSlottedMobileState();\n    if (\n      previous === true &&\n      !this.mobileNavigationOpen &&\n      this.resolvedMode === 'mobile'\n    ) {\n      requestAnimationFrame(() => {\n        const bar = this.el.querySelector('ds-shell-mobile-bar') as\n          | (HTMLElement & {\n              focusDestination?: (\n                destination: ShellMobileDestination | 'navigation'\n              ) => Promise<void>;\n            })\n          | null;\n        const activeElement = document.activeElement;\n        if (activeElement instanceof HTMLElement && bar?.contains(activeElement)) return;\n        void bar?.focusDestination?.('navigation');\n      });\n    }\n  }\n\n  private updateResponsiveMode() {\n    if (typeof window === 'undefined') return;\n    const next = resolveShellResponsiveMode(window.innerWidth);\n    if (next === this.resolvedMode) return;\n    this.resolvedMode = next;\n    this.syncSlottedMobileState();\n    this.scheduleChromeSync();\n    if (this.hasLoaded) this.dsResponsiveModeChange.emit({ mode: next });\n  }\n\n  private onChromeTransitionStart = (event: Event) => {\n    if (readChromeTransitionSource(event) !== 'panel-nav') return;\n\n    this.panelNavTransition.enter();\n    const viewport = readShellViewportDimensions();\n    this.cachedViewportWidth = viewport.width;\n    this.cachedViewportHeight = viewport.height;\n    this.syncChrome();\n  };\n\n  private onChromeTransitionEnd = (event: Event) => {\n    if (readChromeTransitionSource(event) !== 'panel-nav') return;\n\n    this.panelNavTransition.exit();\n    if (!this.panelNavTransition.isActive) {\n      this.scheduleChromeSync();\n    }\n  };\n\n  /** Coalesce ResizeObserver bursts to one layout read per frame. */\n  private scheduleChromeSync() {\n    this.chromeSyncCoalescer.schedule();\n  }\n\n  private syncSlottedNavStyle() {\n    const panel = this.el.querySelector('ds-panel-nav') as (HTMLElement & { navStyle: NavChromeStyle }) | null;\n    const bar = this.el.querySelector('ds-bar-nav') as (HTMLElement & { navStyle: NavChromeStyle }) | null;\n    if (panel) {\n      panel.setAttribute('nav-style', this.navStyle);\n      panel.navStyle = this.navStyle;\n    }\n    if (bar) {\n      bar.setAttribute('nav-style', this.navStyle);\n      bar.navStyle = this.navStyle;\n    }\n  }\n\n  private syncSlottedMobileState() {\n    const tools = this.el.querySelector('ds-shell-tools') as\n      | (HTMLElement & { responsiveMode: ShellResponsiveMode })\n      | null;\n    const bar = this.el.querySelector('ds-shell-mobile-bar') as\n      | (HTMLElement & {\n          activeDestination: ShellMobileDestination;\n          navigationExpanded: boolean;\n        })\n      | null;\n    const navigation = this.el.querySelector('ds-shell-mobile-nav') as\n      | (HTMLElement & { open: boolean })\n      | null;\n\n    if (tools) {\n      tools.setAttribute('responsive-mode', this.resolvedMode);\n      tools.responsiveMode = this.resolvedMode;\n    }\n    if (bar) {\n      bar.activeDestination = this.mobileDestination;\n      bar.navigationExpanded = this.mobileNavigationOpen;\n    }\n    if (navigation) {\n      navigation.open = this.mobileNavigationOpen;\n    }\n  }\n\n  private connectMetricsObserver() {\n    this.resizeObserver = new ResizeObserver(() => {\n      if (this.panelNavTransition.isActive) return;\n      this.scheduleChromeSync();\n    });\n    this.resizeObserver.observe(this.el);\n    const panelWrap = this.el.querySelector('.shell-app__panel');\n    if (panelWrap) this.resizeObserver.observe(panelWrap);\n  }\n\n  private connectViewportListeners() {\n    if (typeof window === 'undefined') return;\n\n    window.addEventListener('resize', this.onWindowResize, { passive: true });\n\n    const visual = window.visualViewport;\n    if (visual) {\n      visual.addEventListener('resize', this.onVisualViewportChange, { passive: true });\n      visual.addEventListener('scroll', this.onVisualViewportChange, { passive: true });\n    }\n  }\n\n  private disconnectViewportListeners() {\n    if (typeof window === 'undefined') return;\n\n    window.removeEventListener('resize', this.onWindowResize);\n\n    const visual = window.visualViewport;\n    if (visual) {\n      visual.removeEventListener('resize', this.onVisualViewportChange);\n      visual.removeEventListener('scroll', this.onVisualViewportChange);\n    }\n  }\n\n  private cachePanelWidthTokens() {\n    const navRoot = this.el.querySelector('ds-panel-nav .panel-nav') as HTMLElement | null;\n    if (!navRoot) return;\n    this.panelWidthTokens = readPanelNavWidthTokens(navRoot);\n  }\n\n  private applyGradientVars(target: HTMLElement, vars: Record<string, string | null>) {\n    const style = target.style;\n    for (const [name, value] of Object.entries(vars)) {\n      if (value === null) style.removeProperty(name);\n      else style.setProperty(name, value);\n    }\n  }\n\n  private clearGradientPaintVars(targets: HTMLElement[]) {\n    const keys = [\n      SHELL_GRADIENT_IMAGE_VAR,\n      SHELL_GRADIENT_SIZE_VAR,\n      SHELL_GRADIENT_OPACITY_VAR,\n    ];\n    for (const target of targets) {\n      for (const key of keys) target.style.removeProperty(key);\n    }\n  }\n\n  /** Panel/bar wash offsets for scroll fades and badge rings. */\n  private syncChromeLayoutVars(\n    panel: HTMLElement | null,\n    bar: HTMLElement | null,\n    panelPosition: string,\n    barPosition: string,\n  ) {\n    if (panel) {\n      panel.style.setProperty(SHELL_GRADIENT_POSITION_PANEL_VAR, panelPosition);\n    }\n    if (bar) {\n      bar.style.setProperty(SHELL_GRADIENT_POSITION_BAR_VAR, barPosition);\n    }\n  }\n\n  private resolvePanelWidthPx(panelNav: HTMLElement | null): number {\n    const navRoot = panelNav?.querySelector('.panel-nav') as HTMLElement | null;\n\n    if (this.panelNavTransition.isActive && this.panelWidthTokens.expandedPx > 0) {\n      const collapsed = isPanelNavCollapsed(panelNav, navRoot);\n      return panelWidthPxFromTokens(this.panelWidthTokens, collapsed);\n    }\n\n    const panelWrap = this.el.querySelector('.shell-app__panel') as HTMLElement | null;\n    const measured = panelWrap?.getBoundingClientRect().width ?? 0;\n    if (measured > 0) return measured;\n\n    if (this.panelWidthTokens.expandedPx > 0) {\n      const collapsed = isPanelNavCollapsed(panelNav, navRoot);\n      return panelWidthPxFromTokens(this.panelWidthTokens, collapsed);\n    }\n\n    return 0;\n  }\n\n  /** Fixed-attachment wash/grid size — always the viewport, never the shell element box. */\n  private resolveViewportDimensions(): { width: number; height: number } {\n    if (this.panelNavTransition.isActive && this.cachedViewportWidth > 0) {\n      return {\n        width: this.cachedViewportWidth,\n        height: this.cachedViewportHeight,\n      };\n    }\n\n    return readShellViewportDimensions();\n  }\n\n  private chromeLayerActive(): boolean {\n    return (\n      this.resolvedMode !== 'mobile' &&\n      normalizeShellGradientPreset(this.gradientPreset) !== 'none'\n    );\n  }\n\n  @Listen('keydown', { target: 'window', capture: true })\n  handleWindowKeyDown(e: KeyboardEvent) {\n    if (!this.shortcutsEnabled) return;\n    if (isEditableShortcutTarget(e.target)) return;\n\n    const action = resolveShellShortcut(e);\n    if (!action) return;\n\n    e.preventDefault();\n\n    const panel = this.el.querySelector('ds-panel-nav') as HTMLDsPanelNavElement | null;\n    const tools = this.el.querySelector('ds-shell-tools, ds-panel-tools') as\n      | (HTMLElement & {\n          closeDrawer?: () => Promise<void>;\n          activateTool?: (id: PanelToolsToolId) => Promise<void>;\n        })\n      | null;\n\n    if (action === 'toggle-panel-nav') {\n      void panel?.toggleCollapsed();\n      return;\n    }\n\n    if (action === 'close-panel-tools') {\n      void tools?.closeDrawer?.();\n      return;\n    }\n\n    if (action.startsWith('open-tool:') && tools) {\n      const toolId = action.slice('open-tool:'.length) as PanelToolsToolId;\n      void tools.activateTool?.(toolId);\n    }\n  }\n\n  private syncChrome() {\n    const panelNav = this.el.querySelector('ds-panel-nav') as HTMLElement | null;\n    const bar = this.el.querySelector('ds-bar-nav') as HTMLElement | null;\n    const targets = [this.el, panelNav, bar].filter((el): el is HTMLElement => el !== null);\n\n    const clearLayoutVars = () => {\n      if (panelNav) panelNav.style.removeProperty(SHELL_GRADIENT_POSITION_PANEL_VAR);\n      if (bar) bar.style.removeProperty(SHELL_GRADIENT_POSITION_BAR_VAR);\n    };\n\n    const preset = normalizeShellGradientPreset(this.gradientPreset);\n    if (preset === 'none' || this.resolvedMode === 'mobile') {\n      this.clearGradientPaintVars(targets);\n      clearLayoutVars();\n      return;\n    }\n\n    const viewport = this.resolveViewportDimensions();\n    const panelWidth = this.resolvePanelWidthPx(panelNav);\n\n    const panelPosition = shellGradientPositionPanel();\n    const barPosition = shellGradientPositionBar(panelWidth);\n\n    this.syncChromeLayoutVars(panelNav, bar, panelPosition, barPosition);\n\n    const image = buildShellRadialGradient(preset);\n\n    const size = shellGradientSize({\n      width: viewport.width,\n      height: viewport.height,\n    });\n    const opacity = shellGradientPresetOpacity(preset);\n\n    for (const target of targets) {\n      if (target === this.el) {\n        this.applyGradientVars(target, {\n          [SHELL_GRADIENT_IMAGE_VAR]: image,\n          [SHELL_GRADIENT_SIZE_VAR]: size,\n          [SHELL_GRADIENT_POSITION_PANEL_VAR]: panelPosition,\n          [SHELL_GRADIENT_POSITION_BAR_VAR]: barPosition,\n          [SHELL_GRADIENT_OPACITY_VAR]: opacity,\n        });\n        continue;\n      }\n\n      const isBar = target.tagName.toLowerCase() === 'ds-bar-nav';\n      this.applyGradientVars(target, {\n        [SHELL_GRADIENT_IMAGE_VAR]: image,\n        [SHELL_GRADIENT_SIZE_VAR]: size,\n        [SHELL_GRADIENT_OPACITY_VAR]: opacity,\n        [SHELL_GRADIENT_POSITION_PANEL_VAR]: isBar ? null : panelPosition,\n        [SHELL_GRADIENT_POSITION_BAR_VAR]: isBar ? barPosition : null,\n      });\n    }\n  }\n\n  render() {\n    const chromeActive = this.chromeLayerActive();\n    const mobile = this.resolvedMode === 'mobile';\n    const mobileToolActive = mobile && this.mobileDestination !== 'area';\n    const mobileStageBlocked = mobile && (mobileToolActive || this.mobileNavigationOpen);\n    const fullscreen = !mobile && this.toolsFullscreen;\n    const shellCls: Record<string, boolean> = {\n      'shell-app': true,\n      'shell-app--gradient': chromeActive,\n      [`shell-app--${this.navStyle}`]: true,\n      [`shell-app--${this.resolvedMode}`]: true,\n      'shell-app--tools-fullscreen': fullscreen,\n      'shell-app--mobile-tool-active': mobileToolActive,\n      'shell-app--mobile-navigation-open': mobile && this.mobileNavigationOpen,\n    };\n\n    return (\n      <Host class={shellCls} responsive-mode={this.resolvedMode}>\n        <div class=\"shell-app__row\">\n          <div class=\"shell-app__chrome\" aria-hidden=\"true\" />\n          <div class=\"shell-app__panel\" aria-hidden={fullscreen ? 'true' : undefined} inert={fullscreen ? true : undefined}>\n            <slot name=\"panel\" />\n          </div>\n          <div class=\"shell-app__main\">\n            <div class=\"shell-app__bar\" aria-hidden={fullscreen ? 'true' : undefined} inert={fullscreen ? true : undefined}>\n              <slot name=\"bar\" />\n            </div>\n            <div\n              class=\"shell-app__mobile-section\"\n              hidden={!mobile || this.mobileDestination !== 'area' || this.mobileNavigationOpen}\n            >\n              <slot name=\"mobile-section-nav\" />\n            </div>\n            <div\n              class=\"shell-app__tools\"\n              aria-hidden={mobile && (!mobileToolActive || this.mobileNavigationOpen) ? 'true' : undefined}\n              inert={mobile && (!mobileToolActive || this.mobileNavigationOpen) ? true : undefined}\n              hidden={mobile && !mobileToolActive}\n            >\n              <slot name=\"tools\" />\n            </div>\n            <div\n              class=\"shell-app__content\"\n              aria-hidden={fullscreen || mobileStageBlocked ? 'true' : undefined}\n              inert={fullscreen || mobileStageBlocked ? true : undefined}\n            >\n              <slot />\n            </div>\n            <div\n              class=\"shell-app__mobile-navigation\"\n              hidden={!mobile || !this.mobileNavigationOpen}\n              aria-hidden={mobile && this.mobileNavigationOpen ? undefined : 'true'}\n              inert={mobile && this.mobileNavigationOpen ? undefined : true}\n            >\n              <slot name=\"mobile-navigation\" />\n            </div>\n            <div class=\"shell-app__mobile-bar\" hidden={!mobile}>\n              <slot name=\"mobile-bar\" />\n            </div>\n          </div>\n        </div>\n      </Host>\n    );\n  }\n}\n",
       "type": "registry:ui"
     }
   ]

package/dist/mcp-data/registry/shell-mobile-bar.json

@@ -0,0 +1,314 @@
+{
+  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+  "name": "shell-mobile-bar",
+  "title": "ShellMobileBar",
+  "description": "Persistent mobile shell navigation for Menu, the router-derived current area, Search, Agents, and Inbox.",
+  "type": "registry:ui",
+  "meta": {
+    "library": "@ds-mo/ui",
+    "distribution": "npm",
+    "storybook": "https://zainadeel.github.io/compomo/?path=/story/shell-mobile-bar",
+    "source": "src/wc/components/ShellMobileBar/ShellMobileBar.tsx",
+    "intentStatus": "complete",
+    "intent": {
+      "audience": "specialized",
+      "status": "experimental",
+      "summary": "Persistent mobile shell navigation for Menu, the router-derived current area, Search, Agents, and Inbox.",
+      "useWhen": [
+        "ShellApp is rendering its dedicated below-768px application composition."
+      ],
+      "avoidWhen": [
+        "Rendering desktop or tablet shell chrome.",
+        "An arbitrary set of product tabs is required."
+      ],
+      "commonlyComposedWith": [
+        "component:ds-shell-app"
+      ],
+      "patterns": [
+        "pattern:application-shell"
+      ],
+      "accessibility": [
+        "Every item keeps a visible label and accessible name.",
+        "Only the active destination exposes aria-current; Menu exposes its controlled pane through aria-expanded."
+      ],
+      "states": [
+        "The item order is fixed: Menu, current area, Search, Agents, Inbox.",
+        "Reselecting an active destination does not reset its nested state."
+      ],
+      "responsiveBehavior": [
+        "Render only below the mobile breakpoint and preserve safe-area clearance."
+      ],
+      "references": [
+        {
+          "label": "Storybook",
+          "path": "src/wc/components/ShellMobileBar/ShellMobileBar.stories.ts"
+        }
+      ]
+    },
+    "api": {
+      "props": {
+        "activeDestination": {
+          "type": "ShellMobileDestination",
+          "resolvedType": "\"agents\" | \"area\" | \"inbox\" | \"search\"",
+          "attribute": "active-destination",
+          "default": "'area'",
+          "required": false,
+          "mutable": false
+        },
+        "agentsDot": {
+          "type": "boolean",
+          "resolvedType": "boolean",
+          "attribute": "agents-dot",
+          "default": "false",
+          "required": false,
+          "mutable": false
+        },
+        "agentsLabel": {
+          "type": "string",
+          "resolvedType": "string",
+          "attribute": "agents-label",
+          "default": "'Agents'",
+          "required": false,
+          "mutable": false
+        },
+        "currentArea": {
+          "type": "PanelNavItem",
+          "resolvedType": "PanelNavItem",
+          "default": "{\n    id: 'tracking',\n    icon: 'MapPage',\n    label: 'Tracking',\n  }",
+          "required": false,
+          "mutable": false
+        },
+        "inboxDot": {
+          "type": "boolean",
+          "resolvedType": "boolean",
+          "attribute": "inbox-dot",
+          "default": "false",
+          "required": false,
+          "mutable": false
+        },
+        "inboxLabel": {
+          "type": "string",
+          "resolvedType": "string",
+          "attribute": "inbox-label",
+          "default": "'Inbox'",
+          "required": false,
+          "mutable": false
+        },
+        "menuLabel": {
+          "type": "string",
+          "resolvedType": "string",
+          "attribute": "menu-label",
+          "default": "'Menu'",
+          "required": false,
+          "mutable": false
+        },
+        "navigationExpanded": {
+          "type": "boolean",
+          "resolvedType": "boolean",
+          "attribute": "navigation-expanded",
+          "default": "false",
+          "required": false,
+          "mutable": false
+        },
+        "searchDot": {
+          "type": "boolean",
+          "resolvedType": "boolean",
+          "attribute": "search-dot",
+          "default": "false",
+          "required": false,
+          "mutable": false
+        },
+        "searchLabel": {
+          "type": "string",
+          "resolvedType": "string",
+          "attribute": "search-label",
+          "default": "'Search'",
+          "required": false,
+          "mutable": false
+        }
+      },
+      "events": [
+        {
+          "name": "dsDestinationChange",
+          "detail": "ShellMobileBarDestinationDetail",
+          "bubbles": true,
+          "cancelable": true,
+          "composed": true
+        },
+        {
+          "name": "dsNavigationToggle",
+          "detail": "boolean",
+          "bubbles": true,
+          "cancelable": true,
+          "composed": true
+        }
+      ],
+      "methods": [
+        {
+          "name": "focusDestination",
+          "signature": "focusDestination(destination: ShellMobileDestination | \"navigation\") => Promise<void>"
+        }
+      ],
+      "slots": []
+    },
+    "props": {
+      "activeDestination": {
+        "type": "ShellMobileDestination",
+        "resolvedType": "\"agents\" | \"area\" | \"inbox\" | \"search\"",
+        "attribute": "active-destination",
+        "default": "'area'",
+        "required": false,
+        "mutable": false
+      },
+      "agentsDot": {
+        "type": "boolean",
+        "resolvedType": "boolean",
+        "attribute": "agents-dot",
+        "default": "false",
+        "required": false,
+        "mutable": false
+      },
+      "agentsLabel": {
+        "type": "string",
+        "resolvedType": "string",
+        "attribute": "agents-label",
+        "default": "'Agents'",
+        "required": false,
+        "mutable": false
+      },
+      "currentArea": {
+        "type": "PanelNavItem",
+        "resolvedType": "PanelNavItem",
+        "default": "{\n    id: 'tracking',\n    icon: 'MapPage',\n    label: 'Tracking',\n  }",
+        "required": false,
+        "mutable": false
+      },
+      "inboxDot": {
+        "type": "boolean",
+        "resolvedType": "boolean",
+        "attribute": "inbox-dot",
+        "default": "false",
+        "required": false,
+        "mutable": false
+      },
+      "inboxLabel": {
+        "type": "string",
+        "resolvedType": "string",
+        "attribute": "inbox-label",
+        "default": "'Inbox'",
+        "required": false,
+        "mutable": false
+      },
+      "menuLabel": {
+        "type": "string",
+        "resolvedType": "string",
+        "attribute": "menu-label",
+        "default": "'Menu'",
+        "required": false,
+        "mutable": false
+      },
+      "navigationExpanded": {
+        "type": "boolean",
+        "resolvedType": "boolean",
+        "attribute": "navigation-expanded",
+        "default": "false",
+        "required": false,
+        "mutable": false
+      },
+      "searchDot": {
+        "type": "boolean",
+        "resolvedType": "boolean",
+        "attribute": "search-dot",
+        "default": "false",
+        "required": false,
+        "mutable": false
+      },
+      "searchLabel": {
+        "type": "string",
+        "resolvedType": "string",
+        "attribute": "search-label",
+        "default": "'Search'",
+        "required": false,
+        "mutable": false
+      }
+    },
+    "events": [
+      {
+        "name": "dsDestinationChange",
+        "detail": "ShellMobileBarDestinationDetail",
+        "bubbles": true,
+        "cancelable": true,
+        "composed": true
+      },
+      {
+        "name": "dsNavigationToggle",
+        "detail": "boolean",
+        "bubbles": true,
+        "cancelable": true,
+        "composed": true
+      }
+    ],
+    "methods": [
+      {
+        "name": "focusDestination",
+        "signature": "focusDestination(destination: ShellMobileDestination | \"navigation\") => Promise<void>"
+      }
+    ],
+    "slots": [],
+    "exports": {
+      "customElement": "ds-shell-mobile-bar",
+      "react": "DsShellMobileBar",
+      "angular": "DsShellMobileBar"
+    },
+    "consumption": {
+      "install": "npm install @ds-mo/ui @ds-mo/tokens @ds-mo/icons",
+      "cssSetup": "import '@ds-mo/tokens';\nimport '@ds-mo/tokens/reset';\nimport '@ds-mo/tokens/globals';",
+      "customElements": {
+        "import": "import '@ds-mo/ui/dist/components/ds-shell-mobile-bar.js';",
+        "example": "<ds-shell-mobile-bar></ds-shell-mobile-bar>"
+      },
+      "react": {
+        "import": "import { DsShellMobileBar } from '@ds-mo/ui/react';",
+        "example": "<DsShellMobileBar />"
+      },
+      "angular": {
+        "import": "import { DsShellMobileBar } from '@ds-mo/ui/angular/ds-shell-mobile-bar';",
+        "example": "<ds-shell-mobile-bar></ds-shell-mobile-bar>"
+      },
+      "complexPropertyNote": "Assign these non-primitive values as JavaScript properties: currentArea.",
+      "peerDependencies": {
+        "required": [
+          "@ds-mo/tokens ^3.1.1",
+          "@ds-mo/icons ^6.4.0"
+        ],
+        "frameworks": "Custom Elements; React 18/19 wrappers; Angular 19-22 standalone adapters."
+      }
+    }
+  },
+  "dependencies": [
+    "@ds-mo/ui",
+    "@ds-mo/tokens",
+    "@ds-mo/icons"
+  ],
+  "registryDependencies": [
+    "icon",
+    "text"
+  ],
+  "files": [
+    {
+      "path": "src/wc/components/ShellMobileBar/ShellMobileBar.css",
+      "content": "@import '../../utils/focus-ring.css';\n@import '../../utils/interaction-fill.css';\n\n:host {\n  display: block;\n  min-width: 0;\n  background: var(--color-background-primary);\n  color: var(--color-foreground-secondary);\n}\n\n.shell-mobile-bar {\n  display: grid;\n  grid-template-columns: repeat(5, minmax(0, 1fr));\n  align-items: stretch;\n  min-width: 0;\n  padding: var(--dimension-space-050) var(--dimension-space-050)\n    max(var(--dimension-space-050), env(safe-area-inset-bottom));\n  border-top: var(--dimension-stroke-width-012) solid var(--color-border-tertiary);\n  background: var(--color-background-primary);\n  box-sizing: border-box;\n}\n\n.shell-mobile-bar__item {\n  appearance: none;\n  min-width: 0;\n  min-height: var(--dimension-size-600);\n  padding: var(--dimension-space-050) var(--dimension-space-025);\n  border: 0;\n  border-radius: var(--dimension-radius-100);\n  background: transparent;\n  color: inherit;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  flex-direction: column;\n  gap: var(--dimension-space-025);\n  cursor: pointer;\n}\n\n.shell-mobile-bar__item--selected {\n  color: var(--color-foreground-primary);\n}\n\n.shell-mobile-bar__item ds-text {\n  display: block;\n  max-width: 100%;\n  overflow: hidden;\n  text-overflow: ellipsis;\n  white-space: nowrap;\n}\n\n.shell-mobile-bar__icon {\n  position: relative;\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  width: var(--dimension-iconography-md);\n  height: var(--dimension-iconography-md);\n}\n\n.shell-mobile-bar__dot {\n  position: absolute;\n  inset-block-start: calc(var(--dimension-space-025) * -1);\n  inset-inline-end: calc(var(--dimension-space-025) * -1);\n  width: var(--dimension-size-075);\n  height: var(--dimension-size-075);\n  border-radius: var(--dimension-radius-half);\n  background: var(--color-background-bold-brand);\n  box-shadow: 0 0 0 var(--dimension-stroke-width-025) var(--color-background-primary);\n}\n",
+      "type": "registry:ui"
+    },
+    {
+      "path": "src/wc/components/ShellMobileBar/ShellMobileBar.tsx",
+      "content": "import {\n  Component,\n  Element,\n  Event,\n  EventEmitter,\n  h,\n  Host,\n  Method,\n  Prop,\n} from '@stencil/core';\nimport {\n  shouldEmitMobileDestinationChange,\n  type ShellMobileDestination,\n} from '../../shell/shell-responsive';\nimport type { PanelNavItem } from '../PanelNav/panel-nav-types';\nimport type { ShellMobileBarDestinationDetail } from './shell-mobile-bar-types';\n\ninterface DestinationConfig {\n  id: ShellMobileDestination;\n  icon: string;\n  label: string;\n  dot: boolean;\n}\n\n@Component({\n  tag: 'ds-shell-mobile-bar',\n  styleUrl: 'ShellMobileBar.css',\n  scoped: true,\n})\nexport class ShellMobileBar {\n  @Element() el!: HTMLElement;\n\n  @Prop() activeDestination: ShellMobileDestination = 'area';\n  @Prop() currentArea: PanelNavItem = {\n    id: 'tracking',\n    icon: 'MapPage',\n    label: 'Tracking',\n  };\n  @Prop() navigationExpanded: boolean = false;\n  @Prop() menuLabel: string = 'Menu';\n  @Prop() searchLabel: string = 'Search';\n  @Prop() agentsLabel: string = 'Agents';\n  @Prop() inboxLabel: string = 'Inbox';\n  @Prop() searchDot: boolean = false;\n  @Prop() agentsDot: boolean = false;\n  @Prop() inboxDot: boolean = false;\n\n  @Event() dsNavigationToggle!: EventEmitter<boolean>;\n  @Event() dsDestinationChange!: EventEmitter<ShellMobileBarDestinationDetail>;\n\n  private destinationConfig(): DestinationConfig[] {\n    return [\n      {\n        id: 'area',\n        icon: this.currentArea.icon || 'MapPage',\n        label: this.currentArea.label || 'Area',\n        dot: false,\n      },\n      { id: 'search', icon: 'MagnifyingGlass', label: this.searchLabel, dot: this.searchDot },\n      { id: 'agents', icon: 'AI', label: this.agentsLabel, dot: this.agentsDot },\n      { id: 'inbox', icon: 'Inbox', label: this.inboxLabel, dot: this.inboxDot },\n    ];\n  }\n\n  private selectDestination(destination: ShellMobileDestination) {\n    if (\n      !shouldEmitMobileDestinationChange(\n        this.activeDestination,\n        destination,\n        this.navigationExpanded\n      )\n    ) {\n      return;\n    }\n    this.dsDestinationChange.emit({ destination });\n  }\n\n  @Method()\n  async focusDestination(destination: ShellMobileDestination | 'navigation') {\n    const target = this.el.querySelector<HTMLElement>(\n      `#${\n        destination === 'navigation'\n          ? 'ds-shell-mobile-navigation-trigger'\n          : `ds-shell-mobile-${destination}-trigger`\n      }`\n    );\n    target?.focus({ preventScroll: true });\n  }\n\n  private renderDestination(item: DestinationConfig) {\n    const selected = !this.navigationExpanded && item.id === this.activeDestination;\n    return (\n      <button\n        id={`ds-shell-mobile-${item.id}-trigger`}\n        type=\"button\"\n        class={{\n          'shell-mobile-bar__item': true,\n          'shell-mobile-bar__item--selected': selected,\n          'ds-focus-ring-inset': true,\n          'ds-interaction-fill': true,\n          'ds-interaction-fill--selected': selected,\n        }}\n        aria-current={selected ? 'page' : undefined}\n        onClick={() => this.selectDestination(item.id)}\n      >\n        <span class=\"shell-mobile-bar__icon\">\n          <ds-icon name={item.icon} size=\"md\" color=\"inherit\" />\n          {item.dot && (\n            <span class=\"shell-mobile-bar__dot\" aria-hidden=\"true\" />\n          )}\n        </span>\n        <ds-text as=\"span\" variant=\"text-caption\" color=\"inherit\">\n          {item.label}\n        </ds-text>\n      </button>\n    );\n  }\n\n  render() {\n    return (\n      <Host>\n        <nav class=\"shell-mobile-bar\" aria-label=\"Primary\">\n          <button\n            id=\"ds-shell-mobile-navigation-trigger\"\n            type=\"button\"\n            class={{\n              'shell-mobile-bar__item': true,\n              'shell-mobile-bar__item--selected': this.navigationExpanded,\n              'ds-focus-ring-inset': true,\n              'ds-interaction-fill': true,\n              'ds-interaction-fill--selected': this.navigationExpanded,\n            }}\n            aria-expanded={String(this.navigationExpanded)}\n            aria-controls=\"ds-shell-mobile-navigation\"\n            onClick={() => this.dsNavigationToggle.emit(!this.navigationExpanded)}\n          >\n            <span class=\"shell-mobile-bar__icon\">\n              <ds-icon name=\"Hamburger\" size=\"md\" color=\"inherit\" />\n            </span>\n            <ds-text\n              as=\"span\"\n              variant=\"text-caption\"\n              color=\"inherit\"\n            >\n              {this.menuLabel}\n            </ds-text>\n          </button>\n          {this.destinationConfig().map(item => this.renderDestination(item))}\n        </nav>\n      </Host>\n    );\n  }\n}\n",
+      "type": "registry:ui"
+    },
+    {
+      "path": "src/wc/components/ShellMobileBar/shell-mobile-bar-types.ts",
+      "content": "import type { ShellMobileDestination } from '../../shell/shell-responsive';\n\nexport interface ShellMobileBarDestinationDetail {\n  destination: ShellMobileDestination;\n}\n",
+      "type": "registry:ui"
+    }
+  ]
+}