@ds-mo/ui 14.28.0 → 14.29.0

package/dist/mcp-data/registry/panel-tool-header.json

@@ -35,7 +35,8 @@
         "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.",
-        "PanelTools supplies application-owned actions and relays their ids through its shared dsHeaderAction event."
+        "PanelTools supplies application-owned actions and relays their ids through its shared dsHeaderAction event.",
+        "Application-owned action surfaces carry surfaceOpen independently from expanded disclosure and pressed toggle state. Retain surfaceOpen until the associated surface completes closing; the header forwards this relationship without owning the menu or panel."
       ],
       "responsiveBehavior": [
         "The title truncates between optional leading navigation and trailing action zones."
@@ -44,6 +45,10 @@
         {
           "label": "Standalone examples",
           "path": "src/wc/components/PanelToolHeader/PanelToolHeader.stories.ts"
+        },
+        {
+          "label": "Surface ownership and trigger state",
+          "path": "src/docs/SurfaceOwnership.mdx"
         }
       ]
     },
@@ -110,6 +115,14 @@
           "mutable": false,
           "description": "Whether the controlled menu is open."
         },
+        "menuSurfaceOpen": {
+          "type": "boolean | undefined",
+          "resolvedType": "boolean | undefined",
+          "attribute": "menu-surface-open",
+          "required": false,
+          "mutable": false,
+          "description": "Associated menu surface is visible, including exit motion."
+        },
         "menuTriggerId": {
           "type": "string",
           "resolvedType": "string",
@@ -231,6 +244,14 @@
         "mutable": false,
         "description": "Whether the controlled menu is open."
       },
