@ds-mo/ui 12.2.0 → 12.4.0

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

@@ -2,7 +2,7 @@
   "$schema": "https://ui.shadcn.com/schema/registry-item.json",
   "name": "shell-page",
   "title": "ShellPage",
-  "description": "The standard routed-page boundary inside ShellApp, owning sticky BarTitle or BarWorkflow placement, container-aware BarTitle variants, stable scroll compaction, and optional page-content inset without creating a nested scroll container.",
+  "description": "The standard routed-page boundary inside ShellApp, owning sticky BarTitle or BarWorkflow placement, application-supplied BarTitle capacity, stable scroll compaction, and optional page-content inset without creating a nested scroll container.",
   "type": "registry:ui",
   "meta": {
     "library": "@ds-mo/ui",
@@ -13,10 +13,10 @@
     "intent": {
       "audience": "general",
       "status": "stable",
-      "summary": "The standard routed-page boundary inside ShellApp, owning sticky BarTitle or BarWorkflow placement, container-aware BarTitle variants, stable scroll compaction, and optional page-content inset without creating a nested scroll container.",
+      "summary": "The standard routed-page boundary inside ShellApp, owning sticky BarTitle or BarWorkflow placement, application-supplied BarTitle capacity, stable scroll compaction, and optional page-content inset without creating a nested scroll container.",
       "useWhen": [
         "Rendering a standard routed page inside ShellApp's default content region.",
-        "BarTitle should expand at a roomy page top, compact after scroll, or use constrained action layout when the page column narrows.",
+        "BarTitle should expand at a roomy page top, compact after scroll, or use constrained action layout when the application shell reports reduced capacity.",
         "BarWorkflow needs sticky page-level placement while remaining compact.",
         "Pages need consistent content gutters with an explicit full-bleed option."
       ],
@@ -53,16 +53,18 @@
         "Responsive variant changes preserve the same heading, controls, accessible names, and keyboard focus targets."
       ],
       "states": [
-        "headerPresentation=auto selects expanded, compact, or constrained from ShellPage's own inline capacity and scroll position.",
+        "headerCapacity=roomy, compact, or constrained is supplied before paint by the owning application shell and describes the page-header space available after viewport and shell-chrome policy are applied.",
+        "headerPresentation=auto selects the matching header variant from headerCapacity and scroll position.",
         "expanded, compact, and constrained are explicit overrides for exceptional layouts and deterministic examples.",
         "contentInset=default supplies standard page gutters; none permits maps, canvases, and other full-bleed content.",
         "The required header slot accepts one BarTitle or BarWorkflow. The default slot owns router output and all page product content."
       ],
       "responsiveBehavior": [
-        "ShellPage observes its own rendered width instead of viewport media queries or ShellApp desktop/tablet modes.",
-        "Roomy pages expand at the top and compact after scroll; medium-capacity pages start compact; narrow pages use the constrained header variant.",
-        "A newly navigated header resolves current page capacity before it is revealed, so persistent tool or navigation chrome cannot flash the expanded presentation first.",
-        "Token-based capacity bands use hysteresis so opening tools or resizing navigation cannot oscillate near a boundary.",
+        "The owning application shell resolves viewport and persistent-chrome state into the explicit headerCapacity prop; ShellPage never guesses the cause of reduced width from its own rendered size.",
+        "Roomy capacity expands at the top and compacts after scroll; compact capacity stays compact; constrained capacity uses the constrained action layout.",
+        "A ShellPage-managed BarTitle remains concealed until headerCapacity is available and its rendered variant matches the resolved presentation, preventing a default-variant flash during route activation.",
+        "Update headerCapacity synchronously with shell layout state so opening tools or crossing application breakpoints cannot briefly render the wrong presentation.",
+        "On roomy pages, the expanded header scrolls upward until its title and action row reaches the compact row position, then snaps variants without moving that shared visual anchor.",
         "Scroll compaction preserves the expanded page flow offset so content never jumps beneath the sticky header.",
         "ShellPage relies on ShellApp's content scroller and never introduces nested scrolling.",
         "BarWorkflow remains compact and is not assigned BarTitle's capacity or scroll variants."
@@ -107,6 +109,14 @@
           "mutable": false,
           "description": "Standard page gutters, or no inset for full-bleed page content."
         },
+        "headerCapacity": {
+          "type": "ShellPageCapacity",
+          "resolvedType": "\"compact\" | \"constrained\" | \"roomy\" | undefined",
+          "attribute": "header-capacity",
+          "required": false,
+          "mutable": false,
+          "description": "Available page-header capacity supplied by the owning application shell."
+        },
         "headerPresentation": {
           "type": "ShellPageHeaderPresentation",
           "resolvedType": "\"auto\" | \"compact\" | \"constrained\" | \"expanded\"",
@@ -114,7 +124,7 @@
           "default": "'auto'",
           "required": false,
           "mutable": false,
-          "description": "Automatic container/scroll behavior, or an explicit header variant override."
+          "description": "Automatic capacity/scroll behavior, or an explicit header variant override."
         }
       },
       "events": [],
@@ -131,6 +141,14 @@
         "mutable": false,
         "description": "Standard page gutters, or no inset for full-bleed page content."
       },
+      "headerCapacity": {
+        "type": "ShellPageCapacity",
+        "resolvedType": "\"compact\" | \"constrained\" | \"roomy\" | undefined",
+        "attribute": "header-capacity",
+        "required": false,
+        "mutable": false,
+        "description": "Available page-header capacity supplied by the owning application shell."
+      },
       "headerPresentation": {
         "type": "ShellPageHeaderPresentation",
         "resolvedType": "\"auto\" | \"compact\" | \"constrained\" | \"expanded\"",
@@ -138,7 +156,7 @@
         "default": "'auto'",
         "required": false,
         "mutable": false,
-        "description": "Automatic container/scroll behavior, or an explicit header variant override."
+        "description": "Automatic capacity/scroll behavior, or an explicit header variant override."
       }
     },
     "events": [],
