@ds-mo/ui 13.4.0 → 13.6.0

package/dist/mcp-data/registry/panel-tools.json

@@ -55,6 +55,7 @@
         "Provide localized accessible labels for the rail, shortcut group, and every rendered tool.",
         "Use the canonical default recipe when the product needs Search first and Help last; custom recipes must preserve a deliberate keyboard and visual order.",
         "Keep focus on the selected rail action when opening a drawer and allow normal Tab navigation into its content.",
+        "When the shortcut rail overflows, its labeled body becomes a keyboard-focusable scroll region without changing the rail action order.",
         "Do not trigger global shortcuts while focus is in an editable control.",
         "Use notification dots only as supplemental unread or new-content status and never as the sole status indication.",
         "Explain temporarily inactive tools through an accessible label or adjacent product guidance; omit unauthorized tools entirely."
@@ -438,7 +439,7 @@
       "complexPropertyNote": "Assign these non-primitive values as JavaScript properties: headers, items.",
       "peerDependencies": {
         "required": [
-          "@ds-mo/tokens ^5.1.0",
+          "@ds-mo/tokens ^5.1.1",
           "@ds-mo/icons ^6.4.0"
         ],
         "frameworks": "Custom Elements; React 18/19 wrappers; Angular 19-22 standalone adapters."
@@ -457,12 +458,12 @@
   "files": [
     {
       "path": "src/wc/components/PanelTools/PanelTools.css",
-      "content": "@import '../../utils/control-density.css';\n@import '../../utils/chrome-layout.css';\n@import '../../utils/scrollbar-hidden.css';\n\n:host {\n  display: block;\n  flex: 0 0 auto;\n  box-sizing: border-box;\n  height: 100%;\n  min-height: 0;\n  overflow: hidden;\n  --_panel-tools-rail-width: var(--dimension-size-600);\n  --_panel-tools-drawer-width: var(--ds-shell-panel-tools-width, var(--dimension-panel-width-xs));\n  --_panel-tools-border: var(--dimension-stroke-width-012, 1px) solid var(--color-border-tertiary);\n  /* Match panel-nav expand timing (medium-1); easing differs by direction. */\n  --_panel-tools-expand-dur: var(--effect-animation-duration-medium-1, 300ms);\n}\n\n.panel-tools__layout {\n  display: flex;\n  flex-direction: row-reverse;\n  align-items: stretch;\n  height: 100%;\n  min-height: 0;\n  box-sizing: border-box;\n}\n\n/* Clip frame — only max-width animates (slide reveal, same as pre-rail :host). */\n.panel-tools__drawer {\n  flex: 0 0 auto;\n  max-width: 0;\n  min-width: 0;\n  height: 100%;\n  min-height: 0;\n  overflow: hidden;\n  box-sizing: border-box;\n  transition: none;\n}\n\n:host(.panel-tools--ready) .panel-tools__drawer {\n  transition: max-width var(--_panel-tools-expand-dur)\n    var(--effect-animation-easing-ease-in-out, ease);\n}\n\n:host(.panel-tools--ready.panel-tools--motion-opening) .panel-tools__drawer {\n  transition: max-width var(--_panel-tools-expand-dur)\n    var(--effect-animation-easing-ease-out, ease-out);\n}\n\n:host(.panel-tools--ready.panel-tools--motion-closing) .panel-tools__drawer {\n  transition: max-width var(--_panel-tools-expand-dur)\n    var(--effect-animation-easing-ease-in, ease-in);\n}\n\n:host(.panel-tools--open) .panel-tools__drawer {\n  max-width: var(--_panel-tools-drawer-width);\n}\n\n.panel-tools__drawer--visible {\n  border-left: var(--_panel-tools-border);\n}\n\n/* Fixed-width surface — ShellApp supplies the standard 300px tools width. */\n.panel-tools__drawer-surface {\n  display: flex;\n  flex-direction: column;\n  width: var(--_panel-tools-drawer-width);\n  height: 100%;\n  min-height: 0;\n  box-sizing: border-box;\n  background-color: transparent;\n}\n\n.panel-tools__full-views,\n.panel-tools__full-view {\n  flex: 1 1 auto;\n  min-height: 0;\n  overflow: hidden;\n}\n\n.panel-tools__full-view {\n  height: 100%;\n}\n\n.panel-tools__full-view {\n  display: none;\n}\n.panel-tools__full-view--active {\n  display: block;\n}\n\n:host([presentation='fullscreen']) {\n  height: 100vh;\n  inset: 0;\n  position: fixed;\n  width: 100vw;\n  z-index: var(--dimension-z-index-modal);\n}\n\n:host([presentation='fullscreen']) .panel-tools__rail {\n  display: none;\n}\n:host([presentation='fullscreen']) .panel-tools__drawer {\n  max-width: 100vw;\n  transition: none;\n  width: 100vw;\n}\n:host([presentation='fullscreen']) .panel-tools__drawer--visible {\n  border-left: none;\n}\n:host([presentation='fullscreen']) .panel-tools__drawer-surface {\n  background-color: transparent;\n  width: 100vw;\n}\n\n/*\n * A framework can update the reflected presentation attribute before Stencil\n * commits the matching render class. Conceal that single inconsistent frame so\n * slotted master/detail content never paints against the previous geometry.\n */\n:host([presentation='fullscreen']:not(.panel-tools--fullscreen)) .panel-tools__drawer-surface,\n:host(.panel-tools--fullscreen:not([presentation='fullscreen'])) .panel-tools__drawer-surface {\n  visibility: hidden;\n}\n\n:host(.panel-tools--presentation-snap) .panel-tools__drawer {\n  transition: none;\n}\n\n.panel-tools__body {\n  flex: 1 1 auto;\n  min-height: 0;\n  overflow: auto;\n  position: relative;\n}\n\n/* Skip paint while fully closed; cleared during open/close motion for WYSIWYG slide. */\n:host(.panel-tools--drawer-resting) .panel-tools__body {\n  content-visibility: auto;\n  contain-intrinsic-size: auto 200px;\n}\n\n.panel-tools__view {\n  display: none;\n  height: 100%;\n  min-height: 0;\n  box-sizing: border-box;\n  padding: var(--dimension-space-200);\n  color: var(--color-foreground-secondary);\n  font-family: var(--typography-font-family);\n  font-size: var(--typography-fontsize-md);\n  line-height: var(--typography-lineheight-md);\n  font-weight: var(--typography-weight-regular);\n  letter-spacing: var(--typography-letterspacing-negative-half);\n}\n\n.panel-tools__view ::slotted(*) {\n  margin: 0;\n  color: var(--color-foreground-secondary);\n  font-family: var(--typography-font-family);\n  font-size: var(--typography-fontsize-md);\n  line-height: var(--typography-lineheight-md);\n  font-weight: var(--typography-weight-regular);\n  letter-spacing: var(--typography-letterspacing-negative-half);\n}\n\n.panel-tools__view--active {\n  display: block;\n}\n\n/* Rail — mirrors collapsed panel-nav width, padding, and item rhythm. */\n.panel-tools__rail {\n  flex: 0 0 var(--_panel-tools-rail-width);\n  width: var(--_panel-tools-rail-width);\n  min-width: var(--_panel-tools-rail-width);\n  display: flex;\n  flex-direction: column;\n  box-sizing: border-box;\n  height: 100%;\n  min-height: 0;\n  border-left: var(--_panel-tools-border);\n  background-color: transparent;\n}\n\n.panel-tools__rail-header {\n  justify-content: center;\n  height: var(--dimension-size-600);\n  flex-shrink: 0;\n  border-bottom: var(--_panel-tools-border);\n}\n\n.panel-tools__rail-body {\n  flex: 1 1 auto;\n  min-height: 0;\n  overflow-y: auto;\n  overflow-x: hidden;\n}\n\n.panel-tools__rail-actions {\n  display: flex;\n  flex-direction: column;\n  gap: var(--dimension-space-050);\n  width: 100%;\n}\n\n/* Flush to the bottom of the rail — mirrors Search header pin. */\n.panel-tools__rail-footer {\n  justify-content: center;\n  flex-shrink: 0;\n  margin-top: auto;\n}\n\n.panel-tools__rail-action {\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  width: 100%;\n  height: var(--ds-control-height);\n  flex-shrink: 0;\n}\n\n@media (prefers-reduced-motion: reduce) {\n  :host(.panel-tools--ready.panel-tools--motion-opening) .panel-tools__drawer,\n  :host(.panel-tools--ready.panel-tools--motion-closing) .panel-tools__drawer {\n    transition: none;\n  }\n}\n",
+      "content": "@import '../../utils/control-density.css';\n@import '../../utils/chrome-layout.css';\n@import '../../utils/focus-ring.css';\n@import '../../utils/scrollbar-hidden.css';\n\n:host {\n  display: block;\n  flex: 0 0 auto;\n  box-sizing: border-box;\n  height: 100%;\n  min-height: 0;\n  overflow: hidden;\n  --_panel-tools-rail-width: var(--dimension-size-600);\n  --_panel-tools-drawer-width: var(--ds-shell-panel-tools-width, var(--dimension-panel-width-xs));\n  --_panel-tools-border: var(--dimension-stroke-width-012, 1px) solid var(--color-border-tertiary);\n  /* Match panel-nav expand timing (medium-1); easing differs by direction. */\n  --_panel-tools-expand-dur: var(--effect-animation-duration-medium-1, 300ms);\n}\n\n.panel-tools__layout {\n  display: flex;\n  flex-direction: row-reverse;\n  align-items: stretch;\n  height: 100%;\n  min-height: 0;\n  box-sizing: border-box;\n}\n\n/* Clip frame — only max-width animates (slide reveal, same as pre-rail :host). */\n.panel-tools__drawer {\n  flex: 0 0 auto;\n  max-width: 0;\n  min-width: 0;\n  height: 100%;\n  min-height: 0;\n  overflow: hidden;\n  box-sizing: border-box;\n  transition: none;\n}\n\n:host(.panel-tools--ready) .panel-tools__drawer {\n  transition: max-width var(--_panel-tools-expand-dur)\n    var(--effect-animation-easing-ease-in-out, ease);\n}\n\n:host(.panel-tools--ready.panel-tools--motion-opening) .panel-tools__drawer {\n  transition: max-width var(--_panel-tools-expand-dur)\n    var(--effect-animation-easing-ease-out, ease-out);\n}\n\n:host(.panel-tools--ready.panel-tools--motion-closing) .panel-tools__drawer {\n  transition: max-width var(--_panel-tools-expand-dur)\n    var(--effect-animation-easing-ease-in, ease-in);\n}\n\n:host(.panel-tools--open) .panel-tools__drawer {\n  max-width: var(--_panel-tools-drawer-width);\n}\n\n.panel-tools__drawer--visible {\n  border-left: var(--_panel-tools-border);\n}\n\n/* Fixed-width surface — ShellApp supplies the standard 300px tools width. */\n.panel-tools__drawer-surface {\n  display: flex;\n  flex-direction: column;\n  width: var(--_panel-tools-drawer-width);\n  height: 100%;\n  min-height: 0;\n  box-sizing: border-box;\n  background-color: transparent;\n}\n\n.panel-tools__full-views,\n.panel-tools__full-view {\n  flex: 1 1 auto;\n  min-height: 0;\n  overflow: hidden;\n}\n\n.panel-tools__full-view {\n  height: 100%;\n}\n\n.panel-tools__full-view {\n  display: none;\n}\n.panel-tools__full-view--active {\n  display: block;\n}\n\n:host([presentation='fullscreen']) {\n  height: 100vh;\n  inset: 0;\n  position: fixed;\n  width: 100vw;\n  z-index: var(--dimension-z-index-modal);\n}\n\n:host([presentation='fullscreen']) .panel-tools__rail {\n  display: none;\n}\n:host([presentation='fullscreen']) .panel-tools__drawer {\n  max-width: 100vw;\n  transition: none;\n  width: 100vw;\n}\n:host([presentation='fullscreen']) .panel-tools__drawer--visible {\n  border-left: none;\n}\n:host([presentation='fullscreen']) .panel-tools__drawer-surface {\n  background-color: transparent;\n  width: 100vw;\n}\n\n/*\n * A framework can update the reflected presentation attribute before Stencil\n * commits the matching render class. Conceal that single inconsistent frame so\n * slotted master/detail content never paints against the previous geometry.\n */\n:host([presentation='fullscreen']:not(.panel-tools--fullscreen)) .panel-tools__drawer-surface,\n:host(.panel-tools--fullscreen:not([presentation='fullscreen'])) .panel-tools__drawer-surface {\n  visibility: hidden;\n}\n\n:host(.panel-tools--presentation-snap) .panel-tools__drawer {\n  transition: none;\n}\n\n.panel-tools__body {\n  flex: 1 1 auto;\n  min-height: 0;\n  overflow: auto;\n  position: relative;\n}\n\n/* Skip paint while fully closed; cleared during open/close motion for WYSIWYG slide. */\n:host(.panel-tools--drawer-resting) .panel-tools__body {\n  content-visibility: auto;\n  contain-intrinsic-size: auto 200px;\n}\n\n.panel-tools__view {\n  display: none;\n  height: 100%;\n  min-height: 0;\n  box-sizing: border-box;\n  padding: var(--dimension-space-200);\n  color: var(--color-foreground-secondary);\n  font-family: var(--typography-font-family);\n  font-size: var(--typography-fontsize-md);\n  line-height: var(--typography-lineheight-md);\n  font-weight: var(--typography-weight-regular);\n  letter-spacing: var(--typography-letterspacing-negative-half);\n}\n\n.panel-tools__view ::slotted(*) {\n  margin: 0;\n  color: var(--color-foreground-secondary);\n  font-family: var(--typography-font-family);\n  font-size: var(--typography-fontsize-md);\n  line-height: var(--typography-lineheight-md);\n  font-weight: var(--typography-weight-regular);\n  letter-spacing: var(--typography-letterspacing-negative-half);\n}\n\n.panel-tools__view--active {\n  display: block;\n}\n\n/* Rail — mirrors collapsed panel-nav width, padding, and item rhythm. */\n.panel-tools__rail {\n  flex: 0 0 var(--_panel-tools-rail-width);\n  width: var(--_panel-tools-rail-width);\n  min-width: var(--_panel-tools-rail-width);\n  display: flex;\n  flex-direction: column;\n  box-sizing: border-box;\n  height: 100%;\n  min-height: 0;\n  border-left: var(--_panel-tools-border);\n  background-color: transparent;\n}\n\n.panel-tools__rail-header {\n  justify-content: center;\n  height: var(--dimension-size-600);\n  flex-shrink: 0;\n  border-bottom: var(--_panel-tools-border);\n}\n\n.panel-tools__rail-body {\n  flex: 1 1 auto;\n  min-height: 0;\n  overflow-y: auto;\n  overflow-x: hidden;\n}\n\n.panel-tools__rail-actions {\n  display: flex;\n  flex-direction: column;\n  gap: var(--dimension-space-050);\n  width: 100%;\n}\n\n/* Flush to the bottom of the rail — mirrors Search header pin. */\n.panel-tools__rail-footer {\n  justify-content: center;\n  flex-shrink: 0;\n  margin-top: auto;\n}\n\n.panel-tools__rail-action {\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  width: 100%;\n  height: var(--ds-control-height);\n  flex-shrink: 0;\n}\n\n@media (prefers-reduced-motion: reduce) {\n  :host(.panel-tools--ready.panel-tools--motion-opening) .panel-tools__drawer,\n  :host(.panel-tools--ready.panel-tools--motion-closing) .panel-tools__drawer {\n    transition: none;\n  }\n}\n",
       "type": "registry:ui"
     },
     {
       "path": "src/wc/components/PanelTools/PanelTools.tsx",
-      "content": "import {\n  Component,\n  Prop,\n  Event,\n  EventEmitter,\n  Element,\n  State,\n  Watch,\n  Method,\n  Listen,\n  h,\n  Host,\n} from '@stencil/core';\nimport type { ChromeTransitionDetail } from '../../shell/chrome-transition';\nimport {\n  PANEL_TOOLS_LABELS,\n  PANEL_TOOLS_SHORTCUTS,\n  type PanelToolsHeaderAction,\n  type PanelToolsHeaderConfig,\n  type PanelToolsHeaders,\n  type PanelToolsItem,\n  type PanelToolsToolId,\n} from './panel-tools-types';\nimport {\n  isPanelToolsToolId,\n  orderPanelToolsItems,\n  panelToolsDrawerAtTerminal,\n  panelToolsDrawerResting,\n  panelToolsDrawerTransitionMs,\n  panelToolsRailPlacement,\n  reconcilePanelToolsAvailability,\n  resolvePanelToolActivation,\n} from './panel-tools-utils';\n\n@Component({\n  tag: 'ds-panel-tools',\n  styleUrl: 'PanelTools.css',\n  scoped: true,\n})\nexport class PanelTools {\n  @Element() el!: HTMLElement;\n\n  /** When false, only the icon rail is shown. */\n  @Prop({ mutable: true, reflect: true }) open: boolean = false;\n\n  /** Drawer presentation or viewport-covering presentation for the active tool. */\n  @Prop({ mutable: true, reflect: true }) presentation: 'drawer' | 'fullscreen' = 'drawer';\n\n  /** Let a fullscreen product supply independent master/detail headers inside its view. */\n  @Prop({ attribute: 'fullscreen-header-mode', reflect: true })\n  fullscreenHeaderMode: 'shared' | 'split' = 'shared';\n\n  /** Active tool view — `search`, `agents`, `messages`, `stacks`, `activity`, or `help`. */\n  @Prop({ mutable: true, attribute: 'active-tool', reflect: true })\n  activeTool: PanelToolsToolId | '' = '';\n\n  /**\n   * Rail items rendered in the right column.\n   * Set via JS property: `el.items = [...]`. Replace the array reference to update.\n   */\n  @Prop() items: PanelToolsItem[] = [];\n\n  @Prop() toolsLabel: string = 'Tools';\n  @Prop() toolShortcutsLabel: string = 'Tool shortcuts';\n\n  /** Active header state per tool. Replace the object when title, depth, or actions change. */\n  @Prop() headers: PanelToolsHeaders = {};\n\n  /**\n   * Optional localStorage key for the last active tool. The drawer always starts\n   * closed; only the tool identity is restored for continuity within this browser.\n   */\n  @Prop({ attribute: 'storage-key' }) storageKey: string = '';\n\n  /** Emitted when a rail button is toggled. Detail = { id, selected }. */\n  @Event({ bubbles: true, composed: true }) dsToolChange!: EventEmitter<{\n    id: PanelToolsToolId;\n    selected: boolean;\n  }>;\n\n  /** Emitted when fullscreen changes, including Escape-initiated exits. */\n  @Event({ bubbles: true, composed: true }) dsPresentationChange!: EventEmitter<{\n    presentation: 'drawer' | 'fullscreen';\n  }>;\n\n  /** Requests navigation to the active tool's parent view. */\n  @Event({ bubbles: true, composed: true }) dsHeaderBack!: EventEmitter<{\n    tool: PanelToolsToolId;\n  }>;\n\n  /** Requests one application-owned action from the active tool header. */\n  @Event({ bubbles: true, composed: true }) dsHeaderAction!: EventEmitter<{\n    tool: PanelToolsToolId;\n    id: string;\n  }>;\n\n  /** Bubbling lifecycle — `ds-bar-nav` defers overflow checks during drawer motion. */\n  @Event({ bubbles: true, composed: true })\n  dsChromeTransitionStart!: EventEmitter<ChromeTransitionDetail>;\n\n  @Event({ bubbles: true, composed: true })\n  dsChromeTransitionEnd!: EventEmitter<ChromeTransitionDetail>;\n\n  /** Arms open vs close easing for the in-flight width transition. */\n  @State() private motion: 'opening' | 'closing' | 'idle' = 'idle';\n\n  /** Keeps header and slotted content painted until the closing clip transition completes. */\n  @State() private drawerSurfaceRetained = false;\n\n  /** Suppresses width transition until the host has painted its initial open state. */\n  @State() private readyForMotion = false;\n\n  /** Fullscreen presentation changes snap without borrowing drawer width motion. */\n  @State() private presentationMotionSuppressed = false;\n\n  @State() private rovingIndex = 0;\n  @State() private fullViewToolIds: PanelToolsToolId[] = [];\n\n  private motionEnableGeneration = 0;\n  private presentationMotionGeneration = 0;\n  private transitionGeneration = 0;\n  private transitionFallbackTimer: number | null = null;\n  /** Ignores the old transition's terminal event when reversing direction. */\n  private ignoreReplacementTerminal = false;\n  private focusBeforeFullscreen: HTMLElement | null = null;\n  private fullViewObserver: MutationObserver | null = null;\n\n  private get railItems(): PanelToolsItem[] {\n    return this.items ?? [];\n  }\n\n  private get orderedRailItems(): PanelToolsItem[] {\n    return orderPanelToolsItems(this.railItems);\n  }\n\n  disconnectedCallback() {\n    this.el.removeEventListener('transitionend', this.handleTransitionEnd);\n    this.el.removeEventListener('transitioncancel', this.handleTransitionEnd);\n    this.el.removeEventListener('dsAction', this.handleComposedHeaderAction);\n    this.clearTransitionCompletion();\n    this.motionEnableGeneration += 1;\n    this.fullViewObserver?.disconnect();\n    this.fullViewObserver = null;\n  }\n\n  @Watch('presentation')\n  presentationChanged(next: 'drawer' | 'fullscreen', previous?: 'drawer' | 'fullscreen') {\n    if (next === previous) return;\n    // Framework property bindings can update slotted master/detail content in\n    // the same render that requests fullscreen. Reflect the host selector\n    // immediately so that content cannot paint once in the drawer geometry\n    // while Stencil waits to commit its next render.\n    if (this.el.getAttribute('presentation') !== next) {\n      this.el.setAttribute('presentation', next);\n    }\n    const presentationGeneration = ++this.presentationMotionGeneration;\n    this.presentationMotionSuppressed = true;\n    requestAnimationFrame(() => {\n      requestAnimationFrame(() => {\n        if (presentationGeneration !== this.presentationMotionGeneration) return;\n        this.presentationMotionSuppressed = false;\n      });\n    });\n    if (next === 'fullscreen') {\n      this.focusBeforeFullscreen =\n        document.activeElement instanceof HTMLElement ? document.activeElement : null;\n      this.open = true;\n    } else if (previous === 'fullscreen') {\n      const focusBeforeFullscreen = this.focusBeforeFullscreen;\n      const fallbackActionId = this.activeHeader().actions?.[0]?.id;\n      requestAnimationFrame(async () => {\n        if (focusBeforeFullscreen?.isConnected) {\n          focusBeforeFullscreen.focus({ preventScroll: true });\n        }\n        const focusRestored = focusBeforeFullscreen\n          ? document.activeElement === focusBeforeFullscreen ||\n            focusBeforeFullscreen.contains(document.activeElement)\n          : false;\n        if (!focusRestored && fallbackActionId) await this.focusHeaderAction(fallbackActionId);\n        this.focusBeforeFullscreen = null;\n      });\n    }\n    this.dsPresentationChange.emit({ presentation: next });\n  }\n\n  @Listen('keydown', { target: 'window', capture: true })\n  handleFullscreenEscape(event: KeyboardEvent) {\n    if (this.presentation !== 'fullscreen' || event.key !== 'Escape') return;\n    event.preventDefault();\n    event.stopPropagation();\n    this.presentation = 'drawer';\n  }\n\n  private deferMotionEnable() {\n    if (this.readyForMotion) return;\n    const generation = ++this.motionEnableGeneration;\n    requestAnimationFrame(() => {\n      if (generation !== this.motionEnableGeneration) return;\n      requestAnimationFrame(() => {\n        if (generation !== this.motionEnableGeneration) return;\n        this.readyForMotion = true;\n      });\n    });\n  }\n\n  connectedCallback() {\n    this.el.addEventListener('transitionend', this.handleTransitionEnd);\n    this.el.addEventListener('transitioncancel', this.handleTransitionEnd);\n    this.el.addEventListener('dsAction', this.handleComposedHeaderAction);\n  }\n\n  private handleComposedHeaderAction = (event: Event) => {\n    const detail = (event as CustomEvent<{ id?: string }>).detail;\n    if (!this.activeTool || !detail?.id) return;\n    event.stopPropagation();\n    this.dsHeaderAction.emit({ tool: this.activeTool, id: detail.id });\n  };\n\n  componentWillLoad() {\n    this.restoreLastActiveTool();\n    this.drawerSurfaceRetained = this.open;\n  }\n\n  @Watch('open')\n  openChanged(isOpen: boolean, wasOpen?: boolean) {\n    if (isOpen) this.drawerSurfaceRetained = true;\n    if (this.readyForMotion && wasOpen !== undefined && wasOpen !== isOpen) {\n      this.startDrawerTransition(isOpen ? 'opening' : 'closing');\n    } else if (!isOpen) {\n      this.drawerSurfaceRetained = false;\n    }\n    this.deferMotionEnable();\n  }\n\n  @Watch('activeTool')\n  activeToolChanged() {\n    this.persistLastActiveTool();\n    this.deferMotionEnable();\n  }\n\n  @Watch('storageKey')\n  storageKeyChanged() {\n    this.restoreLastActiveTool();\n  }\n\n  componentDidLoad() {\n    this.deferMotionEnable();\n    this.syncFullViewTools();\n    this.fullViewObserver = new MutationObserver(() => this.syncFullViewTools());\n    this.fullViewObserver.observe(this.el, {\n      childList: true,\n      attributes: true,\n      attributeFilter: ['slot'],\n    });\n  }\n\n  @Watch('items')\n  itemsChanged() {\n    this.rovingIndex = 0;\n    this.reconcileActiveTool();\n    this.deferMotionEnable();\n  }\n\n  private restoreLastActiveTool() {\n    if (!this.storageKey || this.activeTool) return;\n    try {\n      const stored = localStorage.getItem(this.storageKey);\n      if (isPanelToolsToolId(stored)) this.activeTool = stored;\n    } catch {\n      /* localStorage unavailable */\n    }\n  }\n\n  private persistLastActiveTool() {\n    if (!this.storageKey || !this.activeTool) return;\n    try {\n      localStorage.setItem(this.storageKey, this.activeTool);\n    } catch {\n      /* unavailable */\n    }\n  }\n\n  private clearPersistedTool() {\n    if (!this.storageKey) return;\n    try {\n      localStorage.removeItem(this.storageKey);\n    } catch {\n      /* unavailable */\n    }\n  }\n\n  private reconcileActiveTool() {\n    const next = reconcilePanelToolsAvailability(this.railItems, this.open, this.activeTool);\n    if (!next.removedTool) return;\n    this.clearPersistedTool();\n    this.open = next.open;\n    this.activeTool = next.activeTool;\n    this.dsToolChange.emit({ id: next.removedTool, selected: false });\n  }\n\n  private startDrawerTransition(phase: 'opening' | 'closing') {\n    const drawer = this.el.querySelector('.panel-tools__drawer') as HTMLElement | null;\n    if (this.motion !== 'idle') {\n      this.finishDrawerTransition();\n      this.ignoreReplacementTerminal = true;\n    }\n    this.motion = phase;\n    this.dsChromeTransitionStart.emit({ source: 'panel-tools', phase });\n    const generation = ++this.transitionGeneration;\n\n    requestAnimationFrame(() => {\n      requestAnimationFrame(() => {\n        if (generation !== this.transitionGeneration || this.motion !== phase) return;\n        if (!drawer) {\n          this.finishDrawerTransition();\n          return;\n        }\n\n        if (this.drawerTransitionAtTerminal(drawer, phase)) {\n          this.finishDrawerTransition();\n          return;\n        }\n\n        const fallbackMs = panelToolsDrawerTransitionMs(getComputedStyle(drawer));\n        if (fallbackMs <= 0) {\n          this.finishDrawerTransition();\n          return;\n        }\n        this.transitionFallbackTimer = window.setTimeout(() => {\n          this.finishDrawerTransition();\n        }, fallbackMs);\n      });\n    });\n  }\n\n  private handleTransitionEnd = (event: TransitionEvent) => {\n    const drawer = this.el.querySelector('.panel-tools__drawer') as HTMLElement | null;\n    if (event.target !== drawer) return;\n    if (event.propertyName !== 'max-width') return;\n    if (this.ignoreReplacementTerminal) {\n      this.ignoreReplacementTerminal = false;\n      return;\n    }\n    // Changing from the neutral transition recipe to the direction-specific\n    // easing can cancel the transition that the reflected `open` class began.\n    // The replacement transition and its watchdog still own completion; ending\n    // motion here would hide the fixed-width tool surface while it is visible.\n    if (event.type === 'transitioncancel') return;\n    if (drawer && !this.drawerTransitionAtTerminal(drawer, this.motion)) return;\n    this.finishDrawerTransition();\n  };\n\n  private drawerTransitionAtTerminal(\n    drawer: HTMLElement,\n    phase: 'opening' | 'closing' | 'idle'\n  ): boolean {\n    const width = drawer.getBoundingClientRect().width;\n    const surface = drawer.querySelector('.panel-tools__drawer-surface') as HTMLElement | null;\n    const targetWidth = surface?.getBoundingClientRect().width ?? 0;\n    return panelToolsDrawerAtTerminal(width, targetWidth, phase);\n  }\n\n  private finishDrawerTransition() {\n    const completedPhase = this.motion;\n    const wasTransitioning = completedPhase !== 'idle';\n    this.clearTransitionCompletion();\n    if (!wasTransitioning) return;\n    this.ignoreReplacementTerminal = false;\n    this.motion = 'idle';\n    if (completedPhase === 'closing' && !this.open) {\n      this.drawerSurfaceRetained = false;\n    }\n    this.dsChromeTransitionEnd.emit({ source: 'panel-tools' });\n  }\n\n  private clearTransitionCompletion() {\n    this.transitionGeneration += 1;\n    if (this.transitionFallbackTimer !== null) {\n      window.clearTimeout(this.transitionFallbackTimer);\n      this.transitionFallbackTimer = null;\n    }\n  }\n\n  /** Rail selection follows `open` immediately — independent of the slide animation. */\n  private isRailSelected(id: PanelToolsToolId): boolean {\n    return this.open && this.activeTool === id;\n  }\n\n  /** Drawer body stays mounted while the clip frame animates closed. */\n  private isDrawerPresent(): boolean {\n    return this.open || this.drawerSurfaceRetained;\n  }\n\n  private isViewActive(id: PanelToolsToolId): boolean {\n    return this.isDrawerPresent() && this.activeTool === id;\n  }\n\n  private hasFullView(id: PanelToolsToolId): boolean {\n    return this.fullViewToolIds.includes(id);\n  }\n\n  private syncFullViewTools() {\n    const ids = this.orderedRailItems.map(item => item.id);\n    const next = ids.filter(id => Boolean(this.el.querySelector(`[slot=\"${id}-view\"]`)));\n    if (next.join('|') !== this.fullViewToolIds.join('|')) this.fullViewToolIds = next;\n  }\n\n  private headerLabel(): string {\n    if (!this.isDrawerPresent() || !this.activeTool) return '';\n    const item = this.railItems.find(candidate => candidate.id === this.activeTool);\n    return (\n      item?.label ??\n      PANEL_TOOLS_LABELS[this.activeTool as keyof typeof PANEL_TOOLS_LABELS] ??\n      this.activeTool\n    );\n  }\n\n  private resolvedHeaders(): PanelToolsHeaders {\n    return this.headers ?? {};\n  }\n\n  private activeHeader(): PanelToolsHeaderConfig {\n    if (!this.activeTool) return {};\n    return this.resolvedHeaders()[this.activeTool] ?? {};\n  }\n\n  private handleToolChange = (id: PanelToolsToolId) => {\n    const next = resolvePanelToolActivation(this.open, this.activeTool, id);\n    this.open = next.open;\n    this.activeTool = next.activeTool;\n    this.dsToolChange.emit({ id, selected: next.selected });\n  };\n\n  /** Toggle any rail tool open/closed — shell shortcuts K/A/S/M/N call this. */\n  @Method()\n  async activateTool(id: PanelToolsToolId) {\n    const item = this.railItems.find(entry => entry.id === id);\n    if (!item || item.isInactive) return;\n    this.handleToolChange(id);\n  }\n\n  /** Close the tools drawer when open — used by shell keyboard shortcuts. */\n  @Method()\n  async closeDrawer() {\n    if (!this.open) return;\n    const id = this.activeTool;\n    this.open = false;\n    if (id) {\n      this.dsToolChange.emit({ id, selected: false });\n    }\n  }\n\n  /** Focus an active tool-header action by its application-owned id. */\n  @Method()\n  async focusHeaderAction(id: string) {\n    const action = this.el.querySelector(`[data-header-action-id=\"${CSS.escape(id)}\"]`) as\n      | (HTMLElement & { setFocus?: () => Promise<void> })\n      | null;\n    await action?.setFocus?.();\n  }\n\n  private focusRailAt(index: number) {\n    const items = this.orderedRailItems;\n    if (!items.length) return;\n    const bounded = Math.max(0, Math.min(index, items.length - 1));\n    if (bounded === this.rovingIndex) return;\n    this.rovingIndex = bounded;\n    const actions = Array.from(\n      this.el.querySelectorAll<HTMLElement>('.panel-tools__rail-action .button-icon')\n    );\n    actions[bounded]?.focus({ preventScroll: true });\n  }\n\n  private handleRailKeyDown = (e: KeyboardEvent, index: number) => {\n    const items = this.orderedRailItems;\n    if (!items.length) return;\n\n    if (e.key === 'Enter' || e.key === ' ') {\n      e.preventDefault();\n      this.handleToolChange(items[index].id);\n      return;\n    }\n\n    if (e.key === 'ArrowDown') {\n      if (index >= items.length - 1) return;\n      e.preventDefault();\n      this.focusRailAt(index + 1);\n      return;\n    }\n\n    if (e.key === 'ArrowUp') {\n      if (index <= 0) return;\n      e.preventDefault();\n      this.focusRailAt(index - 1);\n    }\n  };\n\n  private renderRailAction(item: PanelToolsItem, index: number) {\n    const label =\n      item.ariaLabel ??\n      item.label ??\n      PANEL_TOOLS_LABELS[item.id as keyof typeof PANEL_TOOLS_LABELS] ??\n      item.id;\n    return (\n      <ds-tooltip\n        key={item.id}\n        label={label}\n        shortcutKey={\n          item.shortcutKey ??\n          PANEL_TOOLS_SHORTCUTS[item.id as keyof typeof PANEL_TOOLS_SHORTCUTS]\n        }\n        side=\"left\"\n        size=\"sm\"\n      >\n        <ds-button-unfilled\n          variant=\"icon\"\n          class=\"panel-tools__rail-action\"\n          icon={item.icon}\n          isActive={this.isRailSelected(item.id)}\n          activeFill={false}\n          hasBorder={false}\n          pressScale={false}\n          dot={item.dot ?? false}\n          isInactive={item.isInactive}\n          focusTabIndex={index === this.rovingIndex ? 0 : -1}\n          aria-label={label}\n          pressed={this.isRailSelected(item.id)}\n          onFocusin={() => {\n            this.rovingIndex = index;\n          }}\n          onKeyDown={(e: KeyboardEvent) => this.handleRailKeyDown(e, index)}\n          onDsClick={() => this.handleToolChange(item.id)}\n        />\n      </ds-tooltip>\n    );\n  }\n\n  render() {\n    const headerLabel = this.headerLabel();\n    const header = this.activeHeader();\n    const headerTitle = header.title?.trim() || headerLabel;\n    const headerActions = header.actions ?? [];\n    const orderedRailItems = this.orderedRailItems;\n    const headerItems = orderedRailItems.filter(\n      item => panelToolsRailPlacement(item) === 'header'\n    );\n    const bodyItems = orderedRailItems.filter(\n      item => panelToolsRailPlacement(item) === 'body'\n    );\n    const footerItems = orderedRailItems.filter(\n      item => panelToolsRailPlacement(item) === 'footer'\n    );\n    const headerCount = headerItems.length;\n    const footerStart = headerCount + bodyItems.length;\n    const showDrawerChrome = this.isDrawerPresent();\n    const drawerResting = panelToolsDrawerResting(this.open, this.motion);\n    const activeFullView = Boolean(\n      showDrawerChrome && this.activeTool && this.hasFullView(this.activeTool)\n    );\n    const toolIds = orderedRailItems.map(item => item.id);\n\n    return (\n      <Host\n        class={{\n          'panel-tools': true,\n          'panel-tools--open': this.open,\n          'panel-tools--ready': this.readyForMotion,\n          'panel-tools--motion-opening': this.motion === 'opening',\n          'panel-tools--motion-closing': this.motion === 'closing',\n          'panel-tools--drawer-resting': drawerResting,\n          'panel-tools--fullscreen': this.presentation === 'fullscreen',\n          'panel-tools--presentation-snap': this.presentationMotionSuppressed,\n        }}\n        role={this.presentation === 'fullscreen' ? 'dialog' : 'complementary'}\n        aria-modal={this.presentation === 'fullscreen' ? 'true' : undefined}\n        aria-label={this.toolsLabel}\n      >\n        <div class=\"panel-tools__layout\">\n          <nav class=\"panel-tools__rail\" aria-label={this.toolShortcutsLabel}>\n            {headerItems.length ? (\n              <div class=\"panel-tools__rail-header ds-chrome-row ds-chrome-space--md\">\n                {headerItems.map((item, index) => this.renderRailAction(item, index))}\n              </div>\n            ) : null}\n            <div class=\"panel-tools__rail-body ds-chrome-column ds-chrome-space--md ds-scrollbar-hidden\">\n              <div class=\"panel-tools__rail-actions\">\n                {bodyItems.map((item, bodyIdx) =>\n                  this.renderRailAction(item, headerCount + bodyIdx)\n                )}\n              </div>\n            </div>\n            {footerItems.length ? (\n              <div class=\"panel-tools__rail-footer ds-chrome-row ds-chrome-space--md\">\n                {footerItems.map((item, footerIdx) =>\n                  this.renderRailAction(item, footerStart + footerIdx)\n                )}\n              </div>\n            ) : null}\n          </nav>\n\n          <div\n            class={{\n              'panel-tools__drawer': true,\n              'panel-tools__drawer--visible': showDrawerChrome,\n            }}\n            aria-hidden={showDrawerChrome ? null : 'true'}\n            inert={showDrawerChrome ? undefined : true}\n          >\n            <div class=\"panel-tools__drawer-surface\">\n              {this.presentation !== 'fullscreen' || this.fullscreenHeaderMode === 'shared' ? (\n                <ds-panel-tool-header\n                  class=\"panel-tools__header\"\n                  heading={headerTitle}\n                  showBack={header.showBack ?? false}\n                  backIcon={header.backIcon || 'ChevronLeft'}\n                  backAriaLabel={header.backAriaLabel || 'Back'}\n                  showMenu={false}\n                  ref={element => {\n                    const toolHeader = element as\n                      | (HTMLDsPanelToolHeaderElement & {\n                          actions: PanelToolsHeaderAction[];\n                        })\n                      | undefined;\n                    if (toolHeader) toolHeader.actions = headerActions;\n                  }}\n                  onDsBack={() => {\n                    if (this.activeTool) this.dsHeaderBack.emit({ tool: this.activeTool });\n                  }}\n                />\n              ) : null}\n              <div class=\"panel-tools__body\" hidden={activeFullView}>\n                {toolIds.map(id => {\n                  const active = this.isViewActive(id);\n                  return (\n                    <div\n                      class={{\n                        'panel-tools__view': true,\n                        'panel-tools__view--active': active,\n                      }}\n                      hidden={!active}\n                    >\n                      <slot name={id} />\n                    </div>\n                  );\n                })}\n              </div>\n              <div class=\"panel-tools__full-views\" hidden={!activeFullView}>\n                {toolIds.map(id => (\n                  <div\n                    class={{\n                      'panel-tools__full-view': true,\n                      'panel-tools__full-view--active':\n                        this.isViewActive(id) && this.hasFullView(id),\n                    }}\n                    hidden={!(this.isViewActive(id) && this.hasFullView(id))}\n                  >\n                    <slot name={`${id}-view`} />\n                  </div>\n                ))}\n              </div>\n            </div>\n          </div>\n        </div>\n      </Host>\n    );\n  }\n}\n",
+      "content": "import {\n  Component,\n  Prop,\n  Event,\n  EventEmitter,\n  Element,\n  State,\n  Watch,\n  Method,\n  Listen,\n  h,\n  Host,\n} from '@stencil/core';\nimport type { ChromeTransitionDetail } from '../../shell/chrome-transition';\nimport {\n  PANEL_TOOLS_LABELS,\n  PANEL_TOOLS_SHORTCUTS,\n  type PanelToolsHeaderAction,\n  type PanelToolsHeaderConfig,\n  type PanelToolsHeaders,\n  type PanelToolsItem,\n  type PanelToolsToolId,\n} from './panel-tools-types';\nimport {\n  isPanelToolsToolId,\n  orderPanelToolsItems,\n  panelToolsDrawerAtTerminal,\n  panelToolsDrawerResting,\n  panelToolsDrawerTransitionMs,\n  panelToolsRailPlacement,\n  reconcilePanelToolsAvailability,\n  resolvePanelToolActivation,\n} from './panel-tools-utils';\n\n@Component({\n  tag: 'ds-panel-tools',\n  styleUrl: 'PanelTools.css',\n  scoped: true,\n})\nexport class PanelTools {\n  @Element() el!: HTMLElement;\n\n  /** When false, only the icon rail is shown. */\n  @Prop({ mutable: true, reflect: true }) open: boolean = false;\n\n  /** Drawer presentation or viewport-covering presentation for the active tool. */\n  @Prop({ mutable: true, reflect: true }) presentation: 'drawer' | 'fullscreen' = 'drawer';\n\n  /** Let a fullscreen product supply independent master/detail headers inside its view. */\n  @Prop({ attribute: 'fullscreen-header-mode', reflect: true })\n  fullscreenHeaderMode: 'shared' | 'split' = 'shared';\n\n  /** Active tool view — `search`, `agents`, `messages`, `stacks`, `activity`, or `help`. */\n  @Prop({ mutable: true, attribute: 'active-tool', reflect: true })\n  activeTool: PanelToolsToolId | '' = '';\n\n  /**\n   * Rail items rendered in the right column.\n   * Set via JS property: `el.items = [...]`. Replace the array reference to update.\n   */\n  @Prop() items: PanelToolsItem[] = [];\n\n  @Prop() toolsLabel: string = 'Tools';\n  @Prop() toolShortcutsLabel: string = 'Tool shortcuts';\n\n  /** Active header state per tool. Replace the object when title, depth, or actions change. */\n  @Prop() headers: PanelToolsHeaders = {};\n\n  /**\n   * Optional localStorage key for the last active tool. The drawer always starts\n   * closed; only the tool identity is restored for continuity within this browser.\n   */\n  @Prop({ attribute: 'storage-key' }) storageKey: string = '';\n\n  /** Emitted when a rail button is toggled. Detail = { id, selected }. */\n  @Event({ bubbles: true, composed: true }) dsToolChange!: EventEmitter<{\n    id: PanelToolsToolId;\n    selected: boolean;\n  }>;\n\n  /** Emitted when fullscreen changes, including Escape-initiated exits. */\n  @Event({ bubbles: true, composed: true }) dsPresentationChange!: EventEmitter<{\n    presentation: 'drawer' | 'fullscreen';\n  }>;\n\n  /** Requests navigation to the active tool's parent view. */\n  @Event({ bubbles: true, composed: true }) dsHeaderBack!: EventEmitter<{\n    tool: PanelToolsToolId;\n  }>;\n\n  /** Requests one application-owned action from the active tool header. */\n  @Event({ bubbles: true, composed: true }) dsHeaderAction!: EventEmitter<{\n    tool: PanelToolsToolId;\n    id: string;\n  }>;\n\n  /** Bubbling lifecycle — `ds-bar-nav` defers overflow checks during drawer motion. */\n  @Event({ bubbles: true, composed: true })\n  dsChromeTransitionStart!: EventEmitter<ChromeTransitionDetail>;\n\n  @Event({ bubbles: true, composed: true })\n  dsChromeTransitionEnd!: EventEmitter<ChromeTransitionDetail>;\n\n  /** Arms open vs close easing for the in-flight width transition. */\n  @State() private motion: 'opening' | 'closing' | 'idle' = 'idle';\n\n  /** Keeps header and slotted content painted until the closing clip transition completes. */\n  @State() private drawerSurfaceRetained = false;\n\n  /** Suppresses width transition until the host has painted its initial open state. */\n  @State() private readyForMotion = false;\n\n  /** Fullscreen presentation changes snap without borrowing drawer width motion. */\n  @State() private presentationMotionSuppressed = false;\n\n  @State() private rovingIndex = 0;\n  @State() private fullViewToolIds: PanelToolsToolId[] = [];\n  @State() private railBodyScrollable = false;\n\n  private motionEnableGeneration = 0;\n  private presentationMotionGeneration = 0;\n  private transitionGeneration = 0;\n  private transitionFallbackTimer: number | null = null;\n  /** Ignores the old transition's terminal event when reversing direction. */\n  private ignoreReplacementTerminal = false;\n  private focusBeforeFullscreen: HTMLElement | null = null;\n  private fullViewObserver: MutationObserver | null = null;\n  private railBodyEl?: HTMLElement;\n  private railBodyObserver?: ResizeObserver;\n\n  private get railItems(): PanelToolsItem[] {\n    return this.items ?? [];\n  }\n\n  private get orderedRailItems(): PanelToolsItem[] {\n    return orderPanelToolsItems(this.railItems);\n  }\n\n  disconnectedCallback() {\n    this.el.removeEventListener('transitionend', this.handleTransitionEnd);\n    this.el.removeEventListener('transitioncancel', this.handleTransitionEnd);\n    this.el.removeEventListener('dsAction', this.handleComposedHeaderAction);\n    this.clearTransitionCompletion();\n    this.motionEnableGeneration += 1;\n    this.fullViewObserver?.disconnect();\n    this.fullViewObserver = null;\n    this.disconnectRailBodyObserver();\n  }\n\n  @Watch('presentation')\n  presentationChanged(next: 'drawer' | 'fullscreen', previous?: 'drawer' | 'fullscreen') {\n    if (next === previous) return;\n    // Framework property bindings can update slotted master/detail content in\n    // the same render that requests fullscreen. Reflect the host selector\n    // immediately so that content cannot paint once in the drawer geometry\n    // while Stencil waits to commit its next render.\n    if (this.el.getAttribute('presentation') !== next) {\n      this.el.setAttribute('presentation', next);\n    }\n    const presentationGeneration = ++this.presentationMotionGeneration;\n    this.presentationMotionSuppressed = true;\n    requestAnimationFrame(() => {\n      requestAnimationFrame(() => {\n        if (presentationGeneration !== this.presentationMotionGeneration) return;\n        this.presentationMotionSuppressed = false;\n      });\n    });\n    if (next === 'fullscreen') {\n      this.focusBeforeFullscreen =\n        document.activeElement instanceof HTMLElement ? document.activeElement : null;\n      this.open = true;\n    } else if (previous === 'fullscreen') {\n      const focusBeforeFullscreen = this.focusBeforeFullscreen;\n      const fallbackActionId = this.activeHeader().actions?.[0]?.id;\n      requestAnimationFrame(async () => {\n        if (focusBeforeFullscreen?.isConnected) {\n          focusBeforeFullscreen.focus({ preventScroll: true });\n        }\n        const focusRestored = focusBeforeFullscreen\n          ? document.activeElement === focusBeforeFullscreen ||\n            focusBeforeFullscreen.contains(document.activeElement)\n          : false;\n        if (!focusRestored && fallbackActionId) await this.focusHeaderAction(fallbackActionId);\n        this.focusBeforeFullscreen = null;\n      });\n    }\n    this.dsPresentationChange.emit({ presentation: next });\n  }\n\n  @Listen('keydown', { target: 'window', capture: true })\n  handleFullscreenEscape(event: KeyboardEvent) {\n    if (this.presentation !== 'fullscreen' || event.key !== 'Escape') return;\n    event.preventDefault();\n    event.stopPropagation();\n    this.presentation = 'drawer';\n  }\n\n  private deferMotionEnable() {\n    if (this.readyForMotion) return;\n    const generation = ++this.motionEnableGeneration;\n    requestAnimationFrame(() => {\n      if (generation !== this.motionEnableGeneration) return;\n      requestAnimationFrame(() => {\n        if (generation !== this.motionEnableGeneration) return;\n        this.readyForMotion = true;\n      });\n    });\n  }\n\n  connectedCallback() {\n    this.el.addEventListener('transitionend', this.handleTransitionEnd);\n    this.el.addEventListener('transitioncancel', this.handleTransitionEnd);\n    this.el.addEventListener('dsAction', this.handleComposedHeaderAction);\n  }\n\n  private handleComposedHeaderAction = (event: Event) => {\n    const detail = (event as CustomEvent<{ id?: string }>).detail;\n    if (!this.activeTool || !detail?.id) return;\n    event.stopPropagation();\n    this.dsHeaderAction.emit({ tool: this.activeTool, id: detail.id });\n  };\n\n  componentWillLoad() {\n    this.restoreLastActiveTool();\n    this.drawerSurfaceRetained = this.open;\n  }\n\n  @Watch('open')\n  openChanged(isOpen: boolean, wasOpen?: boolean) {\n    if (isOpen) this.drawerSurfaceRetained = true;\n    if (this.readyForMotion && wasOpen !== undefined && wasOpen !== isOpen) {\n      this.startDrawerTransition(isOpen ? 'opening' : 'closing');\n    } else if (!isOpen) {\n      this.drawerSurfaceRetained = false;\n    }\n    this.deferMotionEnable();\n  }\n\n  @Watch('activeTool')\n  activeToolChanged() {\n    this.persistLastActiveTool();\n    this.deferMotionEnable();\n  }\n\n  @Watch('storageKey')\n  storageKeyChanged() {\n    this.restoreLastActiveTool();\n  }\n\n  componentDidLoad() {\n    this.deferMotionEnable();\n    this.connectRailBodyObserver();\n    this.updateRailBodyScrollable();\n    this.syncFullViewTools();\n    this.fullViewObserver = new MutationObserver(() => this.syncFullViewTools());\n    this.fullViewObserver.observe(this.el, {\n      childList: true,\n      attributes: true,\n      attributeFilter: ['slot'],\n    });\n  }\n\n  componentDidRender() {\n    this.updateRailBodyScrollable();\n  }\n\n  private connectRailBodyObserver() {\n    this.disconnectRailBodyObserver();\n    if (!this.railBodyEl || typeof ResizeObserver === 'undefined') return;\n    this.railBodyObserver = new ResizeObserver(() => this.updateRailBodyScrollable());\n    this.railBodyObserver.observe(this.railBodyEl);\n  }\n\n  private disconnectRailBodyObserver() {\n    this.railBodyObserver?.disconnect();\n    this.railBodyObserver = undefined;\n  }\n\n  private updateRailBodyScrollable() {\n    const next = Boolean(\n      this.railBodyEl && this.railBodyEl.scrollHeight > this.railBodyEl.clientHeight + 1\n    );\n    if (next !== this.railBodyScrollable) this.railBodyScrollable = next;\n  }\n\n  @Watch('items')\n  itemsChanged() {\n    this.rovingIndex = 0;\n    this.reconcileActiveTool();\n    this.deferMotionEnable();\n  }\n\n  private restoreLastActiveTool() {\n    if (!this.storageKey || this.activeTool) return;\n    try {\n      const stored = localStorage.getItem(this.storageKey);\n      if (isPanelToolsToolId(stored)) this.activeTool = stored;\n    } catch {\n      /* localStorage unavailable */\n    }\n  }\n\n  private persistLastActiveTool() {\n    if (!this.storageKey || !this.activeTool) return;\n    try {\n      localStorage.setItem(this.storageKey, this.activeTool);\n    } catch {\n      /* unavailable */\n    }\n  }\n\n  private clearPersistedTool() {\n    if (!this.storageKey) return;\n    try {\n      localStorage.removeItem(this.storageKey);\n    } catch {\n      /* unavailable */\n    }\n  }\n\n  private reconcileActiveTool() {\n    const next = reconcilePanelToolsAvailability(this.railItems, this.open, this.activeTool);\n    if (!next.removedTool) return;\n    this.clearPersistedTool();\n    this.open = next.open;\n    this.activeTool = next.activeTool;\n    this.dsToolChange.emit({ id: next.removedTool, selected: false });\n  }\n\n  private startDrawerTransition(phase: 'opening' | 'closing') {\n    const drawer = this.el.querySelector('.panel-tools__drawer') as HTMLElement | null;\n    if (this.motion !== 'idle') {\n      this.finishDrawerTransition();\n      this.ignoreReplacementTerminal = true;\n    }\n    this.motion = phase;\n    this.dsChromeTransitionStart.emit({ source: 'panel-tools', phase });\n    const generation = ++this.transitionGeneration;\n\n    requestAnimationFrame(() => {\n      requestAnimationFrame(() => {\n        if (generation !== this.transitionGeneration || this.motion !== phase) return;\n        if (!drawer) {\n          this.finishDrawerTransition();\n          return;\n        }\n\n        if (this.drawerTransitionAtTerminal(drawer, phase)) {\n          this.finishDrawerTransition();\n          return;\n        }\n\n        const fallbackMs = panelToolsDrawerTransitionMs(getComputedStyle(drawer));\n        if (fallbackMs <= 0) {\n          this.finishDrawerTransition();\n          return;\n        }\n        this.transitionFallbackTimer = window.setTimeout(() => {\n          this.finishDrawerTransition();\n        }, fallbackMs);\n      });\n    });\n  }\n\n  private handleTransitionEnd = (event: TransitionEvent) => {\n    const drawer = this.el.querySelector('.panel-tools__drawer') as HTMLElement | null;\n    if (event.target !== drawer) return;\n    if (event.propertyName !== 'max-width') return;\n    if (this.ignoreReplacementTerminal) {\n      this.ignoreReplacementTerminal = false;\n      return;\n    }\n    // Changing from the neutral transition recipe to the direction-specific\n    // easing can cancel the transition that the reflected `open` class began.\n    // The replacement transition and its watchdog still own completion; ending\n    // motion here would hide the fixed-width tool surface while it is visible.\n    if (event.type === 'transitioncancel') return;\n    if (drawer && !this.drawerTransitionAtTerminal(drawer, this.motion)) return;\n    this.finishDrawerTransition();\n  };\n\n  private drawerTransitionAtTerminal(\n    drawer: HTMLElement,\n    phase: 'opening' | 'closing' | 'idle'\n  ): boolean {\n    const width = drawer.getBoundingClientRect().width;\n    const surface = drawer.querySelector('.panel-tools__drawer-surface') as HTMLElement | null;\n    const targetWidth = surface?.getBoundingClientRect().width ?? 0;\n    return panelToolsDrawerAtTerminal(width, targetWidth, phase);\n  }\n\n  private finishDrawerTransition() {\n    const completedPhase = this.motion;\n    const wasTransitioning = completedPhase !== 'idle';\n    this.clearTransitionCompletion();\n    if (!wasTransitioning) return;\n    this.ignoreReplacementTerminal = false;\n    this.motion = 'idle';\n    if (completedPhase === 'closing' && !this.open) {\n      this.drawerSurfaceRetained = false;\n    }\n    this.dsChromeTransitionEnd.emit({ source: 'panel-tools' });\n  }\n\n  private clearTransitionCompletion() {\n    this.transitionGeneration += 1;\n    if (this.transitionFallbackTimer !== null) {\n      window.clearTimeout(this.transitionFallbackTimer);\n      this.transitionFallbackTimer = null;\n    }\n  }\n\n  /** Rail selection follows `open` immediately — independent of the slide animation. */\n  private isRailSelected(id: PanelToolsToolId): boolean {\n    return this.open && this.activeTool === id;\n  }\n\n  /** Drawer body stays mounted while the clip frame animates closed. */\n  private isDrawerPresent(): boolean {\n    return this.open || this.drawerSurfaceRetained;\n  }\n\n  private isViewActive(id: PanelToolsToolId): boolean {\n    return this.isDrawerPresent() && this.activeTool === id;\n  }\n\n  private hasFullView(id: PanelToolsToolId): boolean {\n    return this.fullViewToolIds.includes(id);\n  }\n\n  private syncFullViewTools() {\n    const ids = this.orderedRailItems.map(item => item.id);\n    const next = ids.filter(id => Boolean(this.el.querySelector(`[slot=\"${id}-view\"]`)));\n    if (next.join('|') !== this.fullViewToolIds.join('|')) this.fullViewToolIds = next;\n  }\n\n  private headerLabel(): string {\n    if (!this.isDrawerPresent() || !this.activeTool) return '';\n    const item = this.railItems.find(candidate => candidate.id === this.activeTool);\n    return (\n      item?.label ??\n      PANEL_TOOLS_LABELS[this.activeTool as keyof typeof PANEL_TOOLS_LABELS] ??\n      this.activeTool\n    );\n  }\n\n  private resolvedHeaders(): PanelToolsHeaders {\n    return this.headers ?? {};\n  }\n\n  private activeHeader(): PanelToolsHeaderConfig {\n    if (!this.activeTool) return {};\n    return this.resolvedHeaders()[this.activeTool] ?? {};\n  }\n\n  private handleToolChange = (id: PanelToolsToolId) => {\n    const next = resolvePanelToolActivation(this.open, this.activeTool, id);\n    this.open = next.open;\n    this.activeTool = next.activeTool;\n    this.dsToolChange.emit({ id, selected: next.selected });\n  };\n\n  /** Toggle any rail tool open/closed — shell shortcuts K/A/S/M/N call this. */\n  @Method()\n  async activateTool(id: PanelToolsToolId) {\n    const item = this.railItems.find(entry => entry.id === id);\n    if (!item || item.isInactive) return;\n    this.handleToolChange(id);\n  }\n\n  /** Close the tools drawer when open — used by shell keyboard shortcuts. */\n  @Method()\n  async closeDrawer() {\n    if (!this.open) return;\n    const id = this.activeTool;\n    this.open = false;\n    if (id) {\n      this.dsToolChange.emit({ id, selected: false });\n    }\n  }\n\n  /** Focus an active tool-header action by its application-owned id. */\n  @Method()\n  async focusHeaderAction(id: string) {\n    const action = this.el.querySelector(`[data-header-action-id=\"${CSS.escape(id)}\"]`) as\n      | (HTMLElement & { setFocus?: () => Promise<void> })\n      | null;\n    await action?.setFocus?.();\n  }\n\n  private focusRailAt(index: number) {\n    const items = this.orderedRailItems;\n    if (!items.length) return;\n    const bounded = Math.max(0, Math.min(index, items.length - 1));\n    if (bounded === this.rovingIndex) return;\n    this.rovingIndex = bounded;\n    const actions = Array.from(\n      this.el.querySelectorAll<HTMLElement>('.panel-tools__rail-action .button-icon')\n    );\n    actions[bounded]?.focus({ preventScroll: true });\n  }\n\n  private handleRailKeyDown = (e: KeyboardEvent, index: number) => {\n    const items = this.orderedRailItems;\n    if (!items.length) return;\n\n    if (e.key === 'Enter' || e.key === ' ') {\n      e.preventDefault();\n      this.handleToolChange(items[index].id);\n      return;\n    }\n\n    if (e.key === 'ArrowDown') {\n      if (index >= items.length - 1) return;\n      e.preventDefault();\n      this.focusRailAt(index + 1);\n      return;\n    }\n\n    if (e.key === 'ArrowUp') {\n      if (index <= 0) return;\n      e.preventDefault();\n      this.focusRailAt(index - 1);\n    }\n  };\n\n  private renderRailAction(item: PanelToolsItem, index: number) {\n    const label =\n      item.ariaLabel ??\n      item.label ??\n      PANEL_TOOLS_LABELS[item.id as keyof typeof PANEL_TOOLS_LABELS] ??\n      item.id;\n    return (\n      <ds-tooltip\n        key={item.id}\n        label={label}\n        shortcutKey={\n          item.shortcutKey ??\n          PANEL_TOOLS_SHORTCUTS[item.id as keyof typeof PANEL_TOOLS_SHORTCUTS]\n        }\n        side=\"left\"\n        size=\"sm\"\n      >\n        <ds-button-unfilled\n          variant=\"icon\"\n          class=\"panel-tools__rail-action\"\n          icon={item.icon}\n          isActive={this.isRailSelected(item.id)}\n          activeFill={false}\n          hasBorder={false}\n          pressScale={false}\n          dot={item.dot ?? false}\n          isInactive={item.isInactive}\n          focusTabIndex={index === this.rovingIndex ? 0 : -1}\n          aria-label={label}\n          pressed={this.isRailSelected(item.id)}\n          onFocusin={() => {\n            this.rovingIndex = index;\n          }}\n          onKeyDown={(e: KeyboardEvent) => this.handleRailKeyDown(e, index)}\n          onDsClick={() => this.handleToolChange(item.id)}\n        />\n      </ds-tooltip>\n    );\n  }\n\n  render() {\n    const headerLabel = this.headerLabel();\n    const header = this.activeHeader();\n    const headerTitle = header.title?.trim() || headerLabel;\n    const headerActions = header.actions ?? [];\n    const orderedRailItems = this.orderedRailItems;\n    const headerItems = orderedRailItems.filter(\n      item => panelToolsRailPlacement(item) === 'header'\n    );\n    const bodyItems = orderedRailItems.filter(\n      item => panelToolsRailPlacement(item) === 'body'\n    );\n    const footerItems = orderedRailItems.filter(\n      item => panelToolsRailPlacement(item) === 'footer'\n    );\n    const headerCount = headerItems.length;\n    const footerStart = headerCount + bodyItems.length;\n    const showDrawerChrome = this.isDrawerPresent();\n    const drawerResting = panelToolsDrawerResting(this.open, this.motion);\n    const activeFullView = Boolean(\n      showDrawerChrome && this.activeTool && this.hasFullView(this.activeTool)\n    );\n    const toolIds = orderedRailItems.map(item => item.id);\n\n    return (\n      <Host\n        class={{\n          'panel-tools': true,\n          'panel-tools--open': this.open,\n          'panel-tools--ready': this.readyForMotion,\n          'panel-tools--motion-opening': this.motion === 'opening',\n          'panel-tools--motion-closing': this.motion === 'closing',\n          'panel-tools--drawer-resting': drawerResting,\n          'panel-tools--fullscreen': this.presentation === 'fullscreen',\n          'panel-tools--presentation-snap': this.presentationMotionSuppressed,\n        }}\n        role={this.presentation === 'fullscreen' ? 'dialog' : 'complementary'}\n        aria-modal={this.presentation === 'fullscreen' ? 'true' : undefined}\n        aria-label={this.toolsLabel}\n      >\n        <div class=\"panel-tools__layout\">\n          <nav class=\"panel-tools__rail\" aria-label={this.toolShortcutsLabel}>\n            {headerItems.length ? (\n              <div class=\"panel-tools__rail-header ds-chrome-row ds-chrome-space--md\">\n                {headerItems.map((item, index) => this.renderRailAction(item, index))}\n              </div>\n            ) : null}\n            <div\n              class={{\n                'panel-tools__rail-body': true,\n                'ds-chrome-column': true,\n                'ds-chrome-space--md': true,\n                'ds-scrollbar-hidden': true,\n                'ds-focus-ring': this.railBodyScrollable,\n              }}\n              ref={element => {\n                const next = (element as HTMLElement) ?? undefined;\n                if (next === this.railBodyEl) return;\n                this.railBodyEl = next;\n                this.connectRailBodyObserver();\n              }}\n              role={this.railBodyScrollable ? 'region' : undefined}\n              aria-label={this.railBodyScrollable ? this.toolShortcutsLabel : undefined}\n              tabIndex={this.railBodyScrollable ? 0 : undefined}\n            >\n              <div class=\"panel-tools__rail-actions\">\n                {bodyItems.map((item, bodyIdx) =>\n                  this.renderRailAction(item, headerCount + bodyIdx)\n                )}\n              </div>\n            </div>\n            {footerItems.length ? (\n              <div class=\"panel-tools__rail-footer ds-chrome-row ds-chrome-space--md\">\n                {footerItems.map((item, footerIdx) =>\n                  this.renderRailAction(item, footerStart + footerIdx)\n                )}\n              </div>\n            ) : null}\n          </nav>\n\n          <div\n            class={{\n              'panel-tools__drawer': true,\n              'panel-tools__drawer--visible': showDrawerChrome,\n            }}\n            aria-hidden={showDrawerChrome ? null : 'true'}\n            inert={showDrawerChrome ? undefined : true}\n          >\n            <div class=\"panel-tools__drawer-surface\">\n              {this.presentation !== 'fullscreen' || this.fullscreenHeaderMode === 'shared' ? (\n                <ds-panel-tool-header\n                  class=\"panel-tools__header\"\n                  heading={headerTitle}\n                  showBack={header.showBack ?? false}\n                  backIcon={header.backIcon || 'ChevronLeft'}\n                  backAriaLabel={header.backAriaLabel || 'Back'}\n                  showMenu={false}\n                  ref={element => {\n                    const toolHeader = element as\n                      | (HTMLDsPanelToolHeaderElement & {\n                          actions: PanelToolsHeaderAction[];\n                        })\n                      | undefined;\n                    if (toolHeader) toolHeader.actions = headerActions;\n                  }}\n                  onDsBack={() => {\n                    if (this.activeTool) this.dsHeaderBack.emit({ tool: this.activeTool });\n                  }}\n                />\n              ) : null}\n              <div class=\"panel-tools__body\" hidden={activeFullView}>\n                {toolIds.map(id => {\n                  const active = this.isViewActive(id);\n                  return (\n                    <div\n                      class={{\n                        'panel-tools__view': true,\n                        'panel-tools__view--active': active,\n                      }}\n                      hidden={!active}\n                    >\n                      <slot name={id} />\n                    </div>\n                  );\n                })}\n              </div>\n              <div class=\"panel-tools__full-views\" hidden={!activeFullView}>\n                {toolIds.map(id => (\n                  <div\n                    class={{\n                      'panel-tools__full-view': true,\n                      'panel-tools__full-view--active':\n                        this.isViewActive(id) && this.hasFullView(id),\n                    }}\n                    hidden={!(this.isViewActive(id) && this.hasFullView(id))}\n                  >\n                    <slot name={`${id}-view`} />\n                  </div>\n                ))}\n              </div>\n            </div>\n          </div>\n        </div>\n      </Host>\n    );\n  }\n}\n",
       "type": "registry:ui"
     },
     {

package/dist/mcp-data/registry/radio.json

@@ -345,7 +345,7 @@
       "complexPropertyNote": "Assign these non-primitive values as JavaScript properties: options.",
       "peerDependencies": {
         "required": [
-          "@ds-mo/tokens ^5.1.0",
+          "@ds-mo/tokens ^5.1.1",
           "@ds-mo/icons ^6.4.0"
         ],
         "frameworks": "Custom Elements; React 18/19 wrappers; Angular 19-22 standalone adapters."

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

@@ -12,7 +12,7 @@
     "themeSetup": "Set data-theme=\"dark\" on <html> for dark mode. Light is default.",
     "peerDependencies": {
       "required": [
-        "@ds-mo/tokens ^5.1.0",
+        "@ds-mo/tokens ^5.1.1",
         "@ds-mo/icons ^6.4.0"
       ],
       "optional": [],
@@ -657,6 +657,160 @@
         "text"
       ]
     },
+    {
+      "name": "banner",
+      "title": "Banner",
+      "description": "Persistent in-flow application banner with semantic color intent, explicit announcement urgency, horizontal actions, and controlled dismissal motion.",
+      "type": "registry:ui",
+      "meta": {
+        "library": "@ds-mo/ui",
+        "distribution": "npm",
+        "storybook": "https://zainadeel.github.io/compomo/?path=/story/banner",
+        "source": "src/wc/components/Banner/Banner.tsx",
+        "intentStatus": "complete",
+        "intent": {
+          "audience": "general",
+          "status": "stable",
+          "summary": "Persistent in-flow application banner with semantic color intent, explicit announcement urgency, horizontal actions, and controlled dismissal motion.",
+          "useWhen": [
+            "A persistent application-wide condition or announcement must remain visible while the user works.",
+            "A shell-level message needs optional actions and dismissal while reflowing the application rather than floating over it.",
+            "Message urgency and color intent must be selected independently."
+          ],
+          "avoidWhen": [
+            "Feedback is transient, queued, promise-driven, or anchored to a control; use Toast.",
+            "The message belongs inside a field, card, or bounded content section; use the future inline banner rather than shrinking the application shell.",
+            "Several global messages must be prioritized or queued; the application must resolve them to one active banner before rendering."
+          ],
+          "alternatives": [
+            {
+              "when": "Feedback is transient or follows a completed action.",
+              "component": "component:ds-toast",
+              "reason": "Toast owns queues, timers, stacking, swipe dismissal, and anchored feedback."
+            },
+            {
+              "when": "A bounded region has no content to show.",
+              "component": "component:ds-empty-state",
+              "reason": "EmptyState explains an empty result without creating global application urgency."
+            }
+          ],
+          "commonlyComposedWith": [
+            "component:ds-shell-app",
+            "component:ds-button-unfilled"
+          ],
+          "patterns": [
+            "pattern:application-shell"
+          ],
+          "accessibility": [
+            "Choose announcement=none for content present at page load, polite for non-urgent dynamic changes, and assertive only when immediate interruption is necessary.",
+            "Visual intent never chooses live-region urgency; a negative banner can be persistent and non-urgent, while a neutral banner can require prompt attention.",
+            "The close control is always available. Localize dismissLabel and keep the banner mounted until dsAfterClose before removing it.",
+            "Slotted actions retain their own accessible names, keyboard behavior, and outcome messaging."
+          ],
+          "states": [
+            "The application owns open. The always-present close control emits dsClose, and the application sets open=false to begin exit motion.",
+            "dsAfterClose fires once after the closing banner is inert, hidden from assistive technology, and no longer occupies layout space.",
+            "The opaque surface slides by its complete block size while occupied-shell space expands with the same short-3 duration. Opening uses the shell tool panel's ease-out curve; dismissal reverses with its ease-in curve, keeping the Banner boundary flush with the shell throughout.",
+            "Heading is optional and description is required. With orientation=horizontal they share one inline copy flow, so description begins after the heading and continuation lines use the complete text width beneath it. With orientation=vertical, description starts on the next line with a 4px gap.",
+            "The actions slot accepts at most two ds-button-unfilled controls. They stay in one horizontal trailing lane, align to the top of the dismiss control when sharing the copy row, and must receive the matching parent-surface background context.",
+            "Intent selects neutral, brand, positive, warning, caution, or negative hue. Contrast independently selects faint, medium, strong, or bold fill.",
+            "Banner has a real bottom boundary, no radius, no elevation, no icon, no timeout, and no internal queue."
+          ],
+          "responsiveBehavior": [
+            "Applications select orientation explicitly. Horizontal keeps copy and actions in one row, with actions top-aligned to dismissal. Vertical puts actions below copy on the 16px text boundary and keeps controls 16px above the bottom boundary.",
+            "When placed in ShellApp's banner slot, the banner spans the complete application above navigation, workspace, and tools.",
+            "ShellApp reserves the mobile top safe area once above the banner and keeps the banner visible while mobile tools or navigation surfaces replace the routed stage."
+          ],
+          "frameworkCaveats": {
+            "customElements": [
+              "Listen for dsClose, set open=false, and wait for dsAfterClose before conditionally removing the element.",
+              "Place at most one ds-banner in ShellApp's banner slot, choose horizontal or vertical orientation for the available shell capacity, and assign no more than two ds-button-unfilled elements slot=actions."
+            ],
+            "react": [
+              "Keep the component mounted while open changes from true to false; remove it in onDsAfterClose when unmounting is required.",
+              "Project no more than two ds-button-unfilled actions and pass each the matching background context."
+            ],
+            "angular": [
+              "Bind open as controlled application state, handle dsClose to update it, and wait for dsAfterClose before removing an ngIf owner.",
+              "Import and project no more than two DsButtonUnfilled actions with slot=actions and their matching background input."
+            ]
+          },
+          "references": [
+            {
+              "label": "Storybook examples",
+              "path": "src/wc/components/Banner/Banner.stories.ts"
+            },
+            {
+              "label": "Rendered behavior coverage",
+              "path": "tests/e2e/banner.spec.ts"
+            },
+            {
+              "label": "Application shell contract",
+              "path": "agent/patterns/application-shell/pattern.agent.json"
+            }
+          ]
+        },
+        "props": {
+          "announcement": {
+            "type": "BannerAnnouncement",
+            "required": false
+          },
+          "contrast": {
+            "type": "BannerContrast",
+            "required": false
+          },
+          "description": {
+            "type": "string",
+            "required": true
+          },
+          "dismissLabel": {
+            "type": "string",
+            "required": false
+          },
+          "heading": {
+            "type": "string",
+            "required": false
+          },
+          "intent": {
+            "type": "BannerIntent",
+            "required": false
+          },
+          "open": {
+            "type": "boolean",
+            "required": false
+          },
+          "orientation": {
+            "type": "BannerOrientation",
+            "required": false
+          }
+        },
+        "events": [
+          {
+            "name": "dsAfterClose",
+            "detail": "void"
+          },
+          {
+            "name": "dsClose",
+            "detail": "MouseEvent"
+          }
+        ],
+        "slots": [],
+        "exports": {
+          "customElement": "ds-banner",
+          "react": "DsBanner",
+          "angular": "DsBanner"
+        }
+      },
+      "dependencies": [
+        "@ds-mo/ui",
+        "@ds-mo/tokens"
+      ],
+      "registryDependencies": [
+        "button-unfilled",
+        "text",
+        "tooltip"
+      ]
+    },
     {
       "name": "bar-nav",
       "title": "BarNav",
@@ -890,7 +1044,7 @@
           "responsiveBehavior": [
             "BarTitle does not observe viewport, shell, scroll, or container state. Its owner selects an explicit variant.",
             "ShellPage is the standard owner for automatic expanded, compact, and constrained selection.",
-            "Compact titles use the shared md control inset so top-level headings align with BarNav and inline Back geometry aligns with PanelToolHeader. Long headings and section labels truncate independently while Back and action controls retain complete hit targets and accessible names.",
+            "Compact titles use the shared compact-header geometry and md control inset so top-level headings align with BarNav and inline Back geometry aligns with PanelToolHeader. Long headings and section labels truncate independently while Back and action controls retain complete hit targets and accessible names.",
             "A never-collapse primary action remains visible in constrained mode; the title and section label yield space first."
           ],
           "frameworkCaveats": {
@@ -1846,7 +2000,7 @@
     {
       "name": "card-overview",
       "title": "CardOverview",
-      "description": "Page-level summary card pairing one headline score with a reporting period, an application-owned period control, and a responsive grid of comparable measures, with an optional elevated scroll-collapse surface and compact 48px presentation.",
+      "description": "Page-level summary with a persistent 48px reporting bar above an equal-track grid of an optional safety score and comparable measures, plus an elevated page-controlled collapse surface.",
       "type": "registry:ui",
       "meta": {
         "library": "@ds-mo/ui",
@@ -1857,7 +2011,7 @@
         "intent": {
           "audience": "general",
           "status": "experimental",
-          "summary": "Page-level summary card pairing one headline score with a reporting period, an application-owned period control, and a responsive grid of comparable measures, with an optional elevated scroll-collapse surface and compact 48px presentation.",
+          "summary": "Page-level summary with a persistent 48px reporting bar above an equal-track grid of an optional safety score and comparable measures, plus an elevated page-controlled collapse surface.",
           "useWhen": [
             "A page opens with one headline figure that the surrounding measures explain.",
             "Every measure is compared against the same period, so one caption describes the comparison for all of them.",
@@ -1889,8 +2043,7 @@
           ],
           "accessibility": [
             "The bar is a labelled region; set overviewLabel to name what is being summarised, such as Safety summary.",
-            "Trend arrows are decorative and hidden from assistive technology, so the formatted change value must read correctly on its own.",
-            "Colour never carries the trend meaning alone; the arrow direction and the value are both present.",
+            "Colour never carries trend meaning alone; the arrow direction and formatted change value are both included in the accessible text.",
             "Measures become selectable only when they are not inactive. Selectable measures form one roving tab stop, so the grid is a single stop and arrow keys move between measures.",
             "Set labelTooltip when a measure's label needs qualifying rather than shortening the label into something ambiguous.",
             "While loading, the region exposes a busy state and renders skeletons whose type metrics match the resolved content."
@@ -1899,20 +2052,21 @@
             "Score and measures are supplied as data; the component owns their type treatment so summary bars stay consistent across pages.",
             "Trend is supplied already resolved as a direction, a formatted value, and a tone. Whether a rise reads well is a product decision, so the component never infers tone from the numbers. Derive it with resolveMetricTrend.",
             "Omit a trend when there is nothing to report; resolveMetricTrend returns null in that case so no zero change is rendered.",
-            "Omit score to render the bar without a headline figure. Set scoreErrorMessage to report that the figure could not be resolved while the measures remain readable.",
+            "Omit score to render a centered Score unavailable cell with a tertiary border and no score fill. Set scoreErrorMessage to replace that copy while the measures remain readable.",
             "Loading replaces the score and the measures with skeletons and does not alter the slotted period control.",
-            "At most six measures are shown. Keep larger collections outside the summary bar rather than turning it into a dense dashboard.",
-            "The period control is slotted rather than owned, because the choice of stepper, select, or date range varies by product surface.",
-            "During a page-controlled scroll collapse, the component preserves its expanded flow height while the elevated visual surface shrinks toward 48px and the full content translates upward inside an internal clip. The elevation remains fitted to the visible surface instead of being clipped with the content.",
-            "compact is exactly 48px high and keeps only the score label, score value, trend, reporting copy, and slotted period control. It omits the score band, measures, and footer."
+            "At most seven measures are shown. Keep larger collections outside the summary bar rather than turning it into a dense dashboard.",
+            "The period and filter controls are slotted rather than owned. Use the period slot when the current range is selectable; otherwise periodLabel supplies fixed current copy in the same md control-frame and label-inset anatomy. Use the filter slot for the application-owned comparison-window control. Slotted Selects use hasBorder false so the 48px bar owns their surrounding boundary.",
+            "A numeric safety score infers fair from 0–50, good from 51–80, and excellent from 81–100. The level can be supplied explicitly when the displayed value is not numeric. The deprecated band field is ignored.",
+            "The safety score is the first grid cell and uses the same track, 8px outer inset, 6px inner padding, dividers, and responsive behavior as metric cells. The display value removes 12px from both block edges of its line box so it does not increase the shared row height. Score remains nonselectable and excluded from metric roving focus.",
+            "During page-controlled scroll collapse, the component preserves its expanded flow height and stationary reporting bar while the metric grid moves and clips beneath it. Elevation remains fitted to the visible surface.",
+            "compact is exactly 48px high and renders only the reporting bar. It omits Score, measures, and footer."
           ],
           "responsiveBehavior": [
-            "The measure grid reflows to fewer columns and finally stacks, driven by the minimum measure width alone. There is no measurement and no horizontal scrolling.",
+            "The measure grid reflows to fewer columns and finally stacks without horizontal scrolling. Even cell totals prefer complete rows; odd totals retain the densest fitting layout and may leave an orphan in the final row.",
             "Every occupied grid track has the same width. When a final row is incomplete, its measures keep the same width as the row above and the unused tracks remain empty.",
             "Set metricMinWidth to change the width a measure may shrink to before the grid drops a column.",
-            "The score block hugs its content and never shrinks, so the headline figure holds its size while the grid absorbs the remaining width.",
-            "Once the card reaches its narrow stacked state, one summary block holds the score label, score, trend, score band, reporting period, and the application-owned period control above the single-column measures.",
-            "In that stacked summary, the score and trend share one line at the start, while the score band is hidden to preserve space. The period control stays at the upper end, while the current period and comparison sit on separate right-aligned lines beside the score.",
+            "The safety score participates in the same equal-width tracks as measures rather than occupying a separate rail.",
+            "The reporting bar owns an exact 8px inset on every edge. Fixed current copy and slotted controls begin at that inset; their labels share md control-frame geometry and truncate before changing the 48px height.",
             "Every measure occupies a full-width row in the stacked state.",
             "Set layout to stacked when the owning page shell enters a responsive mode before the card's own container reaches its narrow threshold.",
             "CardOverview does not observe scroll, choose sticky offsets, or switch its own presentation. The page owner supplies collapse progress, keeps the card sticky at the appropriate shell inset, and swaps to compact at the 48px endpoint.",
@@ -1921,7 +2075,7 @@
           "frameworkCaveats": {
             "customElements": [
               "Assign score and metrics as JavaScript properties; both are objects and cannot be expressed as HTML attributes.",
-              "Place the period control in the filter slot; the component reserves space for it but never renders one.",
+              "Place an optional current-range control in the period slot and the comparison-window control in the filter slot; the component reserves their layout but never computes or renders controls.",
               "When driving scroll collapse, update scrollCollapseProgress from page-owned geometry and swap to a separate compact presentation at the endpoint."
             ],
             "react": [
@@ -1932,7 +2086,7 @@
             "angular": [
               "Bind [score] and [metrics] as properties and read the selected measure from $event.detail on (dsMetricSelect).",
               "Derive each trend with resolveMetricTrend so tone stays an explicit product decision.",
-              "Keep sticky geometry and [scrollCollapseProgress] in the page owner; CardOverview only renders the visual collapse."
+              "Keep date math, sticky geometry, and [scrollCollapseProgress] in the page owner; CardOverview only renders the supplied composition and visual collapse."
             ]
           },
           "references": [
@@ -2007,11 +2161,9 @@
       },
       "dependencies": [
         "@ds-mo/ui",
-        "@ds-mo/tokens",
-        "@ds-mo/icons"
+        "@ds-mo/tokens"
       ],
       "registryDependencies": [
-        "icon",
         "skeleton",
         "text",
         "tooltip"
@@ -3830,7 +3982,7 @@
           ],
           "states": [
             "Every size applies one complete control-density recipe across frame height, inline padding, icon zones, text-container inset, gap, and radius; supporting error content follows the shared 4px field flow.",
-            "The normal field boundary uses the shared secondary inset border. Focus promotes it to the thicker bold-brand inset stroke, while error uses the thicker bold-negative inset stroke without changing geometry.",
+            "The normal field boundary uses the shared secondary inset border. Focus promotes it to the thicker bold-brand inset stroke, while error uses the thicker bold-negative inset stroke without changing geometry. Set hasBorder to false only in chrome that supplies enough surrounding structure; the control then remains borderless at rest, while focused, and while invalid, with semantics and supporting error copy unchanged.",
             "Placeholder text is secondary at rest and quaternary while the editable field is focused because it becomes decorative once typing begins.",
             "Entered values use the parent surface's primary foreground; prefix icons, suffix content, and resting placeholder text use its secondary foreground.",
             "Search fields show a standard borderless CrossCircle icon action only while they contain a value. Clearing emits the empty value and restores focus to the native field.",
@@ -4527,6 +4679,7 @@
           "states": [
             "The component owns clipboard execution and temporary copied feedback while the application supplies the exact copyable text.",
             "Feedback is controlled: the component emits the requested positive, negative, or cleared value while the application owns persistence and consequences.",
+            "Selected feedback changes to the filled thumb icon without adding a persistent selected fill; hover and press feedback remain available.",
             "Copy, positive feedback, and negative feedback retain one stable order."
           ],
           "responsiveBehavior": [
@@ -5308,7 +5461,7 @@
     {
       "name": "modal",
       "title": "Modal",
-      "description": "Dismissible native top-layer dialog for a focused confirmation or short blocking task, with a fixed title-and-close header, composable content, and an optional two-action footer.",
+      "description": "Dismissible native top-layer dialog for a focused confirmation or short blocking task, with a compact title-and-close header, optional supporting description, composable content, and an optional two-action footer.",
       "type": "registry:ui",
       "meta": {
         "library": "@ds-mo/ui",
@@ -5319,7 +5472,7 @@
         "intent": {
           "audience": "general",
           "status": "stable",
-          "summary": "Dismissible native top-layer dialog for a focused confirmation or short blocking task, with a fixed title-and-close header, composable content, and an optional two-action footer.",
+          "summary": "Dismissible native top-layer dialog for a focused confirmation or short blocking task, with a compact title-and-close header, optional supporting description, composable content, and an optional two-action footer.",
           "useWhen": [
             "The user must confirm or cancel one focused decision before returning to the underlying interface.",
             "A short blocking task or compact form needs dialog semantics, focus containment, and explicit completion actions.",
@@ -5357,6 +5510,7 @@
           ],
           "accessibility": [
             "Provide a concise visible heading; the component uses it as the dialog's accessible name.",
+            "When concise supporting context belongs in the header, provide description; it stays below the title and is included in the dialog's accessible description.",
             "Give the primary explanatory copy a stable id and pass it through aria-describedby so assistive technology receives the decision context.",
             "Opening the native modal dialog moves focus to the header Close action, whose visible tooltip matches its accessible name, traps Tab navigation inside the top layer, and makes outside content inert.",
             "Close, Escape, and backdrop activation emit dsClose with close-button, escape, or backdrop reason before beginning dismissal; use the component only when every dismissal path is safe.",
@@ -5369,12 +5523,13 @@
             "The owner opens the modal through the open property and responds to the typed dsClose detail for application state synchronization or dismissal analytics.",
             "The component mutates open to false for Close, Escape, and backdrop dismissal while retaining its rendered surface through exit motion.",
             "The default slot owns task content; the named footer slot is optional and is hidden when no actions are assigned.",
+            "The optional header description remains stacked beneath the title with the shared compact-header rhythm; longer task content belongs in the default slot.",
             "Primary actions use a bold filled button with semantic intent. Secondary and cancel actions use bordered label-only unfilled buttons.",
             "The owner performs save, delete, cancel, and other product consequences before or while closing the modal."
           ],
           "responsiveBehavior": [
             "Choose the smallest sm, md, or lg width that fits the focused task; the top-layer dialog clamps to the viewport with token-based outer space.",
-            "Content scrolls independently when needed while the 64px header and optional 64px footer remain fixed.",
+            "Content scrolls independently when needed while the header and optional 64px footer remain fixed. The title-only header uses the shared 48px compact geometry and grows when its optional description wraps.",
             "Avoid layouts whose minimum content width exceeds the narrow viewport clamp.",
             "The native top layer escapes transformed ancestors, clipping containers, and application stacking contexts without moving slotted content."
           ],
@@ -5419,6 +5574,10 @@
             "type": "string",
             "required": false
           },
+          "description": {
+            "type": "string",
+            "required": false
+          },
           "heading": {
             "type": "string",
             "required": true
@@ -5857,7 +6016,7 @@
           ],
           "states": [
             "The title remains left aligned whether the header has no actions, Back, one trailing action, or several trailing actions.",
-            "Leading and trailing control zones never shrink; only the title consumes and truncates within the remaining width, with a fixed 4px gap between zones.",
+            "Leading and trailing control zones never shrink; only the title consumes and truncates within the remaining width. The header uses the shared 8px compact-header zone gap, while adjacent trailing actions retain their 4px control gap.",
             "Header chrome text is not selectable; actions remain keyboard focusable and interactive.",
             "Adjacent trailing actions keep the shared 4px control gap in drawer and fullscreen presentations.",
             "When fullscreen and overflow actions appear together, author fullscreen before overflow so Ellipses remains the rightmost action.",
@@ -6147,6 +6306,7 @@
             "Provide localized accessible labels for the rail, shortcut group, and every rendered tool.",
             "Use the canonical default recipe when the product needs Search first and Help last; custom recipes must preserve a deliberate keyboard and visual order.",
             "Keep focus on the selected rail action when opening a drawer and allow normal Tab navigation into its content.",
+            "When the shortcut rail overflows, its labeled body becomes a keyboard-focusable scroll region without changing the rail action order.",
             "Do not trigger global shortcuts while focus is in an editable control.",
             "Use notification dots only as supplemental unread or new-content status and never as the sole status indication.",
             "Explain temporarily inactive tools through an accessible label or adjacent product guidance; omit unauthorized tools entirely."
@@ -6607,7 +6767,7 @@
             "An empty filtered list composes the message-only body variant of EmptyState. Keep the default neutral no-results message unless localized product guidance makes the outcome clearer.",
             "Enable searchable for more than roughly 20 options, user-managed listings, large domains such as addresses, or sets users cannot efficiently scan. Local matching includes option labels, subtext, and section headings; the owner resolves remote data before assigning options.",
             "Validation timing belongs to the form owner and may be immediate or deferred until blur or submit; the Select exposes validity and error presentation without imposing that policy.",
-            "The error trigger uses a 1.5px bold-negative inset stroke so invalid state remains distinguishable from the normal 1px border without changing control geometry.",
+            "The error trigger uses a 1.5px bold-negative inset stroke so invalid state remains distinguishable from the normal 1px border without changing control geometry. Set hasBorder to false for chrome where the trigger must remain borderless at rest, when selected or focused, and when invalid; error semantics and supporting copy remain available.",
             "An initially empty option set is not an expected Select use case. The no-results state describes a search with no matches, not a source with no choices.",
             "Use options for a flat list or sections for grouped choices; when sections are present they take precedence.",
             "The background prop describes the actual parent surface and uses the same surface set as ButtonUnfilled."
@@ -6835,6 +6995,7 @@
             "component:ds-mobile-header",
             "component:ds-mobile-bar-nav",
             "component:ds-shell-page",
+            "component:ds-banner",
             "component:ds-swatch-picker"
           ],
           "patterns": [
@@ -6844,6 +7005,7 @@
           "accessibility": [
             "Supply primary destinations through navigation and secondary route sections through pageChrome so managed ShellApp preserves their correct semantics.",
             "Ensure the default content region contains the page's single main landmark.",
+            "Keep the shell-owned routed-content scroller keyboard-focusable while its page landmark retains content semantics.",
             "Keep the managed desktop/tablet and mobile presentations available without conditionally recreating routed or tool content.",
             "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.",
@@ -6856,6 +7018,7 @@
             "ShellApp renders the lower-level desktop, tablet, and mobile chrome, coordinates layout, gradient alignment, transitions, shortcuts, global surfaces, Inbox state, focus restoration, and mobile-stage visibility.",
             "The application router owns authorization, current URLs, history, and route execution; ShellApp forwards navigation and page intent events without routing.",
             "The application supplies each routed content owner and tool view once. ShellApp changes visibility, inert state, and presentation without recreating those nodes.",
+            "The optional banner slot accepts one application-owned ds-banner above the complete shell row. The application owns its open state, orientation for the current shell capacity, action consequences, dismissal persistence, and resolution when several messages compete.",
             "Use composition=slotted only for advanced application architectures that intentionally own all lower-level chrome wiring.",
             "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.",
@@ -6871,6 +7034,7 @@
             "On tablet, ShellApp keeps PanelNav permanently collapsed and prevents user expansion without overwriting the desktop preference.",
             "On mobile, ShellApp hides and inerts desktop chrome, uses a solid primary stage, and composes MobileHeader, MobileSheetNav, ShellTools, and the persistent MobileBarNav around the same application-owned content.",
             "When the application enables viewport-fit=cover, ShellApp reserves the shared top safe-area inset once for the complete mobile stage; nested routed, sheet, and tool headers must not add a second top inset.",
+            "A slotted Banner remains below the top safe-area inset and above routed, navigation, fullscreen-tool, and mobile global-surface presentations.",
             "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 bottom bar remains visible at all route and tool depths in the foundation release."

package/dist/mcp-data/registry/scroll-overlay.json

@@ -156,7 +156,7 @@
       },
       "peerDependencies": {
         "required": [
-          "@ds-mo/tokens ^5.1.0",
+          "@ds-mo/tokens ^5.1.1",
           "@ds-mo/icons ^6.4.0"
         ],
         "frameworks": "Custom Elements; React 18/19 wrappers; Angular 19-22 standalone adapters."