+      "menuSurfaceOpen": {
+        "type": "boolean | undefined",
+        "resolvedType": "boolean | undefined",
+        "attribute": "menu-surface-open",
+        "required": false,
+        "mutable": false,
+        "description": "Associated menu surface is visible, including exit motion."
+      },
       "menuTriggerId": {
         "type": "string",
         "resolvedType": "string",
@@ -341,7 +362,7 @@
     },
     {
       "path": "src/wc/components/PanelToolHeader/PanelToolHeader.tsx",
-      "content": "import { Component, Element, Event, EventEmitter, h, Host, Method, Prop } from '@stencil/core';\nimport type {\n  PanelToolHeaderActionDetail,\n  PanelToolsHeaderAction,\n} from '../PanelTools/panel-tools-types';\n\n@Component({\n  tag: 'ds-panel-tool-header',\n  styleUrl: 'PanelToolHeader.css',\n  scoped: true,\n})\nexport class PanelToolHeader {\n  @Element() el!: HTMLElement;\n\n  /** Visible heading for the active tool view. */\n  @Prop() heading: string = '';\n  /** Show the leading Back action. */\n  @Prop() showBack: boolean = false;\n  /** Canonical icon for the leading navigation or dismiss action. */\n  @Prop() backIcon: string = 'ChevronLeft';\n  /** Accessible name for the leading navigation or dismiss action. */\n  @Prop() backAriaLabel: string = 'Back';\n  /** Show the trailing options-menu trigger. */\n  @Prop() showMenu: boolean = true;\n  /** Accessible name for the options-menu trigger. */\n  @Prop() menuAriaLabel: string = 'More options';\n  /** Stable id placed on the menu trigger host for ds-menu anchoring. */\n  @Prop() menuTriggerId: string = '';\n  /** Id of the menu controlled by the trigger. */\n  @Prop() menuControls: string | undefined;\n  /** Whether the controlled menu is open. */\n  @Prop() menuExpanded: boolean = false;\n  /** Trailing application-owned icon actions. When present, these replace the legacy menu action. */\n  @Prop() actions: PanelToolsHeaderAction[] = [];\n\n  @Event() dsBack!: EventEmitter<MouseEvent>;\n  @Event() dsMenuToggle!: EventEmitter<MouseEvent>;\n  @Event() dsAction!: EventEmitter<PanelToolHeaderActionDetail>;\n\n  @Method()\n  async focusMenuTrigger() {\n    const trigger = this.el.querySelector(\n      'ds-button-unfilled.panel-tool-header__menu, ds-button-unfilled[data-header-action-id=\"menu\"]'\n    ) as (HTMLElement & { setFocus?: () => Promise<void> }) | null;\n    await trigger?.setFocus?.();\n  }\n\n  render() {\n    const authoredActions = this.actions.length > 0;\n    const actions: PanelToolsHeaderAction[] = authoredActions\n      ? this.actions\n      : this.showMenu\n        ? [\n            {\n              id: 'menu',\n              icon: 'Ellipses',\n              ariaLabel: this.menuAriaLabel,\n              triggerId: this.menuTriggerId,\n              controls: this.menuControls,\n              expanded: this.menuExpanded,\n              haspopup: 'menu',\n            },\n          ]\n        : [];\n\n    return (\n      <Host>\n        <header class=\"panel-tool-header ds-chrome-header ds-chrome-header--bounded\">\n          <div class=\"panel-tool-header__leading ds-chrome-header__leading\">\n            {this.showBack ? (\n              <ds-tooltip label={this.backAriaLabel} side=\"bottom\" size=\"sm\">\n                <ds-button-unfilled\n                  class=\"panel-tool-header__back\"\n                  variant=\"icon\"\n                  icon={this.backIcon}\n                  size=\"md\"\n                  aria-label={this.backAriaLabel}\n                  activeFill={false}\n                  hasBorder={false}\n                  onDsClick={(event: CustomEvent<MouseEvent>) => this.dsBack.emit(event.detail)}\n                />\n              </ds-tooltip>\n            ) : null}\n          </div>\n          <ds-text\n            class=\"panel-tool-header__heading ds-chrome-header__heading ds-control--md\"\n            as=\"h2\"\n            variant=\"text-body-medium\"\n            emphasis\n            color=\"primary\"\n            lineTruncation={1}\n          >\n            {this.heading}\n          </ds-text>\n          <div class=\"panel-tool-header__trailing ds-chrome-header__trailing\">\n            {actions.map(action => (\n              <ds-tooltip key={action.id} label={action.ariaLabel} side=\"bottom\" size=\"sm\">\n                <ds-button-unfilled\n                  id={action.triggerId || undefined}\n                  data-header-action-id={action.id}\n                  class={{\n                    'panel-tool-header__action': true,\n                    'panel-tool-header__menu': action.id === 'menu',\n                  }}\n                  variant=\"icon\"\n                  icon={action.icon}\n                  size=\"md\"\n                  aria-label={action.ariaLabel}\n                  haspopup={action.haspopup}\n                  controls={action.controls}\n                  expanded={action.expanded}\n                  pressed={action.pressed}\n                  isInactive={action.isInactive}\n                  activeFill={false}\n                  hasBorder={false}\n                  onDsClick={(event: CustomEvent<MouseEvent>) => {\n                    if (!authoredActions && action.id === 'menu')\n                      this.dsMenuToggle.emit(event.detail);\n                    this.dsAction.emit({\n                      id: action.id,\n                      originalEvent: event.detail,\n                      anchor: event.currentTarget as HTMLElement,\n                    });\n                  }}\n                />\n              </ds-tooltip>\n            ))}\n          </div>\n        </header>\n      </Host>\n    );\n  }\n}\n",
+      "content": "import { Component, Element, Event, EventEmitter, h, Host, Method, Prop } from '@stencil/core';\nimport type {\n  PanelToolHeaderActionDetail,\n  PanelToolsHeaderAction,\n} from '../PanelTools/panel-tools-types';\n\n@Component({\n  tag: 'ds-panel-tool-header',\n  styleUrl: 'PanelToolHeader.css',\n  scoped: true,\n})\nexport class PanelToolHeader {\n  @Element() el!: HTMLElement;\n\n  /** Visible heading for the active tool view. */\n  @Prop() heading: string = '';\n  /** Show the leading Back action. */\n  @Prop() showBack: boolean = false;\n  /** Canonical icon for the leading navigation or dismiss action. */\n  @Prop() backIcon: string = 'ChevronLeft';\n  /** Accessible name for the leading navigation or dismiss action. */\n  @Prop() backAriaLabel: string = 'Back';\n  /** Show the trailing options-menu trigger. */\n  @Prop() showMenu: boolean = true;\n  /** Accessible name for the options-menu trigger. */\n  @Prop() menuAriaLabel: string = 'More options';\n  /** Stable id placed on the menu trigger host for ds-menu anchoring. */\n  @Prop() menuTriggerId: string = '';\n  /** Id of the menu controlled by the trigger. */\n  @Prop() menuControls: string | undefined;\n  /** Whether the controlled menu is open. */\n  @Prop() menuExpanded: boolean = false;\n  /** Associated menu surface is visible, including exit motion. */\n  @Prop() menuSurfaceOpen: boolean | undefined;\n  /** Trailing application-owned icon actions. When present, these replace the legacy menu action. */\n  @Prop() actions: PanelToolsHeaderAction[] = [];\n\n  @Event() dsBack!: EventEmitter<MouseEvent>;\n  @Event() dsMenuToggle!: EventEmitter<MouseEvent>;\n  @Event() dsAction!: EventEmitter<PanelToolHeaderActionDetail>;\n\n  @Method()\n  async focusMenuTrigger() {\n    const trigger = this.el.querySelector(\n      'ds-button-unfilled.panel-tool-header__menu, ds-button-unfilled[data-header-action-id=\"menu\"]'\n    ) as (HTMLElement & { setFocus?: () => Promise<void> }) | null;\n    await trigger?.setFocus?.();\n  }\n\n  render() {\n    const authoredActions = this.actions.length > 0;\n    const actions: PanelToolsHeaderAction[] = authoredActions\n      ? this.actions\n      : this.showMenu\n        ? [\n            {\n              id: 'menu',\n              icon: 'Ellipses',\n              ariaLabel: this.menuAriaLabel,\n              triggerId: this.menuTriggerId,\n              controls: this.menuControls,\n              expanded: this.menuExpanded,\n              surfaceOpen: this.menuSurfaceOpen,\n              haspopup: 'menu',\n            },\n          ]\n        : [];\n\n    return (\n      <Host>\n        <header class=\"panel-tool-header ds-chrome-header ds-chrome-header--bounded\">\n          <div class=\"panel-tool-header__leading ds-chrome-header__leading\">\n            {this.showBack ? (\n              <ds-tooltip label={this.backAriaLabel} side=\"bottom\" size=\"sm\">\n                <ds-button-unfilled\n                  class=\"panel-tool-header__back\"\n                  variant=\"icon\"\n                  icon={this.backIcon}\n                  size=\"md\"\n                  aria-label={this.backAriaLabel}\n                  activeFill={false}\n                  hasBorder={false}\n                  onDsClick={(event: CustomEvent<MouseEvent>) => this.dsBack.emit(event.detail)}\n                />\n              </ds-tooltip>\n            ) : null}\n          </div>\n          <ds-text\n            class=\"panel-tool-header__heading ds-chrome-header__heading ds-control--md\"\n            as=\"h2\"\n            variant=\"text-body-medium\"\n            emphasis\n            color=\"primary\"\n            lineTruncation={1}\n          >\n            {this.heading}\n          </ds-text>\n          <div class=\"panel-tool-header__trailing ds-chrome-header__trailing\">\n            {actions.map(action => (\n              <ds-tooltip key={action.id} label={action.ariaLabel} side=\"bottom\" size=\"sm\">\n                <ds-button-unfilled\n                  id={action.triggerId || undefined}\n                  data-header-action-id={action.id}\n                  class={{\n                    'panel-tool-header__action': true,\n                    'panel-tool-header__menu': action.id === 'menu',\n                  }}\n                  variant=\"icon\"\n                  icon={action.icon}\n                  size=\"md\"\n                  aria-label={action.ariaLabel}\n                  haspopup={action.haspopup}\n                  controls={action.controls}\n                  expanded={action.expanded}\n                  surfaceOpen={action.surfaceOpen}\n                  pressed={action.pressed}\n                  isInactive={action.isInactive}\n                  activeFill={false}\n                  hasBorder={false}\n                  onDsClick={(event: CustomEvent<MouseEvent>) => {\n                    if (!authoredActions && action.id === 'menu')\n                      this.dsMenuToggle.emit(event.detail);\n                    this.dsAction.emit({\n                      id: action.id,\n                      originalEvent: event.detail,\n                      anchor: event.currentTarget as HTMLElement,\n                    });\n                  }}\n                />\n              </ds-tooltip>\n            ))}\n          </div>\n        </header>\n      </Host>\n    );\n  }\n}\n",
       "type": "registry:ui"
     }
   ]