@@ -181,17 +199,17 @@
   "files": [
     {
       "path": "src/wc/components/ShellPage/ShellPage.css",
-      "content": ":host {\n  display: block;\n  position: relative;\n  min-width: 0;\n  min-height: 100%;\n  box-sizing: border-box;\n  background: var(--color-background-primary);\n}\n\n.shell-page__scroll-sentinel {\n  position: absolute;\n  inset-block-start: 0;\n  inset-inline-start: 0;\n  width: var(--dimension-stroke-width-012);\n  height: var(--dimension-stroke-width-012);\n  pointer-events: none;\n}\n\n.shell-page__sticky-header {\n  position: sticky;\n  inset-block-start: 0;\n  z-index: var(--dimension-z-index-raised);\n  min-width: 0;\n  background: var(--color-background-primary);\n  overflow: visible;\n  overflow-anchor: none;\n}\n\n.shell-page__sticky-header ::slotted(ds-bar-title),\n.shell-page__sticky-header ::slotted(ds-bar-workflow) {\n  display: block;\n  min-width: 0;\n}\n\n.shell-page__flow-spacer {\n  height: var(--ds-shell-page-flow-spacer, 0);\n  background: var(--color-background-primary);\n}\n\n.shell-page__content {\n  min-width: 0;\n  box-sizing: border-box;\n  background: var(--color-background-primary);\n}\n\n:host(.shell-page-host--inset-default) .shell-page__content {\n  padding: var(--dimension-space-400) var(--dimension-space-400) var(--dimension-space-800);\n}\n\n:host(.shell-page-host--inset-none) .shell-page__content {\n  padding: 0;\n}\n",
+      "content": ":host {\n  display: block;\n  position: relative;\n  min-width: 0;\n  min-height: 100%;\n  box-sizing: border-box;\n  background: var(--color-background-primary);\n}\n\n.shell-page__scroll-sentinel {\n  position: absolute;\n  inset-block-start: var(--ds-shell-page-header-travel, 0);\n  inset-inline-start: 0;\n  width: var(--dimension-stroke-width-012);\n  height: var(--dimension-stroke-width-012);\n  pointer-events: none;\n}\n\n.shell-page__sticky-header {\n  position: sticky;\n  inset-block-start: var(--ds-shell-page-sticky-offset, 0);\n  z-index: var(--dimension-z-index-raised);\n  min-width: 0;\n  background: var(--color-background-primary);\n  overflow: visible;\n  overflow-anchor: none;\n}\n\n.shell-page__sticky-header ::slotted(ds-bar-title),\n.shell-page__sticky-header ::slotted(ds-bar-workflow) {\n  display: block;\n  min-width: 0;\n}\n\n.shell-page__flow-spacer {\n  height: var(--ds-shell-page-flow-spacer, 0);\n  background: var(--color-background-primary);\n}\n\n.shell-page__content {\n  min-width: 0;\n  box-sizing: border-box;\n  background: var(--color-background-primary);\n}\n\n:host(.shell-page-host--inset-default) .shell-page__content {\n  padding: var(--dimension-space-400) var(--dimension-space-400) var(--dimension-space-800);\n}\n\n:host(.shell-page-host--inset-none) .shell-page__content {\n  padding: 0;\n}\n",
       "type": "registry:ui"
     },
     {
       "path": "src/wc/components/ShellPage/ShellPage.tsx",
-      "content": "import { Component, Element, h, Host, Prop, State } from '@stencil/core';\nimport { createRafCoalescer } from '../../shell/chrome-transition';\nimport { resolveCssLengthPx } from '../../utils/resolve-css-length-px';\nimport type { BarTitleVariant } from '../BarTitle/bar-title-types';\nimport { resolveShellPageCapacity, resolveShellPageHeaderVariant } from './shell-page-responsive';\nimport type {\n  ShellPageCapacity,\n  ShellPageContentInset,\n  ShellPageHeaderPresentation,\n} from './shell-page-types';\n\ntype BarTitleElement = HTMLElement & { variant: BarTitleVariant };\n\n@Component({\n  tag: 'ds-shell-page',\n  styleUrl: 'ShellPage.css',\n  scoped: true,\n})\nexport class ShellPage {\n  private static readonly MAX_HEADER_REVEAL_FRAMES = 12;\n\n  @Element() el!: HTMLElement;\n\n  /** Automatic container/scroll behavior, or an explicit header variant override. */\n  @Prop() headerPresentation: ShellPageHeaderPresentation = 'auto';\n\n  /** Standard page gutters, or no inset for full-bleed page content. */\n  @Prop() contentInset: ShellPageContentInset = 'default';\n\n  @State() private capacity: ShellPageCapacity | null = null;\n  @State() private pageTopVisible = true;\n\n  private sentinelEl: HTMLElement | null = null;\n  private spacerEl: HTMLElement | null = null;\n  private headerEl: BarTitleElement | null = null;\n  private expandedHeaderHeight = 0;\n  private resizeObserver: ResizeObserver | null = null;\n  private headerResizeObserver: ResizeObserver | null = null;\n  private headerRevealFrame: number | null = null;\n  private scrollRoot: HTMLElement | Window | null = null;\n  private readonly layoutCoalescer = createRafCoalescer(() => this.syncCapacity());\n\n  componentDidLoad() {\n    // Resolve the already-laid-out page width before adopting a slotted header.\n    // Waiting for the first ResizeObserver/RAF lets BarTitle paint its default\n    // expanded variant for one frame when persistent shell chrome narrows a\n    // newly navigated page.\n    this.syncCapacity();\n    this.observeHeader(this.findHeader());\n    this.connectObservers();\n    this.connectScrollRoot();\n    this.layoutCoalescer.schedule();\n  }\n\n  componentDidRender() {\n    this.syncHeaderVariant();\n  }\n\n  disconnectedCallback() {\n    this.resizeObserver?.disconnect();\n    this.resizeObserver = null;\n    this.headerResizeObserver?.disconnect();\n    this.headerResizeObserver = null;\n    this.cancelHeaderReveal();\n    this.scrollRoot?.removeEventListener('scroll', this.handleScroll);\n    this.scrollRoot = null;\n    this.layoutCoalescer.cancel();\n  }\n\n  private get effectiveVariant(): BarTitleVariant {\n    return resolveShellPageHeaderVariant(\n      this.headerPresentation,\n      this.capacity ?? 'roomy',\n      this.pageTopVisible\n    );\n  }\n\n  private get isScrollCompacted(): boolean {\n    return this.headerPresentation === 'auto' && this.capacity === 'roomy' && !this.pageTopVisible;\n  }\n\n  private connectObservers() {\n    if (typeof ResizeObserver !== 'undefined') {\n      this.resizeObserver = new ResizeObserver(() => this.layoutCoalescer.schedule());\n      this.resizeObserver.observe(this.el);\n    }\n  }\n\n  private composedParent(element: Element): Element | null {\n    return (element as HTMLElement).assignedSlot?.parentElement ?? element.parentElement;\n  }\n\n  private findScrollRoot(): HTMLElement | Window {\n    let ancestor = this.composedParent(this.el);\n    while (ancestor && ancestor !== document.documentElement) {\n      const overflow = getComputedStyle(ancestor).overflowY;\n      if (overflow === 'auto' || overflow === 'scroll') return ancestor as HTMLElement;\n      ancestor = this.composedParent(ancestor);\n    }\n    return window;\n  }\n\n  private connectScrollRoot() {\n    this.scrollRoot?.removeEventListener('scroll', this.handleScroll);\n    this.scrollRoot = this.findScrollRoot();\n    this.scrollRoot.addEventListener('scroll', this.handleScroll, { passive: true });\n    this.handleScroll();\n  }\n\n  private handleScroll = () => {\n    if (!this.sentinelEl || !this.scrollRoot) return;\n    const rootTop =\n      this.scrollRoot === window ? 0 : (this.scrollRoot as HTMLElement).getBoundingClientRect().top;\n    this.pageTopVisible = this.sentinelEl.getBoundingClientRect().top >= rootTop;\n  };\n\n  private findHeader(): BarTitleElement | null {\n    return this.el.querySelector<BarTitleElement>('ds-bar-title');\n  }\n\n  private syncCapacity() {\n    const inlineSize = this.el.getBoundingClientRect().width;\n    if (inlineSize <= 0) return;\n\n    const compactAt = resolveCssLengthPx('--dimension-panel-width-2xl', 0);\n    const constrainedAt = resolveCssLengthPx('--dimension-panel-width-lg', 0);\n    const hysteresis = resolveCssLengthPx('--dimension-space-100', 0);\n    if (compactAt <= 0 || constrainedAt <= 0) return;\n\n    const next = resolveShellPageCapacity({\n      inlineSize,\n      compactAt,\n      constrainedAt,\n      hysteresis,\n      previous: this.capacity,\n    });\n    if (next !== this.capacity) this.capacity = next;\n    else this.syncHeaderVariant();\n  }\n\n  private get compactHeaderHeight(): number {\n    return resolveCssLengthPx('--dimension-size-600', 0);\n  }\n\n  private setSpacerHeight(height: number) {\n    if (!this.spacerEl) return;\n    this.spacerEl.style.setProperty('--ds-shell-page-flow-spacer', `${Math.max(0, height)}px`);\n  }\n\n  private variantClass(variant: BarTitleVariant): string {\n    return `bar-title-host--${variant}`;\n  }\n\n  private cancelHeaderReveal() {\n    if (this.headerRevealFrame !== null) cancelAnimationFrame(this.headerRevealFrame);\n    this.headerRevealFrame = null;\n    this.headerEl?.removeAttribute('data-shell-page-syncing');\n  }\n\n  private revealHeaderWhenSynced(header: BarTitleElement, variant: BarTitleVariant) {\n    // Stencil re-renders within a frame or two of a prop change, but this cap\n    // guarantees the header can never stay hidden indefinitely if that\n    // assumption ever breaks.\n    let framesRemaining = ShellPage.MAX_HEADER_REVEAL_FRAMES;\n    const reveal = () => {\n      if (this.headerEl !== header) {\n        header.removeAttribute('data-shell-page-syncing');\n        return;\n      }\n      framesRemaining -= 1;\n      if (framesRemaining <= 0 || header.classList.contains(this.variantClass(variant))) {\n        header.removeAttribute('data-shell-page-syncing');\n        this.headerRevealFrame = null;\n        return;\n      }\n      this.headerRevealFrame = requestAnimationFrame(reveal);\n    };\n    this.headerRevealFrame = requestAnimationFrame(reveal);\n  }\n\n  private syncHeaderVariant(concealUntilSynced = false) {\n    const header = this.headerEl;\n    if (!header) return;\n\n    const next = this.effectiveVariant;\n    if (header.variant === 'expanded') {\n      this.expandedHeaderHeight = header.getBoundingClientRect().height;\n    }\n\n    this.setSpacerHeight(\n      this.isScrollCompacted ? this.expandedHeaderHeight - this.compactHeaderHeight : 0\n    );\n\n    const renderedVariantIsStale = !header.classList.contains(this.variantClass(next));\n    if (concealUntilSynced && renderedVariantIsStale) {\n      header.setAttribute('data-shell-page-syncing', '');\n    }\n    if (header.variant !== next) header.variant = next;\n    if (concealUntilSynced && renderedVariantIsStale) {\n      this.revealHeaderWhenSynced(header, next);\n    }\n  }\n\n  private observeHeader(header: BarTitleElement | null) {\n    this.cancelHeaderReveal();\n    this.headerResizeObserver?.disconnect();\n    this.headerResizeObserver = null;\n    this.headerEl = header;\n    this.expandedHeaderHeight = 0;\n    this.setSpacerHeight(0);\n\n    if (!header) return;\n    if (typeof ResizeObserver !== 'undefined') {\n      this.headerResizeObserver = new ResizeObserver(() => {\n        if (header.variant === 'expanded') {\n          this.expandedHeaderHeight = header.getBoundingClientRect().height;\n        }\n      });\n      this.headerResizeObserver.observe(header);\n    }\n    this.syncHeaderVariant(true);\n  }\n\n  private handleHeaderSlotChange = (event: Event) => {\n    const slot = event.target as HTMLSlotElement;\n    const header = slot\n      .assignedElements({ flatten: true })\n      .find(element => element.tagName.toLowerCase() === 'ds-bar-title');\n    this.observeHeader((header as BarTitleElement | undefined) ?? null);\n  };\n\n  render() {\n    return (\n      <Host\n        role=\"main\"\n        class={{\n          'shell-page-host--inset-default': this.contentInset === 'default',\n          'shell-page-host--inset-none': this.contentInset === 'none',\n          [`shell-page-host--header-${this.effectiveVariant}`]: true,\n        }}\n      >\n        <div\n          ref={el => {\n            this.sentinelEl = el ?? null;\n          }}\n          class=\"shell-page__scroll-sentinel\"\n          aria-hidden=\"true\"\n        />\n        <div class=\"shell-page__sticky-header\">\n          <slot name=\"header\" onSlotchange={this.handleHeaderSlotChange} />\n        </div>\n        <div\n          ref={el => {\n            this.spacerEl = el ?? null;\n          }}\n          class=\"shell-page__flow-spacer\"\n          aria-hidden=\"true\"\n        />\n        <div class=\"shell-page__content\">\n          <slot />\n        </div>\n      </Host>\n    );\n  }\n}\n",
+      "content": "import { Component, Element, h, Host, Prop, State, Watch } from '@stencil/core';\nimport { resolveCssLengthPx } from '../../utils/resolve-css-length-px';\nimport type { BarTitleVariant } from '../BarTitle/bar-title-types';\nimport { resolveShellPageHeaderVariant } from './shell-page-responsive';\nimport type {\n  ShellPageCapacity,\n  ShellPageContentInset,\n  ShellPageHeaderPresentation,\n} from './shell-page-types';\n\ntype BarTitleElement = HTMLElement & { variant: BarTitleVariant };\n\n@Component({\n  tag: 'ds-shell-page',\n  styleUrl: 'ShellPage.css',\n  scoped: true,\n})\nexport class ShellPage {\n  private static readonly MAX_HEADER_REVEAL_FRAMES = 12;\n  private static readonly MAX_HEADER_GEOMETRY_FRAMES = 12;\n\n  @Element() el!: HTMLElement;\n\n  /** Automatic capacity/scroll behavior, or an explicit header variant override. */\n  @Prop() headerPresentation: ShellPageHeaderPresentation = 'auto';\n\n  /** Available page-header capacity supplied by the owning application shell. */\n  @Prop() headerCapacity?: ShellPageCapacity;\n\n  /** Standard page gutters, or no inset for full-bleed page content. */\n  @Prop() contentInset: ShellPageContentInset = 'default';\n\n  @State() private pageTopVisible = true;\n\n  private sentinelEl: HTMLElement | null = null;\n  private spacerEl: HTMLElement | null = null;\n  private stickyHeaderEl: HTMLElement | null = null;\n  private headerEl: BarTitleElement | null = null;\n  private expandedHeaderHeight = 0;\n  private headerTravel = 0;\n  private expandedGeometryFrozen = false;\n  private headerResizeObserver: ResizeObserver | null = null;\n  private headerMutationObserver: MutationObserver | null = null;\n  private headerRevealFrame: number | null = null;\n  private headerGeometryFrame: number | null = null;\n  private scrollRoot: HTMLElement | Window | null = null;\n\n  @Watch('headerCapacity')\n  @Watch('headerPresentation')\n  handleHeaderContractChange() {\n    this.syncHeaderVariant(true);\n  }\n\n  componentDidLoad() {\n    this.observeHeader(this.findHeader());\n    this.connectScrollRoot();\n  }\n\n  componentDidRender() {\n    this.syncHeaderVariant();\n  }\n\n  disconnectedCallback() {\n    this.headerResizeObserver?.disconnect();\n    this.headerResizeObserver = null;\n    this.headerMutationObserver?.disconnect();\n    this.headerMutationObserver = null;\n    this.cancelHeaderReveal();\n    this.cancelHeaderGeometrySync();\n    this.scrollRoot?.removeEventListener('scroll', this.handleScroll);\n    this.scrollRoot = null;\n  }\n\n  private get effectiveVariant(): BarTitleVariant {\n    return resolveShellPageHeaderVariant(\n      this.headerPresentation,\n      this.headerCapacity ?? 'roomy',\n      this.pageTopVisible\n    );\n  }\n\n  private get headerContractResolved(): boolean {\n    return this.headerPresentation !== 'auto' || this.headerCapacity !== undefined;\n  }\n\n  private get isScrollCompacted(): boolean {\n    return (\n      this.headerPresentation === 'auto' && this.headerCapacity === 'roomy' && !this.pageTopVisible\n    );\n  }\n\n  private composedParent(element: Element): Element | null {\n    return (element as HTMLElement).assignedSlot?.parentElement ?? element.parentElement;\n  }\n\n  private findScrollRoot(): HTMLElement | Window {\n    let ancestor = this.composedParent(this.el);\n    while (ancestor && ancestor !== document.documentElement) {\n      const overflow = getComputedStyle(ancestor).overflowY;\n      if (overflow === 'auto' || overflow === 'scroll' || overflow === 'overlay') {\n        return ancestor as HTMLElement;\n      }\n      ancestor = this.composedParent(ancestor);\n    }\n    return window;\n  }\n\n  private connectScrollRoot() {\n    const next = this.findScrollRoot();\n    if (next === this.scrollRoot) return;\n    this.scrollRoot?.removeEventListener('scroll', this.handleScroll);\n    this.scrollRoot = next;\n    this.scrollRoot.addEventListener('scroll', this.handleScroll, { passive: true });\n    this.handleScroll();\n  }\n\n  private handleScroll = () => {\n    if (!this.sentinelEl || !this.scrollRoot) return;\n    const rootTop =\n      this.scrollRoot === window ? 0 : (this.scrollRoot as HTMLElement).getBoundingClientRect().top;\n    const nextPageTopVisible = this.sentinelEl.getBoundingClientRect().top >= rootTop;\n    if (\n      !nextPageTopVisible &&\n      this.pageTopVisible &&\n      this.headerEl?.classList.contains(this.variantClass('expanded'))\n    ) {\n      this.captureExpandedHeaderGeometry(this.headerEl);\n      this.expandedGeometryFrozen = true;\n    }\n    if (\n      nextPageTopVisible &&\n      this.expandedGeometryFrozen &&\n      this.el.getBoundingClientRect().top >= rootTop\n    ) {\n      this.expandedGeometryFrozen = false;\n      if (this.headerEl?.classList.contains(this.variantClass('expanded'))) {\n        this.captureExpandedHeaderGeometry(this.headerEl);\n      }\n    }\n    this.pageTopVisible = nextPageTopVisible;\n  };\n\n  private findHeader(): BarTitleElement | null {\n    return this.el.querySelector<BarTitleElement>('ds-bar-title');\n  }\n\n  private get compactHeaderHeight(): number {\n    return resolveCssLengthPx('--dimension-size-600', 0);\n  }\n\n  private setHeaderTravel(distance: number) {\n    const next = Math.max(0, distance);\n    if (Math.abs(next - this.headerTravel) < 0.5) return;\n    this.headerTravel = next;\n    this.el.style.setProperty('--ds-shell-page-header-travel', `${next}px`);\n    this.handleScroll();\n  }\n\n  private measureHeaderTravel(header: BarTitleElement) {\n    const anchor = header.querySelector<HTMLElement>('[data-shell-page-header-anchor]');\n    const compactHeight = this.compactHeaderHeight;\n    if (!anchor || compactHeight <= 0) return;\n\n    const headerRect = header.getBoundingClientRect();\n    const anchorRect = anchor.getBoundingClientRect();\n    if (headerRect.height <= 0 || anchorRect.height <= 0) return;\n\n    const expandedAnchorTop = anchorRect.top - headerRect.top;\n    const compactAnchorTop = Math.max(0, (compactHeight - anchorRect.height) / 2);\n    this.setHeaderTravel(expandedAnchorTop - compactAnchorTop);\n  }\n\n  private captureExpandedHeaderGeometry(header: BarTitleElement) {\n    this.expandedHeaderHeight = header.getBoundingClientRect().height;\n    this.measureHeaderTravel(header);\n  }\n\n  private setSpacerHeight(height: number) {\n    if (!this.spacerEl) return;\n    this.spacerEl.style.setProperty('--ds-shell-page-flow-spacer', `${Math.max(0, height)}px`);\n  }\n\n  private variantClass(variant: BarTitleVariant): string {\n    return `bar-title-host--${variant}`;\n  }\n\n  private setStickyHeaderOffset(renderedVariant: BarTitleVariant) {\n    this.stickyHeaderEl?.style.setProperty(\n      '--ds-shell-page-sticky-offset',\n      renderedVariant === 'expanded' &&\n        this.headerPresentation === 'auto' &&\n        this.headerCapacity === 'roomy'\n        ? `${-this.headerTravel}px`\n        : '0px'\n    );\n  }\n\n  private syncRenderedHeaderGeometry(header: BarTitleElement) {\n    const renderedVariant = this.effectiveVariant;\n    if (!header.classList.contains(this.variantClass(renderedVariant))) return;\n\n    // Update both flow-preservation pieces before reading layout. Otherwise a\n    // reverse compact → expanded render can briefly contain the tall header and\n    // the compact spacer together, giving browser scroll anchoring a transient\n    // height change to compensate.\n    this.setSpacerHeight(\n      this.isScrollCompacted ? this.expandedHeaderHeight - this.compactHeaderHeight : 0\n    );\n    this.setStickyHeaderOffset(renderedVariant);\n\n    if (renderedVariant === 'expanded' && !this.expandedGeometryFrozen) {\n      this.captureExpandedHeaderGeometry(header);\n      this.setStickyHeaderOffset(renderedVariant);\n    }\n  }\n\n  private cancelHeaderGeometrySync() {\n    if (this.headerGeometryFrame !== null) cancelAnimationFrame(this.headerGeometryFrame);\n    this.headerGeometryFrame = null;\n  }\n\n  private scheduleHeaderGeometrySync(header: BarTitleElement) {\n    this.cancelHeaderGeometrySync();\n    let framesRemaining = ShellPage.MAX_HEADER_GEOMETRY_FRAMES;\n    let framesElapsed = 0;\n    const sync = () => {\n      if (this.headerEl !== header) return;\n      framesRemaining -= 1;\n      framesElapsed += 1;\n      // In WebKit a child's componentDidLoad can precede its assignment into\n      // the parent's rendered slot. Revalidate after ShellApp has had a frame\n      // to expose the actual content scroller.\n      this.connectScrollRoot();\n      this.syncRenderedHeaderGeometry(header);\n      const geometryReady =\n        this.effectiveVariant !== 'expanded' ||\n        (this.expandedHeaderHeight > 0 && this.headerTravel > 0);\n      if ((geometryReady && framesElapsed >= 2) || framesRemaining <= 0) {\n        this.headerGeometryFrame = null;\n        return;\n      }\n      this.headerGeometryFrame = requestAnimationFrame(sync);\n    };\n    this.headerGeometryFrame = requestAnimationFrame(sync);\n  }\n\n  private cancelHeaderReveal() {\n    if (this.headerRevealFrame !== null) cancelAnimationFrame(this.headerRevealFrame);\n    this.headerRevealFrame = null;\n    this.headerEl?.removeAttribute('data-shell-page-syncing');\n  }\n\n  private revealHeaderWhenSynced(header: BarTitleElement, variant: BarTitleVariant) {\n    // Stencil normally re-renders within a frame or two of a prop change. Stop\n    // polling at the cap, but fail closed: a stale variant must never paint.\n    let framesRemaining = ShellPage.MAX_HEADER_REVEAL_FRAMES;\n    const reveal = () => {\n      if (this.headerEl !== header) {\n        header.removeAttribute('data-shell-page-syncing');\n        return;\n      }\n      framesRemaining -= 1;\n      if (header.classList.contains(this.variantClass(variant))) {\n        header.removeAttribute('data-shell-page-syncing');\n        this.headerRevealFrame = null;\n        return;\n      }\n      if (framesRemaining <= 0) {\n        this.headerRevealFrame = null;\n        return;\n      }\n      this.headerRevealFrame = requestAnimationFrame(reveal);\n    };\n    this.headerRevealFrame = requestAnimationFrame(reveal);\n  }\n\n  private syncHeaderVariant(concealUntilSynced = false) {\n    const header = this.headerEl;\n    if (!header) return;\n\n    if (!this.headerContractResolved) {\n      this.cancelHeaderReveal();\n      header.setAttribute('data-shell-page-syncing', '');\n      return;\n    }\n\n    const next = this.effectiveVariant;\n    const renderedVariantIsStale = !header.classList.contains(this.variantClass(next));\n    if (!renderedVariantIsStale) this.syncRenderedHeaderGeometry(header);\n    if (concealUntilSynced) {\n      this.cancelHeaderReveal();\n      header.setAttribute('data-shell-page-syncing', '');\n    }\n    if (header.variant !== next) header.variant = next;\n    if (concealUntilSynced) {\n      this.revealHeaderWhenSynced(header, next);\n    }\n  }\n\n  private observeHeader(header: BarTitleElement | null) {\n    this.cancelHeaderReveal();\n    this.cancelHeaderGeometrySync();\n    this.headerResizeObserver?.disconnect();\n    this.headerResizeObserver = null;\n    this.headerMutationObserver?.disconnect();\n    this.headerMutationObserver = null;\n    this.headerEl = header;\n    this.expandedHeaderHeight = 0;\n    this.expandedGeometryFrozen = false;\n    this.setHeaderTravel(0);\n    this.setSpacerHeight(0);\n    this.stickyHeaderEl?.style.setProperty('--ds-shell-page-sticky-offset', '0px');\n\n    if (!header) return;\n    if (header.classList.contains(this.variantClass('expanded'))) {\n      this.captureExpandedHeaderGeometry(header);\n    }\n    if (typeof ResizeObserver !== 'undefined') {\n      this.headerResizeObserver = new ResizeObserver(() => {\n        this.syncRenderedHeaderGeometry(header);\n      });\n      this.headerResizeObserver.observe(header);\n    }\n    if (typeof MutationObserver !== 'undefined') {\n      this.headerMutationObserver = new MutationObserver(() => {\n        this.syncRenderedHeaderGeometry(header);\n      });\n      this.headerMutationObserver.observe(header, {\n        attributes: true,\n        attributeFilter: ['class'],\n      });\n    }\n    this.syncHeaderVariant(true);\n    this.scheduleHeaderGeometrySync(header);\n  }\n\n  private handleHeaderSlotChange = (event: Event) => {\n    const slot = event.target as HTMLSlotElement;\n    const header = slot\n      .assignedElements()\n      .find(element => element.tagName.toLowerCase() === 'ds-bar-title');\n    this.observeHeader((header as BarTitleElement | undefined) ?? null);\n  };\n\n  render() {\n    return (\n      <Host\n        role=\"main\"\n        class={{\n          'shell-page-host--inset-default': this.contentInset === 'default',\n          'shell-page-host--inset-none': this.contentInset === 'none',\n          [`shell-page-host--header-${this.effectiveVariant}`]: true,\n        }}\n      >\n        <div\n          ref={el => {\n            this.sentinelEl = el ?? null;\n          }}\n          class=\"shell-page__scroll-sentinel\"\n          aria-hidden=\"true\"\n        />\n        <div\n          ref={el => {\n            this.stickyHeaderEl = el ?? null;\n          }}\n          class=\"shell-page__sticky-header\"\n        >\n          <slot name=\"header\" onSlotchange={this.handleHeaderSlotChange} />\n        </div>\n        <div\n          ref={el => {\n            this.spacerEl = el ?? null;\n          }}\n          class=\"shell-page__flow-spacer\"\n          aria-hidden=\"true\"\n        />\n        <div class=\"shell-page__content\">\n          <slot />\n        </div>\n      </Host>\n    );\n  }\n}\n",
       "type": "registry:ui"
     },
     {
       "path": "src/wc/components/ShellPage/shell-page-responsive.ts",
-      "content": "import type { ShellPageCapacity, ShellPageHeaderPresentation } from './shell-page-types';\nimport type { BarTitleVariant } from '../BarTitle/bar-title-types';\n\nexport interface ShellPageCapacityOptions {\n  inlineSize: number;\n  compactAt: number;\n  constrainedAt: number;\n  hysteresis: number;\n  previous: ShellPageCapacity | null;\n}\n\nexport function resolveShellPageCapacity({\n  inlineSize,\n  compactAt,\n  constrainedAt,\n  hysteresis,\n  previous,\n}: ShellPageCapacityOptions): ShellPageCapacity {\n  if (previous === null) {\n    if (inlineSize <= constrainedAt) return 'constrained';\n    if (inlineSize <= compactAt) return 'compact';\n    return 'roomy';\n  }\n\n  if (previous === 'constrained') {\n    if (inlineSize <= constrainedAt + hysteresis) return 'constrained';\n    return inlineSize <= compactAt ? 'compact' : 'roomy';\n  }\n\n  if (inlineSize <= constrainedAt) return 'constrained';\n\n  if (previous === 'compact') {\n    return inlineSize <= compactAt + hysteresis ? 'compact' : 'roomy';\n  }\n\n  return inlineSize <= compactAt ? 'compact' : 'roomy';\n}\n\nexport function resolveShellPageHeaderVariant(\n  presentation: ShellPageHeaderPresentation,\n  capacity: ShellPageCapacity,\n  pageTopVisible: boolean\n): BarTitleVariant {\n  if (presentation !== 'auto') return presentation;\n  if (capacity === 'constrained') return 'constrained';\n  if (capacity === 'compact' || !pageTopVisible) return 'compact';\n  return 'expanded';\n}\n",
+      "content": "import type { ShellPageCapacity, ShellPageHeaderPresentation } from './shell-page-types';\nimport type { BarTitleVariant } from '../BarTitle/bar-title-types';\n\nexport function resolveShellPageHeaderVariant(\n  presentation: ShellPageHeaderPresentation,\n  capacity: ShellPageCapacity,\n  pageTopVisible: boolean\n): BarTitleVariant {\n  if (presentation !== 'auto') return presentation;\n  if (capacity === 'constrained') return 'constrained';\n  if (capacity === 'compact' || !pageTopVisible) return 'compact';\n  return 'expanded';\n}\n",
       "type": "registry:ui"
     },
     {

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

@@ -0,0 +1,450 @@
+{
+  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+  "name": "shell-tools",
+  "title": "ShellTools",
+  "description": "Responsive persistent host for shell tools, adapting PanelTools rail and drawer chrome to full-stage mobile Search, Agents, and Inbox surfaces.",
+  "type": "registry:ui",
+  "meta": {
+    "library": "@ds-mo/ui",
+    "distribution": "npm",
+    "storybook": "https://zainadeel.github.io/compomo/?path=/story/shell-tools",
+    "source": "src/wc/components/ShellTools/ShellTools.tsx",
+    "intentStatus": "complete",
+    "intent": {
+      "audience": "specialized",
+      "status": "experimental",
+      "summary": "Responsive persistent host for shell tools, adapting PanelTools rail and drawer chrome to full-stage mobile Search, Agents, and Inbox surfaces.",
+      "useWhen": [
+        "A ShellApp must preserve the same Search, Agents, Messages, Stacks, Activity, and Help product owners across desktop, tablet, and mobile."
+      ],
+      "avoidWhen": [
+        "The tools exist only in desktop and tablet chrome; PanelTools remains supported for that case.",
+        "The content is a routed primary application area."
+      ],
+      "alternatives": [
+        {
+          "when": "Only legacy rail and drawer behavior is required.",
+          "component": "component:ds-panel-tools",
+          "reason": "PanelTools remains the backward-compatible desktop and tablet primitive."
+        }
+      ],
+      "commonlyComposedWith": [
+        "component:ds-shell-app",
+        "component:ds-panel-tool-header",
+        "component:ds-shell-mobile-bar"
+      ],
+      "patterns": [
+        "pattern:application-shell"
+      ],
+      "accessibility": [
+        "Only the active mobile tool view participates in focus or the accessibility tree.",
+        "Header Back and application-owned header actions preserve the PanelTools event contract.",
+        "Inbox uses TabGroup semantics for Messages, Stacks, and Activity."
+      ],
+      "states": [
+        "The application owns open and activeTool and replaces headers when tool depth changes.",
+        "Messages, Stacks, and Activity map to one mobile Inbox destination while retaining the actual active tool id.",
+        "Switching responsive mode must not recreate application-owned slotted product elements."
+      ],
+      "responsiveBehavior": [
+        "Desktop and tablet compose PanelTools-compatible rail and drawer chrome.",
+        "Mobile renders the active tool across the shell stage and groups available inbox tools in a segmented control."
+      ],
+      "frameworkCaveats": {
+        "customElements": [
+          "Assign items and headers as JavaScript properties and place each persistent owner in its named *-view slot."
+        ],
+        "react": [
+          "Keep stable keyed product owner elements in the generated wrapper's named slots."
+        ],
+        "angular": [
+          "Bind structured items and headers as properties and keep each tool owner mounted under a named *-view slot."
+        ]
+      },
+      "references": [
+        {
+          "label": "Storybook",
+          "path": "src/wc/components/ShellTools/ShellTools.stories.ts"
+        },
+        {
+          "label": "PanelTools contract",
+          "path": "src/wc/components/PanelTools/PanelTools.agent.json"
+        }
+      ]
+    },
+    "api": {
+      "props": {
+        "activeTool": {
+          "type": "PanelToolsToolId | ''",
+          "resolvedType": "\"\" | \"activity\" | \"agents\" | \"help\" | \"messages\" | \"search\" | \"stacks\"",
+          "attribute": "active-tool",
+          "default": "''",
+          "required": false,
+          "mutable": true
+        },
+        "fullscreenHeaderMode": {
+          "type": "'shared' | 'split'",
+          "resolvedType": "\"shared\" | \"split\"",
+          "attribute": "fullscreen-header-mode",
+          "default": "'shared'",
+          "required": false,
+          "mutable": false
+        },
+        "headers": {
+          "type": "PanelToolsHeaders",
+          "resolvedType": "\"activity\" | \"agents\" | \"help\" | \"messages\" | \"search\" | \"stacks\" | PanelToolsHeaderConfig",
+          "default": "{}",
+          "required": false,
+          "mutable": false
+        },
+        "headersJson": {
+          "type": "string",
+          "resolvedType": "string",
+          "attribute": "headers-json",
+          "default": "''",
+          "required": false,
+          "mutable": false
+        },
+        "inboxLabel": {
+          "type": "string",
+          "resolvedType": "string",
+          "attribute": "inbox-label",
+          "default": "'Inbox'",
+          "required": false,
+          "mutable": false
+        },
+        "inboxNavigationLabel": {
+          "type": "string",
+          "resolvedType": "string",
+          "attribute": "inbox-navigation-label",
+          "default": "'Inbox sections'",
+          "required": false,
+          "mutable": false
+        },
+        "items": {
+          "type": "PanelToolsItem[]",
+          "resolvedType": "PanelToolsItem[]",
+          "default": "[]",
+          "required": false,
+          "mutable": false
+        },
+        "itemsJson": {
+          "type": "string",
+          "resolvedType": "string",
+          "attribute": "items-json",
+          "default": "''",
+          "required": false,
+          "mutable": false
+        },
+        "open": {
+          "type": "boolean",
+          "resolvedType": "boolean",
+          "attribute": "open",
+          "default": "false",
+          "required": false,
+          "mutable": true
+        },
+        "presentation": {
+          "type": "'drawer' | 'fullscreen'",
+          "resolvedType": "\"drawer\" | \"fullscreen\"",
+          "attribute": "presentation",
+          "default": "'drawer'",
+          "required": false,
+          "mutable": true
+        },
+        "responsiveMode": {
+          "type": "ShellResponsiveMode",
+          "resolvedType": "\"desktop\" | \"mobile\" | \"tablet\"",
+          "attribute": "responsive-mode",
+          "default": "'desktop'",
+          "required": false,
+          "mutable": false,
+          "description": "Resolved by ShellApp; mobile uses a full-stage tool presentation."
+        },
+        "storageKey": {
+          "type": "string",
+          "resolvedType": "string",
+          "attribute": "storage-key",
+          "default": "''",
+          "required": false,
+          "mutable": false
+        },
+        "toolShortcutsLabel": {
+          "type": "string",
+          "resolvedType": "string",
+          "attribute": "tool-shortcuts-label",
+          "default": "'Tool shortcuts'",
+          "required": false,
+          "mutable": false
+        },
+        "toolsLabel": {
+          "type": "string",
+          "resolvedType": "string",
+          "attribute": "tools-label",
+          "default": "'Tools'",
+          "required": false,
+          "mutable": false
+        }
+      },
+      "events": [
+        {
+          "name": "dsHeaderAction",
+          "detail": "{\n    tool: PanelToolsToolId;\n    id: string;\n  }",
+          "bubbles": true,
+          "cancelable": true,
+          "composed": true
+        },
+        {
+          "name": "dsHeaderBack",
+          "detail": "{\n    tool: PanelToolsToolId;\n  }",
+          "bubbles": true,
+          "cancelable": true,
+          "composed": true
+        },
+        {
+          "name": "dsPresentationChange",
+          "detail": "{\n    presentation: 'drawer' | 'fullscreen';\n  }",
+          "bubbles": true,
+          "cancelable": true,
+          "composed": true
+        },
+        {
+          "name": "dsToolChange",
+          "detail": "{\n    id: PanelToolsToolId;\n    selected: boolean;\n  }",
+          "bubbles": true,
+          "cancelable": true,
+          "composed": true
+        }
+      ],
+      "methods": [
+        {
+          "name": "activateTool",
+          "signature": "activateTool(id: PanelToolsToolId) => Promise<void>",
+          "description": "Match PanelTools' imperative activation contract in every responsive mode."
+        },
+        {
+          "name": "closeDrawer",
+          "signature": "closeDrawer() => Promise<void>",
+          "description": "Close the active global tool surface."
+        },
+        {
+          "name": "focusHeaderAction",
+          "signature": "focusHeaderAction(id: string) => Promise<void>",
+          "description": "Focus an application-owned action in the visible shared tool header."
+        }
+      ],
+      "slots": []
+    },
+    "props": {
+      "activeTool": {
+        "type": "PanelToolsToolId | ''",
+        "resolvedType": "\"\" | \"activity\" | \"agents\" | \"help\" | \"messages\" | \"search\" | \"stacks\"",
+        "attribute": "active-tool",
+        "default": "''",
+        "required": false,
+        "mutable": true
+      },
+      "fullscreenHeaderMode": {
+        "type": "'shared' | 'split'",
+        "resolvedType": "\"shared\" | \"split\"",
+        "attribute": "fullscreen-header-mode",
+        "default": "'shared'",
+        "required": false,
+        "mutable": false
+      },
+      "headers": {
+        "type": "PanelToolsHeaders",
+        "resolvedType": "\"activity\" | \"agents\" | \"help\" | \"messages\" | \"search\" | \"stacks\" | PanelToolsHeaderConfig",
+        "default": "{}",
+        "required": false,
+        "mutable": false
+      },
+      "headersJson": {
+        "type": "string",
+        "resolvedType": "string",
+        "attribute": "headers-json",
+        "default": "''",
+        "required": false,
+        "mutable": false
+      },
+      "inboxLabel": {
+        "type": "string",
+        "resolvedType": "string",
+        "attribute": "inbox-label",
+        "default": "'Inbox'",
+        "required": false,
+        "mutable": false
+      },
+      "inboxNavigationLabel": {
+        "type": "string",
+        "resolvedType": "string",
+        "attribute": "inbox-navigation-label",
+        "default": "'Inbox sections'",
+        "required": false,
+        "mutable": false
+      },
+      "items": {
+        "type": "PanelToolsItem[]",
+        "resolvedType": "PanelToolsItem[]",
+        "default": "[]",
+        "required": false,
+        "mutable": false
+      },
+      "itemsJson": {
+        "type": "string",
+        "resolvedType": "string",
+        "attribute": "items-json",
+        "default": "''",
+        "required": false,
+        "mutable": false
+      },
+      "open": {
+        "type": "boolean",
+        "resolvedType": "boolean",
+        "attribute": "open",
+        "default": "false",
+        "required": false,
+        "mutable": true
+      },
+      "presentation": {
+        "type": "'drawer' | 'fullscreen'",
+        "resolvedType": "\"drawer\" | \"fullscreen\"",
+        "attribute": "presentation",
+        "default": "'drawer'",
+        "required": false,
+        "mutable": true
+      },
+      "responsiveMode": {
+        "type": "ShellResponsiveMode",
+        "resolvedType": "\"desktop\" | \"mobile\" | \"tablet\"",
+        "attribute": "responsive-mode",
+        "default": "'desktop'",
+        "required": false,
+        "mutable": false,
+        "description": "Resolved by ShellApp; mobile uses a full-stage tool presentation."
+      },
+      "storageKey": {
+        "type": "string",
+        "resolvedType": "string",
+        "attribute": "storage-key",
+        "default": "''",
+        "required": false,
+        "mutable": false
+      },
+      "toolShortcutsLabel": {
+        "type": "string",
+        "resolvedType": "string",
+        "attribute": "tool-shortcuts-label",
+        "default": "'Tool shortcuts'",
+        "required": false,
+        "mutable": false
+      },
+      "toolsLabel": {
+        "type": "string",
+        "resolvedType": "string",
+        "attribute": "tools-label",
+        "default": "'Tools'",
+        "required": false,
+        "mutable": false
+      }
+    },
+    "events": [
+      {
+        "name": "dsHeaderAction",
+        "detail": "{\n    tool: PanelToolsToolId;\n    id: string;\n  }",
+        "bubbles": true,
+        "cancelable": true,
+        "composed": true
+      },
+      {
+        "name": "dsHeaderBack",
+        "detail": "{\n    tool: PanelToolsToolId;\n  }",
+        "bubbles": true,
+        "cancelable": true,
+        "composed": true
+      },
+      {
+        "name": "dsPresentationChange",
+        "detail": "{\n    presentation: 'drawer' | 'fullscreen';\n  }",
+        "bubbles": true,
+        "cancelable": true,
+        "composed": true
+      },
+      {
+        "name": "dsToolChange",
+        "detail": "{\n    id: PanelToolsToolId;\n    selected: boolean;\n  }",
+        "bubbles": true,
+        "cancelable": true,
+        "composed": true
+      }
+    ],
+    "methods": [
+      {
+        "name": "activateTool",
+        "signature": "activateTool(id: PanelToolsToolId) => Promise<void>",
+        "description": "Match PanelTools' imperative activation contract in every responsive mode."
+      },
+      {
+        "name": "closeDrawer",
+        "signature": "closeDrawer() => Promise<void>",
+        "description": "Close the active global tool surface."
+      },
+      {
+        "name": "focusHeaderAction",
+        "signature": "focusHeaderAction(id: string) => Promise<void>",
+        "description": "Focus an application-owned action in the visible shared tool header."
+      }
+    ],
+    "slots": [],
+    "exports": {
+      "customElement": "ds-shell-tools",
+      "react": "DsShellTools",
+      "angular": "DsShellTools"
+    },
+    "consumption": {
+      "install": "npm install @ds-mo/ui @ds-mo/tokens @ds-mo/icons",
+      "cssSetup": "import '@ds-mo/tokens';\nimport '@ds-mo/tokens/reset';\nimport '@ds-mo/tokens/globals';",
+      "customElements": {
+        "import": "import '@ds-mo/ui/dist/components/ds-shell-tools.js';",
+        "example": "<ds-shell-tools></ds-shell-tools>"
+      },
+      "react": {
+        "import": "import { DsShellTools } from '@ds-mo/ui/react';",
+        "example": "<DsShellTools />"
+      },
+      "angular": {
+        "import": "import { DsShellTools } from '@ds-mo/ui/angular/ds-shell-tools';",
+        "example": "<ds-shell-tools></ds-shell-tools>"
+      },
+      "complexPropertyNote": "Assign these non-primitive values as JavaScript properties: headers, items.",
+      "peerDependencies": {
+        "required": [
+          "@ds-mo/tokens ^3.1.1",
+          "@ds-mo/icons ^6.4.0"
+        ],
+        "frameworks": "Custom Elements; React 18/19 wrappers; Angular 19-22 standalone adapters."
+      }
+    }
+  },
+  "dependencies": [
+    "@ds-mo/ui",
+    "@ds-mo/tokens"
+  ],
+  "registryDependencies": [
+    "panel-tool-header",
+    "panel-tools",
+    "tab-group"
+  ],
+  "files": [
+    {
+      "path": "src/wc/components/ShellTools/ShellTools.css",
+      "content": ":host {\n  display: block;\n  min-width: 0;\n  min-height: 0;\n  height: 100%;\n  background: var(--color-background-primary);\n}\n\n.shell-tools__desktop,\n.shell-tools__desktop ds-panel-tools,\n.shell-tools__mobile {\n  display: block;\n  min-width: 0;\n  min-height: 0;\n  height: 100%;\n}\n\n.shell-tools__mobile {\n  display: grid;\n  grid-template-rows: auto auto minmax(0, 1fr);\n  background: var(--color-background-primary);\n}\n\n.shell-tools__inbox-nav {\n  padding: var(--dimension-space-100);\n  border-bottom: var(--dimension-stroke-width-012) solid var(--color-border-tertiary);\n  background: var(--color-background-primary);\n}\n\n.shell-tools__mobile-body,\n.shell-tools__view {\n  min-width: 0;\n  min-height: 0;\n  height: 100%;\n}\n\n.shell-tools__mobile-body {\n  overflow: hidden;\n}\n\n.shell-tools__view {\n  overflow: auto;\n  overscroll-behavior: contain;\n}\n\n.shell-tools__view[hidden] {\n  display: none;\n}\n\n.shell-tools__view ::slotted(*) {\n  min-height: 0;\n}\n",
+      "type": "registry:ui"
+    },
+    {
+      "path": "src/wc/components/ShellTools/ShellTools.tsx",
+      "content": "import {\n  Component,\n  Element,\n  Event,\n  EventEmitter,\n  h,\n  Host,\n  Method,\n  Prop,\n  Watch,\n} from '@stencil/core';\nimport {\n  PANEL_TOOLS_LABELS,\n  PANEL_TOOLS_TOOL_IDS,\n  type PanelToolsHeaderAction,\n  type PanelToolsHeaderConfig,\n  type PanelToolsHeaders,\n  type PanelToolsItem,\n  type PanelToolsToolId,\n} from '../PanelTools/panel-tools-types';\nimport {\n  parsePanelToolsItems,\n  reconcilePanelToolsAvailability,\n  resolvePanelToolActivation,\n} from '../PanelTools/panel-tools-utils';\nimport {\n  isShellInboxTool,\n  resolveAvailableInboxTool,\n  type ShellInboxToolId,\n  type ShellResponsiveMode,\n} from '../../shell/shell-responsive';\n\nconst MOBILE_VIEW_ORDER: PanelToolsToolId[] = [\n  'search',\n  'agents',\n  'messages',\n  'stacks',\n  'activity',\n  'help',\n];\n\n@Component({\n  tag: 'ds-shell-tools',\n  styleUrl: 'ShellTools.css',\n  scoped: true,\n})\nexport class ShellTools {\n  @Element() el!: HTMLElement;\n\n  /** Resolved by ShellApp; mobile uses a full-stage tool presentation. */\n  @Prop({ attribute: 'responsive-mode', reflect: true })\n  responsiveMode: ShellResponsiveMode = 'desktop';\n  @Prop({ mutable: true, reflect: true }) open: boolean = false;\n  @Prop({ mutable: true, attribute: 'active-tool', reflect: true })\n  activeTool: PanelToolsToolId | '' = '';\n  @Prop({ mutable: true, reflect: true }) presentation: 'drawer' | 'fullscreen' = 'drawer';\n  @Prop({ attribute: 'fullscreen-header-mode', reflect: true })\n  fullscreenHeaderMode: 'shared' | 'split' = 'shared';\n  @Prop() items: PanelToolsItem[] = [];\n  @Prop({ attribute: 'items-json' }) itemsJson: string = '';\n  @Prop() headers: PanelToolsHeaders = {};\n  @Prop({ attribute: 'headers-json' }) headersJson: string = '';\n  @Prop({ attribute: 'storage-key' }) storageKey: string = '';\n  @Prop() toolsLabel: string = 'Tools';\n  @Prop() toolShortcutsLabel: string = 'Tool shortcuts';\n  @Prop() inboxLabel: string = 'Inbox';\n  @Prop() inboxNavigationLabel: string = 'Inbox sections';\n\n  @Event({ bubbles: true, composed: true }) dsToolChange!: EventEmitter<{\n    id: PanelToolsToolId;\n    selected: boolean;\n  }>;\n  @Event({ bubbles: true, composed: true }) dsPresentationChange!: EventEmitter<{\n    presentation: 'drawer' | 'fullscreen';\n  }>;\n  @Event({ bubbles: true, composed: true }) dsHeaderBack!: EventEmitter<{\n    tool: PanelToolsToolId;\n  }>;\n  @Event({ bubbles: true, composed: true }) dsHeaderAction!: EventEmitter<{\n    tool: PanelToolsToolId;\n    id: string;\n  }>;\n\n  private panelToolsEl: HTMLDsPanelToolsElement | null = null;\n\n  private get resolvedItems(): PanelToolsItem[] {\n    return parsePanelToolsItems(this.items, this.itemsJson);\n  }\n\n  private get availableInboxTools(): ShellInboxToolId[] {\n    return this.resolvedItems\n      .filter(item => !item.isInactive && isShellInboxTool(item.id))\n      .map(item => item.id as ShellInboxToolId);\n  }\n\n  private get mobileActiveTool(): PanelToolsToolId | '' {\n    if (!isShellInboxTool(this.activeTool)) return this.activeTool;\n    return resolveAvailableInboxTool(this.activeTool, this.availableInboxTools);\n  }\n\n  componentWillLoad() {\n    this.reconcileAvailability();\n  }\n\n  @Watch('items')\n  @Watch('itemsJson')\n  handleItemsChange() {\n    this.reconcileAvailability();\n  }\n\n  private reconcileAvailability() {\n    const next = reconcilePanelToolsAvailability(this.resolvedItems, this.open, this.activeTool);\n    this.open = next.open;\n    this.activeTool = next.activeTool;\n  }\n\n  private resolvedHeaders(): PanelToolsHeaders {\n    if (Object.keys(this.headers).length) return this.headers;\n    if (!this.headersJson.trim()) return {};\n    try {\n      const parsed = JSON.parse(this.headersJson);\n      return parsed && typeof parsed === 'object' && !Array.isArray(parsed)\n        ? (parsed as PanelToolsHeaders)\n        : {};\n    } catch {\n      return {};\n    }\n  }\n\n  private activeHeader(tool: PanelToolsToolId): PanelToolsHeaderConfig {\n    return this.resolvedHeaders()[tool] ?? {};\n  }\n\n  private activateMobileTool(id: PanelToolsToolId) {\n    const item = this.resolvedItems.find(entry => entry.id === id);\n    if (!item || item.isInactive) return;\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  private selectInboxTool = (event: CustomEvent<string>) => {\n    const id = event.detail;\n    if (!isShellInboxTool(id) || id === this.mobileActiveTool) return;\n    this.open = true;\n    this.activeTool = id;\n    this.dsToolChange.emit({ id, selected: true });\n  };\n\n  private handlePanelToolChange = (\n    event: CustomEvent<{ id: PanelToolsToolId; selected: boolean }>\n  ) => {\n    this.activeTool = event.detail.id;\n    this.open = event.detail.selected;\n  };\n\n  private handlePanelPresentationChange = (\n    event: CustomEvent<{ presentation: 'drawer' | 'fullscreen' }>\n  ) => {\n    this.presentation = event.detail.presentation;\n  };\n\n  private handleMobileHeaderAction = (\n    tool: PanelToolsToolId,\n    event: CustomEvent<{ id: string }>\n  ) => {\n    event.stopPropagation();\n    this.dsHeaderAction.emit({ tool, id: event.detail.id });\n  };\n\n  /** Match PanelTools' imperative activation contract in every responsive mode. */\n  @Method()\n  async activateTool(id: PanelToolsToolId) {\n    if (this.responsiveMode !== 'mobile') {\n      await this.panelToolsEl?.activateTool(id);\n      return;\n    }\n    this.activateMobileTool(id);\n  }\n\n  /** Close the active global tool surface. */\n  @Method()\n  async closeDrawer() {\n    if (this.responsiveMode !== 'mobile') {\n      await this.panelToolsEl?.closeDrawer();\n      return;\n    }\n    if (!this.open) return;\n    const id = this.activeTool;\n    this.open = false;\n    if (id) this.dsToolChange.emit({ id, selected: false });\n  }\n\n  /** Focus an application-owned action in the visible shared tool header. */\n  @Method()\n  async focusHeaderAction(id: string) {\n    if (this.responsiveMode !== 'mobile') {\n      await this.panelToolsEl?.focusHeaderAction(id);\n      return;\n    }\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 renderForwardedSlots() {\n    return PANEL_TOOLS_TOOL_IDS.flatMap(id => [\n      <slot name={id} slot={id} />,\n      <slot name={`${id}-view`} slot={`${id}-view`} />,\n    ]);\n  }\n\n  private renderDesktop() {\n    return (\n      <div class=\"shell-tools__desktop\">\n        <ds-panel-tools\n          open={this.open}\n          activeTool={this.activeTool}\n          presentation={this.presentation}\n          fullscreenHeaderMode={this.fullscreenHeaderMode}\n          items={this.resolvedItems}\n          headers={this.resolvedHeaders()}\n          storageKey={this.storageKey}\n          toolsLabel={this.toolsLabel}\n          toolShortcutsLabel={this.toolShortcutsLabel}\n          ref={element => {\n            this.panelToolsEl = element as HTMLDsPanelToolsElement | null;\n          }}\n          onDsToolChange={this.handlePanelToolChange}\n          onDsPresentationChange={this.handlePanelPresentationChange}\n        >\n          {this.renderForwardedSlots()}\n        </ds-panel-tools>\n      </div>\n    );\n  }\n\n  private renderMobileHeader(tool: PanelToolsToolId) {\n    const header = this.activeHeader(tool);\n    const configuredTitle = header.title?.trim();\n    const title = isShellInboxTool(tool)\n      ? header.showBack && configuredTitle\n        ? configuredTitle\n        : this.inboxLabel\n      : configuredTitle || PANEL_TOOLS_LABELS[tool];\n    const actions = header.actions ?? [];\n\n    return (\n      <ds-panel-tool-header\n        class=\"shell-tools__mobile-header\"\n        heading={title}\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 & { actions: PanelToolsHeaderAction[] })\n            | undefined;\n          if (toolHeader) toolHeader.actions = actions;\n        }}\n        onDsBack={() => this.dsHeaderBack.emit({ tool })}\n        onDsAction={(event: CustomEvent<{ id: string }>) =>\n          this.handleMobileHeaderAction(tool, event)}\n      />\n    );\n  }\n\n  private renderMobile() {\n    const tool = this.mobileActiveTool;\n    const inboxTabs = this.availableInboxTools.map(id => ({\n      id,\n      label: PANEL_TOOLS_LABELS[id],\n    }));\n\n    return (\n      <div\n        class=\"shell-tools__mobile\"\n        aria-hidden={this.open && tool ? undefined : 'true'}\n        inert={this.open && tool ? undefined : true}\n      >\n        {tool ? this.renderMobileHeader(tool) : null}\n        {tool && isShellInboxTool(tool) && inboxTabs.length ? (\n          <div class=\"shell-tools__inbox-nav\">\n            <ds-tab-group\n              tabs={inboxTabs}\n              value={tool}\n              aria-label={this.inboxNavigationLabel}\n              onDsChange={this.selectInboxTool}\n            />\n          </div>\n        ) : null}\n        <div class=\"shell-tools__mobile-body\">\n          {MOBILE_VIEW_ORDER.map(id => {\n            const active = this.open && id === tool;\n            return (\n              <div\n                class={{\n                  'shell-tools__view': true,\n                  'shell-tools__view--active': active,\n                }}\n                hidden={!active}\n                aria-hidden={active ? undefined : 'true'}\n                inert={active ? undefined : true}\n              >\n                <slot name={`${id}-view`}>\n                  <slot name={id} />\n                </slot>\n              </div>\n            );\n          })}\n        </div>\n      </div>\n    );\n  }\n\n  render() {\n    return (\n      <Host\n        role={this.presentation === 'fullscreen' ? 'dialog' : 'complementary'}\n        aria-modal={this.presentation === 'fullscreen' ? 'true' : undefined}\n        aria-label={this.toolsLabel}\n      >\n        {this.responsiveMode === 'mobile' ? this.renderMobile() : this.renderDesktop()}\n      </Host>\n    );\n  }\n}\n",
+      "type": "registry:ui"
+    }
+  ]
+}