package/dist/mcp-data/registry/panel-tool-search.json

@@ -38,7 +38,8 @@
         "The search icon stays foreground-secondary at rest, hover, focus, active, and while the query is filled.",
         "The row and control surface remain transparent so the ShellApp chrome wash is visible behind them.",
         "The row divider remains the same tertiary 1px boundary while the input is focused because it belongs to the 48px container rather than the input control.",
-        "With filtering enabled, the md search control, decorative vertical divider, and borderless md Filter action are separated by 8px; filterActive promotes only the trigger foreground without adding a selected fill."
+        "With filtering enabled, the md search control, decorative vertical divider, and borderless md Filter action are separated by 8px; filterActive promotes only the trigger foreground without adding a selected fill.",
+        "Applied filters and an open filter surface are independent states. Use filterSurfaceOpen through the external surface exit while filterExpanded describes disclosure and filterActive describes applied values."
       ],
       "responsiveBehavior": [
         "The row fills the available drawer or fullscreen width, allows its search region to shrink inside a 300px drawer without pushing the filter trigger under the tool rail, and does not reduce its control below md density."
@@ -61,6 +62,10 @@
         {
           "label": "Storybook examples",
           "path": "src/wc/components/PanelToolSearch/PanelToolSearch.stories.ts"
+        },
+        {
+          "label": "Surface ownership and trigger state",
+          "path": "src/docs/SurfaceOwnership.mdx"
         }
       ]
     },
@@ -118,6 +123,14 @@
           "mutable": false,
           "description": "Whether the controlled filter menu is open."
         },
+        "filterSurfaceOpen": {
+          "type": "boolean | undefined",
+          "resolvedType": "boolean | undefined",
+          "attribute": "filter-surface-open",
+          "required": false,
+          "mutable": false,
+          "description": "Associated filter surface is visible, including exit motion."
+        },
         "filterTriggerId": {
           "type": "string",
           "resolvedType": "string",
@@ -252,6 +265,14 @@
         "mutable": false,
         "description": "Whether the controlled filter menu is open."
       },
+      "filterSurfaceOpen": {
+        "type": "boolean | undefined",
+        "resolvedType": "boolean | undefined",
+        "attribute": "filter-surface-open",
+        "required": false,
+        "mutable": false,
+        "description": "Associated filter surface is visible, including exit motion."
+      },
       "filterTriggerId": {
         "type": "string",
         "resolvedType": "string",
@@ -385,7 +406,7 @@
     },
     {
       "path": "src/wc/components/PanelToolSearch/PanelToolSearch.tsx",
-      "content": "import { Component, Element, Event, EventEmitter, h, Host, Method, Prop } from '@stencil/core';\nimport { ChoiceSearch } from '../../utils/choice-list-parts';\n\n@Component({\n  tag: 'ds-panel-tool-search',\n  styleUrl: 'PanelToolSearch.css',\n  scoped: true,\n})\nexport class PanelToolSearch {\n  @Element() el!: HTMLElement;\n\n  /** Current search query. */\n  @Prop({ mutable: true }) value: string = '';\n  /** Search guidance shown while the query is empty. */\n  @Prop() placeholder: string = 'Search';\n  /** Accessible name for the search field. */\n  @Prop({ attribute: 'aria-label' }) ariaLabel: string = 'Search';\n  /** Optional ID of the results region filtered by this search. */\n  @Prop() controls: string | undefined;\n  /** Prevents search interaction while keeping the row visible. */\n  @Prop() isInactive: boolean = false;\n  /** Show the optional trailing filter-menu trigger. */\n  @Prop() showFilter: boolean = false;\n  /** Accessible name for the filter-menu trigger. */\n  @Prop() filterAriaLabel: string = 'Filter';\n  /** Stable id placed on the filter trigger for ds-menu anchoring. */\n  @Prop() filterTriggerId: string = '';\n  /** Id of the menu controlled by the filter trigger. */\n  @Prop() filterControls: string | undefined;\n  /** Whether the controlled filter menu is open. */\n  @Prop() filterExpanded: boolean = false;\n  /** Promote the trigger foreground when one or more filters are applied. */\n  @Prop() filterActive: boolean = false;\n\n  @Event() dsChange!: EventEmitter<string>;\n  @Event() dsClear!: EventEmitter<void>;\n  @Event() dsFilterToggle!: EventEmitter<MouseEvent>;\n\n  componentDidRender() {\n    const input = this.el.querySelector('input');\n    if (input && input.value !== this.value) input.value = this.value;\n  }\n\n  @Method()\n  async setFocus() {\n    this.el.querySelector('input')?.focus();\n  }\n\n  @Method()\n  async focusFilterTrigger() {\n    const trigger = this.el.querySelector('ds-button-unfilled.panel-tool-search__filter') as\n      | (HTMLElement & { setFocus?: () => Promise<void> })\n      | null;\n    await trigger?.setFocus?.();\n  }\n\n  private handleChange = (value: string) => {\n    this.value = value;\n    this.dsChange.emit(value);\n  };\n\n  render() {\n    return (\n      <Host>\n        <div class=\"panel-tool-search ds-chrome-row ds-chrome-space--md\">\n          <ChoiceSearch\n            hasFocusBoundary={false}\n            hasInteractionFill={false}\n            value={this.value}\n            placeholder={this.placeholder}\n            ariaLabel={this.ariaLabel}\n            controls={this.controls}\n            disabled={this.isInactive}\n            inputRef={() => undefined}\n            clearLabel=\"Clear\"\n            onValueChange={this.handleChange}\n            onClear={() => this.dsClear.emit()}\n            onKeyDown={() => undefined}\n          />\n          {this.showFilter ? (\n            <div class=\"panel-tool-search__filter-group\">\n              <ds-divider\n                class=\"panel-tool-search__divider\"\n                orientation=\"vertical\"\n                length=\"var(--dimension-size-200)\"\n              />\n              <ds-tooltip label={this.filterAriaLabel} side=\"bottom\" size=\"sm\">\n                <ds-button-unfilled\n                  id={this.filterTriggerId || undefined}\n                  class=\"panel-tool-search__filter\"\n                  variant=\"icon\"\n                  icon=\"Filters\"\n                  size=\"md\"\n                  aria-label={this.filterAriaLabel}\n                  haspopup=\"menu\"\n                  controls={this.filterControls}\n                  expanded={this.filterExpanded}\n                  isActive={this.filterActive}\n                  isInactive={this.isInactive}\n                  activeFill={false}\n                  hasBorder={false}\n                  onDsChange={(event: CustomEvent<boolean>) => {\n                    event.stopPropagation();\n                  }}\n                  onDsClick={(event: CustomEvent<MouseEvent>) => {\n                    event.stopPropagation();\n                    this.dsFilterToggle.emit(event.detail);\n                  }}\n                />\n              </ds-tooltip>\n            </div>\n          ) : null}\n        </div>\n      </Host>\n    );\n  }\n}\n",
+      "content": "import { Component, Element, Event, EventEmitter, h, Host, Method, Prop } from '@stencil/core';\nimport { ChoiceSearch } from '../../utils/choice-list-parts';\n\n@Component({\n  tag: 'ds-panel-tool-search',\n  styleUrl: 'PanelToolSearch.css',\n  scoped: true,\n})\nexport class PanelToolSearch {\n  @Element() el!: HTMLElement;\n\n  /** Current search query. */\n  @Prop({ mutable: true }) value: string = '';\n  /** Search guidance shown while the query is empty. */\n  @Prop() placeholder: string = 'Search';\n  /** Accessible name for the search field. */\n  @Prop({ attribute: 'aria-label' }) ariaLabel: string = 'Search';\n  /** Optional ID of the results region filtered by this search. */\n  @Prop() controls: string | undefined;\n  /** Prevents search interaction while keeping the row visible. */\n  @Prop() isInactive: boolean = false;\n  /** Show the optional trailing filter-menu trigger. */\n  @Prop() showFilter: boolean = false;\n  /** Accessible name for the filter-menu trigger. */\n  @Prop() filterAriaLabel: string = 'Filter';\n  /** Stable id placed on the filter trigger for ds-menu anchoring. */\n  @Prop() filterTriggerId: string = '';\n  /** Id of the menu controlled by the filter trigger. */\n  @Prop() filterControls: string | undefined;\n  /** Whether the controlled filter menu is open. */\n  @Prop() filterExpanded: boolean = false;\n  /** Associated filter surface is visible, including exit motion. */\n  @Prop() filterSurfaceOpen: boolean | undefined;\n  /** Promote the trigger foreground when one or more filters are applied. */\n  @Prop() filterActive: boolean = false;\n\n  @Event() dsChange!: EventEmitter<string>;\n  @Event() dsClear!: EventEmitter<void>;\n  @Event() dsFilterToggle!: EventEmitter<MouseEvent>;\n\n  componentDidRender() {\n    const input = this.el.querySelector('input');\n    if (input && input.value !== this.value) input.value = this.value;\n  }\n\n  @Method()\n  async setFocus() {\n    this.el.querySelector('input')?.focus();\n  }\n\n  @Method()\n  async focusFilterTrigger() {\n    const trigger = this.el.querySelector('ds-button-unfilled.panel-tool-search__filter') as\n      | (HTMLElement & { setFocus?: () => Promise<void> })\n      | null;\n    await trigger?.setFocus?.();\n  }\n\n  private handleChange = (value: string) => {\n    this.value = value;\n    this.dsChange.emit(value);\n  };\n\n  render() {\n    return (\n      <Host>\n        <div class=\"panel-tool-search ds-chrome-row ds-chrome-space--md\">\n          <ChoiceSearch\n            hasFocusBoundary={false}\n            hasInteractionFill={false}\n            value={this.value}\n            placeholder={this.placeholder}\n            ariaLabel={this.ariaLabel}\n            controls={this.controls}\n            disabled={this.isInactive}\n            inputRef={() => undefined}\n            clearLabel=\"Clear\"\n            onValueChange={this.handleChange}\n            onClear={() => this.dsClear.emit()}\n            onKeyDown={() => undefined}\n          />\n          {this.showFilter ? (\n            <div class=\"panel-tool-search__filter-group\">\n              <ds-divider\n                class=\"panel-tool-search__divider\"\n                orientation=\"vertical\"\n                length=\"var(--dimension-size-200)\"\n              />\n              <ds-tooltip label={this.filterAriaLabel} side=\"bottom\" size=\"sm\">\n                <ds-button-unfilled\n                  id={this.filterTriggerId || undefined}\n                  class=\"panel-tool-search__filter\"\n                  variant=\"icon\"\n                  icon=\"Filters\"\n                  size=\"md\"\n                  aria-label={this.filterAriaLabel}\n                  haspopup=\"menu\"\n                  controls={this.filterControls}\n                  expanded={this.filterExpanded}\n                  surfaceOpen={this.filterSurfaceOpen}\n                  isActive={this.filterActive}\n                  isInactive={this.isInactive}\n                  activeFill={false}\n                  hasBorder={false}\n                  onDsChange={(event: CustomEvent<boolean>) => {\n                    event.stopPropagation();\n                  }}\n                  onDsClick={(event: CustomEvent<MouseEvent>) => {\n                    event.stopPropagation();\n                    this.dsFilterToggle.emit(event.detail);\n                  }}\n                />\n              </ds-tooltip>\n            </div>\n          ) : null}\n        </div>\n      </Host>\n    );\n  }\n}\n",
       "type": "registry:ui"
     }
   ]

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

@@ -91,7 +91,8 @@
         "The application owns slotted tool products and data while PanelTools owns rail ordering, drawer selection, open state, motion, and shell events.",
         "Opening and closing clip an already-rendered fixed-width surface. Header and tool content remain fully opaque and retained during width motion; transition completion is accepted only at the measured terminal clip width, after which the closed surface becomes inert and paint-skipped.",
         "Entering and exiting fullscreen snaps without borrowing the drawer open or close animation.",
-        "When fullscreenHeaderMode is split, PanelTools suppresses only its fullscreen shared header. The application renders exactly two canonical ds-panel-tool-header instances: a tool-title/list-actions header over the 300px history pane and a chat-title/Exit-fullscreen/chat-actions header over the detail pane. The detail header omits Back because the list remains visible."
+        "When fullscreenHeaderMode is split, PanelTools suppresses only its fullscreen shared header. The application renders exactly two canonical ds-panel-tool-header instances: a tool-title/list-actions header over the 300px history pane and a chat-title/Exit-fullscreen/chat-actions header over the detail pane. The detail header omits Back because the list remains visible.",
+        "Header action surfaceOpen identifies the owner of an external menu or panel without turning that action into a selected tool or toggle. The application owns this surface lifecycle."
       ],
       "responsiveBehavior": [
         "The open drawer reduces main-content width and uses --dimension-panel-width-xs (300px) on every supported desktop and tablet viewport.",
@@ -130,6 +131,10 @@
         {
           "label": "Application shell composition",
           "path": "agent/patterns/application-shell/pattern.agent.json"
+        },
+        {
+          "label": "Surface ownership and trigger state",
+          "path": "src/docs/SurfaceOwnership.mdx"
         }
       ]
     },
@@ -521,7 +526,7 @@
     },
     {
       "path": "src/wc/components/PanelTools/panel-tools-types.ts",
-      "content": "/** Application-owned tool id for the shell rail and responsive tool views. */\nexport type PanelToolsToolId = string;\n\n/** Canonical Motive shell recipe used when item metadata is omitted. */\nexport type CanonicalPanelToolsToolId =\n  | 'search'\n  | 'messages'\n  | 'agents'\n  | 'stacks'\n  | 'activity'\n  | 'help';\n\nexport const PANEL_TOOLS_TOOL_IDS: CanonicalPanelToolsToolId[] = [\n  'agents',\n  'messages',\n  'activity',\n  'search',\n  'stacks',\n  'help',\n];\n\n/** Rail header slot — mirrors panel-nav M logo row. */\nexport const PANEL_TOOLS_PRIMARY_TOOL_ID: CanonicalPanelToolsToolId = 'agents';\n\n/** Rail footer slot — flush to the bottom of the tools column. */\nexport const PANEL_TOOLS_FOOTER_TOOL_ID: CanonicalPanelToolsToolId = 'help';\n\nexport const PANEL_TOOLS_LABELS: Record<CanonicalPanelToolsToolId, string> = {\n  search: 'Search',\n  messages: 'Messages',\n  stacks: 'Stacks',\n  activity: 'Activity',\n  agents: 'Agents',\n  help: 'Help & Support',\n};\n\nexport const PANEL_TOOLS_SHORTCUTS: Partial<Record<CanonicalPanelToolsToolId, string>> = {\n  search: 'K',\n  agents: 'A',\n  messages: 'M',\n  stacks: 'S',\n  activity: 'N',\n  help: '/',\n};\n\nexport type PanelToolsRailPlacement = 'header' | 'body' | 'footer';\n\nexport interface PanelToolsItem {\n  id: PanelToolsToolId;\n  /** Icon name for <ds-icon>. */\n  icon: string;\n  /** Visible and accessible fallback label for custom tool ids. */\n  label?: string;\n  /** Explicit rail region; canonical Agents/Help placement is the fallback. */\n  railPlacement?: PanelToolsRailPlacement;\n  /** Stable ordering within the selected rail region. */\n  order?: number;\n  /** Optional shortcut label displayed by the tooltip. */\n  shortcutKey?: string;\n  /** Mobile destination recipe; canonical ids retain their explicit defaults. */\n  mobileDestination?: 'search' | 'inbox' | 'activity' | 'messages' | 'agents' | 'help';\n  /** Whether this rail button is currently pressed/active. */\n  selected?: boolean;\n  /** Show a notification dot. */\n  dot?: boolean;\n  isInactive?: boolean;\n  ariaLabel?: string;\n}\n\nexport type PanelToolsRailAccessoryVisual =\n  | { type: 'icon'; icon: string }\n  | { type: 'initial'; initial: string }\n  | { type: 'image'; src: string };\n\nexport interface PanelToolsRailAccessoryAction {\n  /** Stable application-owned action id emitted with the accessory id. */\n  id: string;\n  /** Overrides the accessory label for the primary action. */\n  ariaLabel?: string;\n  isInactive?: boolean;\n}\n\nexport interface PanelToolsRailAccessorySecondaryAction {\n  id: string;\n  icon: string;\n  ariaLabel: string;\n  isInactive?: boolean;\n}\n\nexport type PanelToolsRailTransientTone = 'active' | 'positive';\n\ninterface PanelToolsRailAccessoryBase {\n  /** Stable application-owned identity. Duplicate or blank ids are omitted. */\n  id: string;\n  /** Explicit rail region; accessories never infer placement from their id. */\n  railPlacement: PanelToolsRailPlacement;\n  /** Stable ordering within the selected rail region. */\n  order: number;\n}\n\n/** Decorative boundary between application-owned rail accessory groups. */\nexport interface PanelToolsRailDividerAccessory extends PanelToolsRailAccessoryBase {\n  type: 'divider';\n}\n\n/**\n * A compact one-action shortcut that matches standard tool-button geometry.\n * PanelTools owns its initial orb, notification dot, and transient interaction paint.\n */\nexport interface PanelToolsRailShortcutAccessory extends PanelToolsRailAccessoryBase {\n  type: 'shortcut';\n  /** Accessible shortcut name and action-label fallback. */\n  ariaLabel: string;\n  /** One or two displayed graphemes. Longer values are truncated visually. */\n  initials: string;\n  /** Supplemental notification dot. Include its meaning in the accessible label when needed. */\n  dot?: boolean;\n  action: PanelToolsRailAccessoryAction;\n}\n\n/**\n * A direct application intent that never selects a tool or changes drawer state.\n * PanelTools owns the two-control-height surface and its focus behavior.\n */\nexport interface PanelToolsRailTransientAccessory extends PanelToolsRailAccessoryBase {\n  type: 'transient';\n  /** Accessible accessory name and primary-action fallback label. */\n  ariaLabel: string;\n  visual: PanelToolsRailAccessoryVisual;\n  /** State announced with the primary action and shown in its tooltip. */\n  statusText: string;\n  /** Bold surface treatment. Active uses brand; positive uses positive semantic color. */\n  statusTone: PanelToolsRailTransientTone;\n  primaryAction: PanelToolsRailAccessoryAction;\n  secondaryAction?: PanelToolsRailAccessorySecondaryAction;\n}\n\nexport type PanelToolsRailAccessory =\n  | PanelToolsRailDividerAccessory\n  | PanelToolsRailShortcutAccessory\n  | PanelToolsRailTransientAccessory;\n\nexport interface PanelToolsRailAccessoryActionDetail {\n  accessoryId: string;\n  actionId: string;\n  /** Rendered action control, suitable for anchoring an application-owned overlay. */\n  anchor: HTMLElement;\n}\n\n/** Canonical shell recipe used by Lab and by managed ShellApp examples. */\nexport const PANEL_TOOLS_DEFAULT_ITEMS: PanelToolsItem[] = [\n  {\n    id: 'agents',\n    icon: 'AI',\n    label: PANEL_TOOLS_LABELS.agents,\n    railPlacement: 'header',\n    order: 0,\n    shortcutKey: PANEL_TOOLS_SHORTCUTS.agents,\n    mobileDestination: 'agents',\n  },\n  {\n    id: 'messages',\n    icon: 'MessageBubbleStack',\n    label: PANEL_TOOLS_LABELS.messages,\n    order: 0,\n    shortcutKey: PANEL_TOOLS_SHORTCUTS.messages,\n    mobileDestination: 'messages',\n  },\n  {\n    id: 'activity',\n    icon: 'Bell',\n    label: PANEL_TOOLS_LABELS.activity,\n    order: 1,\n    shortcutKey: PANEL_TOOLS_SHORTCUTS.activity,\n    mobileDestination: 'activity',\n  },\n  {\n    id: 'search',\n    icon: 'MagnifyingGlass',\n    label: PANEL_TOOLS_LABELS.search,\n    order: 2,\n    shortcutKey: PANEL_TOOLS_SHORTCUTS.search,\n    mobileDestination: 'search',\n  },\n  {\n    id: 'help',\n    icon: 'CircleQuestion',\n    label: PANEL_TOOLS_LABELS.help,\n    railPlacement: 'footer',\n    order: 0,\n    shortcutKey: PANEL_TOOLS_SHORTCUTS.help,\n    mobileDestination: 'help',\n  },\n];\n\nexport interface PanelToolsHeaderAction {\n  id: string;\n  icon: string;\n  ariaLabel: string;\n  triggerId?: string;\n  controls?: string;\n  expanded?: boolean;\n  haspopup?: 'menu' | 'dialog' | 'listbox' | 'tree' | 'grid';\n  pressed?: boolean;\n  isInactive?: boolean;\n}\n\nexport interface PanelToolsHeaderActionDetail {\n  tool: PanelToolsToolId;\n  id: string;\n  /** Rendered header action host. Pass this to an external overlay's element anchor prop. */\n  anchor?: HTMLElement;\n}\n\nexport interface PanelToolHeaderActionDetail {\n  id: string;\n  originalEvent: MouseEvent;\n  /** Rendered action host, suitable for anchoring an external overlay across a shadow boundary. */\n  anchor: HTMLElement;\n}\n\nexport interface PanelToolsHeaderConfig {\n  title?: string;\n  showBack?: boolean;\n  backIcon?: string;\n  backAriaLabel?: string;\n  actions?: PanelToolsHeaderAction[];\n}\n\n/** Per-tool header state. The application replaces the object when a tool changes depth or actions. */\nexport type PanelToolsHeaders = Partial<Record<PanelToolsToolId, PanelToolsHeaderConfig>>;\n",
+      "content": "/** Application-owned tool id for the shell rail and responsive tool views. */\nexport type PanelToolsToolId = string;\n\n/** Canonical Motive shell recipe used when item metadata is omitted. */\nexport type CanonicalPanelToolsToolId =\n  | 'search'\n  | 'messages'\n  | 'agents'\n  | 'stacks'\n  | 'activity'\n  | 'help';\n\nexport const PANEL_TOOLS_TOOL_IDS: CanonicalPanelToolsToolId[] = [\n  'agents',\n  'messages',\n  'activity',\n  'search',\n  'stacks',\n  'help',\n];\n\n/** Rail header slot — mirrors panel-nav M logo row. */\nexport const PANEL_TOOLS_PRIMARY_TOOL_ID: CanonicalPanelToolsToolId = 'agents';\n\n/** Rail footer slot — flush to the bottom of the tools column. */\nexport const PANEL_TOOLS_FOOTER_TOOL_ID: CanonicalPanelToolsToolId = 'help';\n\nexport const PANEL_TOOLS_LABELS: Record<CanonicalPanelToolsToolId, string> = {\n  search: 'Search',\n  messages: 'Messages',\n  stacks: 'Stacks',\n  activity: 'Activity',\n  agents: 'Agents',\n  help: 'Help & Support',\n};\n\nexport const PANEL_TOOLS_SHORTCUTS: Partial<Record<CanonicalPanelToolsToolId, string>> = {\n  search: 'K',\n  agents: 'A',\n  messages: 'M',\n  stacks: 'S',\n  activity: 'N',\n  help: '/',\n};\n\nexport type PanelToolsRailPlacement = 'header' | 'body' | 'footer';\n\nexport interface PanelToolsItem {\n  id: PanelToolsToolId;\n  /** Icon name for <ds-icon>. */\n  icon: string;\n  /** Visible and accessible fallback label for custom tool ids. */\n  label?: string;\n  /** Explicit rail region; canonical Agents/Help placement is the fallback. */\n  railPlacement?: PanelToolsRailPlacement;\n  /** Stable ordering within the selected rail region. */\n  order?: number;\n  /** Optional shortcut label displayed by the tooltip. */\n  shortcutKey?: string;\n  /** Mobile destination recipe; canonical ids retain their explicit defaults. */\n  mobileDestination?: 'search' | 'inbox' | 'activity' | 'messages' | 'agents' | 'help';\n  /** Whether this rail button is currently pressed/active. */\n  selected?: boolean;\n  /** Show a notification dot. */\n  dot?: boolean;\n  isInactive?: boolean;\n  ariaLabel?: string;\n}\n\nexport type PanelToolsRailAccessoryVisual =\n  | { type: 'icon'; icon: string }\n  | { type: 'initial'; initial: string }\n  | { type: 'image'; src: string };\n\nexport interface PanelToolsRailAccessoryAction {\n  /** Stable application-owned action id emitted with the accessory id. */\n  id: string;\n  /** Overrides the accessory label for the primary action. */\n  ariaLabel?: string;\n  isInactive?: boolean;\n}\n\nexport interface PanelToolsRailAccessorySecondaryAction {\n  id: string;\n  icon: string;\n  ariaLabel: string;\n  isInactive?: boolean;\n}\n\nexport type PanelToolsRailTransientTone = 'active' | 'positive';\n\ninterface PanelToolsRailAccessoryBase {\n  /** Stable application-owned identity. Duplicate or blank ids are omitted. */\n  id: string;\n  /** Explicit rail region; accessories never infer placement from their id. */\n  railPlacement: PanelToolsRailPlacement;\n  /** Stable ordering within the selected rail region. */\n  order: number;\n}\n\n/** Decorative boundary between application-owned rail accessory groups. */\nexport interface PanelToolsRailDividerAccessory extends PanelToolsRailAccessoryBase {\n  type: 'divider';\n}\n\n/**\n * A compact one-action shortcut that matches standard tool-button geometry.\n * PanelTools owns its initial orb, notification dot, and transient interaction paint.\n */\nexport interface PanelToolsRailShortcutAccessory extends PanelToolsRailAccessoryBase {\n  type: 'shortcut';\n  /** Accessible shortcut name and action-label fallback. */\n  ariaLabel: string;\n  /** One or two displayed graphemes. Longer values are truncated visually. */\n  initials: string;\n  /** Supplemental notification dot. Include its meaning in the accessible label when needed. */\n  dot?: boolean;\n  action: PanelToolsRailAccessoryAction;\n}\n\n/**\n * A direct application intent that never selects a tool or changes drawer state.\n * PanelTools owns the two-control-height surface and its focus behavior.\n */\nexport interface PanelToolsRailTransientAccessory extends PanelToolsRailAccessoryBase {\n  type: 'transient';\n  /** Accessible accessory name and primary-action fallback label. */\n  ariaLabel: string;\n  visual: PanelToolsRailAccessoryVisual;\n  /** State announced with the primary action and shown in its tooltip. */\n  statusText: string;\n  /** Bold surface treatment. Active uses brand; positive uses positive semantic color. */\n  statusTone: PanelToolsRailTransientTone;\n  primaryAction: PanelToolsRailAccessoryAction;\n  secondaryAction?: PanelToolsRailAccessorySecondaryAction;\n}\n\nexport type PanelToolsRailAccessory =\n  | PanelToolsRailDividerAccessory\n  | PanelToolsRailShortcutAccessory\n  | PanelToolsRailTransientAccessory;\n\nexport interface PanelToolsRailAccessoryActionDetail {\n  accessoryId: string;\n  actionId: string;\n  /** Rendered action control, suitable for anchoring an application-owned overlay. */\n  anchor: HTMLElement;\n}\n\n/** Canonical shell recipe used by Lab and by managed ShellApp examples. */\nexport const PANEL_TOOLS_DEFAULT_ITEMS: PanelToolsItem[] = [\n  {\n    id: 'agents',\n    icon: 'AI',\n    label: PANEL_TOOLS_LABELS.agents,\n    railPlacement: 'header',\n    order: 0,\n    shortcutKey: PANEL_TOOLS_SHORTCUTS.agents,\n    mobileDestination: 'agents',\n  },\n  {\n    id: 'messages',\n    icon: 'MessageBubbleStack',\n    label: PANEL_TOOLS_LABELS.messages,\n    order: 0,\n    shortcutKey: PANEL_TOOLS_SHORTCUTS.messages,\n    mobileDestination: 'messages',\n  },\n  {\n    id: 'activity',\n    icon: 'Bell',\n    label: PANEL_TOOLS_LABELS.activity,\n    order: 1,\n    shortcutKey: PANEL_TOOLS_SHORTCUTS.activity,\n    mobileDestination: 'activity',\n  },\n  {\n    id: 'search',\n    icon: 'MagnifyingGlass',\n    label: PANEL_TOOLS_LABELS.search,\n    order: 2,\n    shortcutKey: PANEL_TOOLS_SHORTCUTS.search,\n    mobileDestination: 'search',\n  },\n  {\n    id: 'help',\n    icon: 'CircleQuestion',\n    label: PANEL_TOOLS_LABELS.help,\n    railPlacement: 'footer',\n    order: 0,\n    shortcutKey: PANEL_TOOLS_SHORTCUTS.help,\n    mobileDestination: 'help',\n  },\n];\n\nexport interface PanelToolsHeaderAction {\n  id: string;\n  icon: string;\n  ariaLabel: string;\n  triggerId?: string;\n  controls?: string;\n  expanded?: boolean;\n  /** Associated surface remains visible, including exit motion. */\n  surfaceOpen?: boolean;\n  haspopup?: 'menu' | 'dialog' | 'listbox' | 'tree' | 'grid';\n  pressed?: boolean;\n  isInactive?: boolean;\n}\n\nexport interface PanelToolsHeaderActionDetail {\n  tool: PanelToolsToolId;\n  id: string;\n  /** Rendered header action host. Pass this to an external overlay's element anchor prop. */\n  anchor?: HTMLElement;\n}\n\nexport interface PanelToolHeaderActionDetail {\n  id: string;\n  originalEvent: MouseEvent;\n  /** Rendered action host, suitable for anchoring an external overlay across a shadow boundary. */\n  anchor: HTMLElement;\n}\n\nexport interface PanelToolsHeaderConfig {\n  title?: string;\n  showBack?: boolean;\n  backIcon?: string;\n  backAriaLabel?: string;\n  actions?: PanelToolsHeaderAction[];\n}\n\n/** Per-tool header state. The application replaces the object when a tool changes depth or actions. */\nexport type PanelToolsHeaders = Partial<Record<PanelToolsToolId, PanelToolsHeaderConfig>>;\n",
       "type": "registry:ui"
     },
     {