@ds-mo/ui 14.27.1 → 14.29.0

package/dist/agent.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "1.0.0",
   "package": "@ds-mo/ui",
-  "packageVersion": "14.27.1",
+  "packageVersion": "14.29.0",
   "kind": "components",
   "entries": [
     {
@@ -1121,7 +1121,8 @@
           "On non-tab detail routes, show the parent PanelNav destination label in BarNav while the detail-page title remains in page content.",
           "Dividers and groups visually organize peer route sections only and do not create hierarchy.",
           "The application filters unauthorized sections before passing tabs to BarNav.",
-          "Dashboard and Settings route state updates PanelNav groups, BarNav tabs, heading, basePath, currentUrl, and navStyle as one coordinated change."
+          "Dashboard and Settings route state updates PanelNav groups, BarNav tabs, heading, basePath, currentUrl, and navStyle as one coordinated change.",
+          "The overflow trigger automatically retains the shared surface-open wash through menu exit, separately from the selected route."
         ],
         "responsiveBehavior": [
           "Keep the BarNav region present so shell height and main-content origin remain stable across routes.",
@@ -1154,6 +1155,10 @@
           {
             "label": "Application shell composition",
             "path": "agent/patterns/application-shell/pattern.agent.json"
+          },
+          {
+            "label": "Surface ownership and trigger state",
+            "path": "src/docs/SurfaceOwnership.mdx"
           }
         ]
       },
@@ -1284,7 +1289,8 @@
           "expanded renders the larger heading, optional description, inset divider, and a full-width caption breadcrumb row above the title. The breadcrumb begins after 32px top padding; the following title and right-side actions share one top alignment. Compact renders 48px chrome with the existing icon Back action; constrained uses compact chrome and moves an auto-collapse primary action into overflow.",
           "The one visible ordered action collapses by default in constrained presentation. Use never for an exceptional action whose hierarchy must remain visible; explicit overflow actions never leave the shared menu.",
           "showDivider=false removes the bottom divider when the surrounding page composition supplies the boundary; showCompactDivider can independently restore or remove that boundary in compact and constrained variants.",
-          "placement=shell-bar is reserved for ShellApp panel section navigation. It remains compact, omits description and breadcrumb presentation, and preserves applicable Back, section, primary, and overflow controls."
+          "placement=shell-bar is reserved for ShellApp panel section navigation. It remains compact, omits description and breadcrumb presentation, and preserves applicable Back, section, primary, and overflow controls.",
+          "Section, action, split-menu, and overflow triggers automatically retain the shared surface-open wash through exit. The expanded header presentation is layout, not surface ownership, and does not itself acquire a pressed wash."
         ],
         "responsiveBehavior": [
           "BarTitle does not observe viewport, shell, scroll, or container state. Its owner selects an explicit variant.",
@@ -1321,6 +1327,10 @@
           {
             "label": "Cross-browser shell-page and header coverage",
             "path": "tests/e2e/bar-title.spec.ts"
+          },
+          {
+            "label": "Surface ownership and trigger state",
+            "path": "src/docs/SurfaceOwnership.mdx"
           }
         ]
       },
@@ -1795,10 +1805,11 @@
           "Physical press scaling is on by default. Disable it only when an owning composite must keep child or background geometry fixed; hover and pressed interaction washes remain available.",
           "Visible labels are emphasized by default. Set labelEmphasis to false when a composed surface deliberately needs the button label to match adjacent regular-weight control labels; this does not change the action hierarchy, foreground, icon, or interaction states.",
           "ButtonFilled has no active, pressed, or selected state; a filled action is a command, not a toggle or a persistent selection.",
-          "An open popup is a transient pressed state instead. While expanded is true the pressed wash is held for the popup's complete rendered lifecycle and survives hover, so the trigger reads as held open without introducing a selected treatment.",
+          "An open popup is a transient pressed state instead. While surfaceOpen is true the pressed wash is held for the popup's complete rendered lifecycle and survives hover, so the trigger reads as held open without introducing a selected treatment.",
           "hasMenu supports only the label and icon-label variants. The chevron is what communicates that a menu will open, so an icon-only filled menu button would leave the affordance unstated.",
           "Split mode supports label, icon, and icon-label primary segments. The primary segment emits dsClick and the appended menu segment emits dsMenuClick.",
-          "Split mode keeps both segments flush and uses a tertiary on-background separator. Rounded changes the shared outer radius without separating the segments."
+          "Split mode keeps both segments flush and uses a tertiary on-background separator. Rounded changes the shared outer radius without separating the segments.",
+          "Use surfaceOpen to identify this command as the owner of a visible menu, picker, or panel, even when that surface is distant. Keep the pressed wash through exit motion without adding selected styling or sustained physical scaling. Inline expansion and completed commands do not acquire this treatment."
         ],
         "responsiveBehavior": [
           "Use fill width only when the parent layout calls for a full-width action, commonly on narrow form layouts."
@@ -1818,6 +1829,10 @@
           {
             "label": "Storybook examples",
             "path": "src/wc/components/ButtonFilled/ButtonFilled.stories.ts"
+          },
+          {
+            "label": "Surface ownership and trigger state",
+            "path": "src/docs/SurfaceOwnership.mdx"
           }
         ]
       },
@@ -1907,6 +1922,10 @@
             "type": "boolean",
             "required": false
           },
+          "surfaceOpen": {
+            "type": "boolean | undefined",
+            "required": false
+          },
           "type": {
             "type": "'button' | 'submit' | 'reset'",
             "required": false
@@ -2002,7 +2021,7 @@
         "accessibility": [
           "Provide an explicit accessible name for every icon-only action.",
           "In split mode, provide menuAriaLabel for the appended ChevronDown segment, pass controls with the Menu id, and synchronize expanded with the Menu open state.",
-          "Set hasMenu when the button triggers a Menu; it implies aria-haspopup of menu. Pass controls with the Menu id and expanded from the same open state given to Menu. Expanded popup triggers hold only the pressed wash while open, without changing their resting foreground; expanded disclosure controls without popup semantics retain the normal resting appearance.",
+          "Set hasMenu when the button triggers a Menu; it implies aria-haspopup of menu. Pass controls with the Menu id and expanded from the same open state given to Menu. Surface-open popup triggers hold only the pressed wash while rendered, without changing their resting foreground; expanded disclosure controls without popup semantics retain the normal resting appearance.",
           "Give an icon-only menu button an accessible name that states the role, such as More options or Customize table, because no visible label or chevron carries it.",
           "Use haspopup directly for a non-menu popup such as a listbox or dialog; those cases get no chevron.",
           "Use pressed only for a genuine toggle button; it supplies aria-pressed and dsChange intent. Use isActive only for owner-controlled visual emphasis inside a composite whose selection semantics live on the owner.",
@@ -2027,9 +2046,10 @@
           "Icon and icon-label loading replace the icon in place. Label-only loading centers the loader while preserving the button's measured width.",
           "hasMenu covers two distinct menu-button shapes and the variant selects between them. With label or icon-label the action has a menu, and a trailing chevron carries the affordance. With icon the button is a menu and no chevron is added.",
           "Because the icon-only shape has no chevron, its glyph must convey the menu on its own. Use Ellipses for a generic more-options or overflow control. Use a specific icon when the menu has a named purpose, such as Table for Customize table.",
-          "An open popup is a transient pressed state rather than a selected one. While expanded is true and haspopup or hasMenu identifies a popup, the pressed wash is held for the popup's complete rendered lifecycle and survives hover without promoting foreground or selected fill, including when chrome opts out of selected fills with activeFill set to false. Expanded disclosure buttons without popup semantics remain visually neutral.",
+          "An open popup is a transient pressed state rather than a selected one. While surfaceOpen is true, the pressed wash is held for the popup's complete rendered lifecycle and survives hover without promoting foreground or selected fill, including when chrome opts out of selected fills with activeFill set to false. Expanded disclosure buttons without popup semantics remain visually neutral.",
           "Split mode supports label, icon, and icon-label primary segments. The primary segment emits dsClick and the appended menu segment emits dsMenuClick.",
-          "Split mode keeps both segments flush and uses a tertiary surface-aware separator. Bordered mode also preserves the shared outer border; borderless mode limits the separator to the content line height."
+          "Split mode keeps both segments flush and uses a tertiary surface-aware separator. Bordered mode also preserves the shared outer border; borderless mode limits the separator to the content line height.",
+          "Use surfaceOpen to identify the owner of a visible menu, picker, or panel, even when it is distant. Preserve it through exit motion independently of expanded semantics, pressed toggles, and isActive selection. It preserves resting foreground and does not hold physical scaling. Inline expansion and last-click history do not acquire this treatment."
         ],
         "responsiveBehavior": [
           "The consuming layout decides when an icon-label action becomes icon-only and must provide an explicit accessible name after changing variants. Table caption Customize is one such layout: below 900px it uses the icon shape while keeping the same neutral resting foreground regardless of the controlled column configuration.",
@@ -2052,6 +2072,10 @@
           {
             "label": "Storybook examples",
             "path": "src/wc/components/ButtonUnfilled/ButtonUnfilled.stories.ts"
+          },
+          {
+            "label": "Surface ownership and trigger state",
+            "path": "src/docs/SurfaceOwnership.mdx"
           }
         ]
       },
@@ -2157,6 +2181,10 @@
             "type": "boolean",
             "required": false
           },
+          "surfaceOpen": {
+            "type": "boolean | undefined",
+            "required": false
+          },
           "type": {
             "type": "'button' | 'submit' | 'reset'",
             "required": false
@@ -2318,6 +2346,133 @@
         "text"
       ]
     },
+    {
+      "id": "component:ds-card-navigation",
+      "tag": "ds-card-navigation",
+      "name": "card-navigation",
+      "title": "CardNavigation",
+      "summary": "Settings-style navigation surface with a native destination link, optional supporting copy, a fixed ChevronRight affordance, and an optional application-owned body.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "general",
+        "status": "stable",
+        "summary": "Settings-style navigation surface with a native destination link, optional supporting copy, a fixed ChevronRight affordance, and an optional application-owned body.",
+        "useWhen": [
+          "A settings page needs a card that leads to a deeper settings destination.",
+          "A compact destination card needs the complete surface to act as one link.",
+          "A settings summary must remain visible in a body while only the card header navigates."
+        ],
+        "avoidWhen": [
+          "The card edits its contents in place; use CardSetting for the edit-save-cancel workflow.",
+          "The destination is an action without a navigable URL.",
+          "The surface contains a chart, legend, metric visualization, or other data-visualization composition."
+        ],
+        "alternatives": [
+          {
+            "when": "The section switches between read-only and editable content in place.",
+            "component": "component:ds-card-setting",
+            "reason": "CardSetting owns the controlled edit-save-cancel workflow."
+          },
+          {
+            "when": "The surface contains a chart or specialized data-visualization composition.",
+            "component": "component:ds-card-chart",
+            "reason": "CardChart owns the independently evolving chart-card contract."
+          }
+        ],
+        "commonlyComposedWith": [
+          "component:ds-text",
+          "component:ds-card-setting"
+        ],
+        "accessibility": [
+          "CardNavigation renders a native link whenever href resolves to an allowed URL, so Enter activation, link context menus, and modified-click behavior remain available.",
+          "The heading is rendered as an h2 and the optional description contributes to the link's accessible name.",
+          "The ChevronRight icon is decorative because the link text already names the destination.",
+          "Use the content variant only when interactive body content must remain outside the header link; never place interactive descendants inside the navigation-only card.",
+          "dsNavigate is cancelable so client-side routers can prevent native navigation after accepting an unmodified activation."
+        ],
+        "states": [
+          "The native link owns hover, pressed, and focus-visible states across the complete card in navigation-only mode.",
+          "In content mode, the native link owns those interaction states only across the header while the body remains application-owned.",
+          "An empty or unsafe href renders non-interactive card chrome without a false keyboard target.",
+          "The application owns destination loading, authorization, not-found, and recovery states after navigation."
+        ],
+        "responsiveBehavior": [
+          "Choose sm, md, or lg from the parent layout; the surface never exceeds its parent width.",
+          "Supporting copy wraps while the chevron remains visible at the trailing edge.",
+          "The parent owns wrapping, columns, stacking, and breakpoint changes between cards."
+        ],
+        "frameworkCaveats": {
+          "customElements": [
+            "Set href to a valid relative or HTTP(S) URL.",
+            "Prevent dsNavigate only when an application router takes ownership of the same activation."
+          ],
+          "react": [
+            "Pass href for native link semantics and use onDsNavigate only when coordinating with a client-side router.",
+            "Use variant content when projecting interactive body content so those controls stay outside the link."
+          ],
+          "angular": [
+            "Bind href and prevent dsNavigate before calling Router.navigateByUrl for unmodified primary activations.",
+            "Use variant content when projecting interactive body content so those controls stay outside the link."
+          ]
+        },
+        "references": [
+          {
+            "label": "Storybook navigation-only and content examples",
+            "path": "src/wc/components/CardNavigation/CardNavigation.stories.ts"
+          },
+          {
+            "label": "Rendered navigation and interaction coverage",
+            "path": "tests/e2e/card-navigation.spec.ts"
+          }
+        ]
+      },
+      "api": {
+        "props": {
+          "cardWidth": {
+            "type": "CardNavigationWidth",
+            "required": false
+          },
+          "description": {
+            "type": "string | undefined",
+            "required": false
+          },
+          "heading": {
+            "type": "string",
+            "required": true
+          },
+          "href": {
+            "type": "string",
+            "required": true
+          },
+          "variant": {
+            "type": "CardNavigationVariant",
+            "required": false
+          }
+        },
+        "events": [
+          {
+            "name": "dsNavigate",
+            "detail": "CardNavigationDetail"
+          }
+        ],
+        "slots": []
+      },
+      "exports": {
+        "customElement": "ds-card-navigation",
+        "react": "DsCardNavigation",
+        "vue": "DsCardNavigation",
+        "angular": "DsCardNavigation"
+      },
+      "dependencies": [
+        "@ds-mo/ui",
+        "@ds-mo/tokens",
+        "@ds-mo/icons"
+      ],
+      "componentDependencies": [
+        "icon",
+        "text"
+      ]
+    },
     {
       "id": "component:ds-card-overview",
       "tag": "ds-card-overview",
@@ -2635,6 +2790,120 @@
         "text"
       ]
     },
+    {
+      "id": "component:ds-card-settings-scope",
+      "tag": "ds-card-settings-scope",
+      "name": "card-settings-scope",
+      "title": "CardSettingsScope",
+      "summary": "Compact, theme-aware settings context card with inline product-area and profile menu triggers.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "general",
+        "status": "stable",
+        "summary": "Compact, theme-aware settings context card with inline product-area and profile menu triggers.",
+        "useWhen": [
+          "A settings workspace needs to show and change both its product area and the organization or profile being managed."
+        ],
+        "avoidWhen": [
+          "The content is a reporting period and metrics summary; use CardOverview.",
+          "The card edits settings in place; use CardSetting."
+        ],
+        "commonlyComposedWith": [
+          "component:ds-menu",
+          "component:ds-card-setting"
+        ],
+        "accessibility": [
+          "Both scope values are native buttons with popup relationships and controlled expanded state.",
+          "Use the emitted native anchor for menu placement and focus return.",
+          "An empty informational profiles popup uses dialog semantics.",
+          "The shared text-action recipe supplies brand foreground, hover underline, and keyboard focus indication."
+        ],
+        "states": [
+          "The application owns the selected area, profile, available choices, permissions, and empty-state copy.",
+          "The card reports popup requests without changing selection or expanded state.",
+          "The surface follows the active theme rather than imposing always-dark colors."
+        ],
+        "responsiveBehavior": [
+          "The parent owns sticky positioning and shell offsets.",
+          "The compact sentence wraps when space is constrained so both controls remain available."
+        ],
+        "frameworkCaveats": {
+          "angular": [
+            "Import the generated standalone adapter; bind controlled labels and expanded states and handle dsScopeRequest."
+          ]
+        },
+        "references": [
+          {
+            "label": "Storybook examples",
+            "path": "src/wc/components/CardSettingsScope/CardSettingsScope.stories.ts"
+          }
+        ]
+      },
+      "api": {
+        "props": {
+          "areaControls": {
+            "type": "string | undefined",
+            "required": false
+          },
+          "areaExpanded": {
+            "type": "boolean",
+            "required": false
+          },
+          "areaLabel": {
+            "type": "string",
+            "required": false
+          },
+          "forLabel": {
+            "type": "string",
+            "required": false
+          },
+          "managingLabel": {
+            "type": "string",
+            "required": false
+          },
+          "profileControls": {
+            "type": "string | undefined",
+            "required": false
+          },
+          "profileExpanded": {
+            "type": "boolean",
+            "required": false
+          },
+          "profileLabel": {
+            "type": "string",
+            "required": false
+          },
+          "profilePopup": {
+            "type": "'menu' | 'dialog'",
+            "required": false
+          },
+          "scopeLabel": {
+            "type": "string",
+            "required": false
+          }
+        },
+        "events": [
+          {
+            "name": "dsScopeRequest",
+            "detail": "SettingsScopeRequest"
+          }
+        ],
+        "slots": []
+      },
+      "exports": {
+        "customElement": "ds-card-settings-scope",
+        "react": "DsCardSettingsScope",
+        "vue": "DsCardSettingsScope",
+        "angular": "DsCardSettingsScope"
+      },
+      "dependencies": [
+        "@ds-mo/ui",
+        "@ds-mo/tokens"
+      ],
+      "componentDependencies": [
+        "text"
+      ]
+    },
     {
       "id": "component:ds-chart",
       "tag": "ds-chart",
@@ -3911,7 +4180,8 @@
           "Range selection applies the first date immediately as a one-day range; while an end is pending, that selected start retains its bold treatment and hovering or focusing another day paints the rest of the provisional inclusive span faint without emitting a value. A second activation completes an ordered inclusive range and gives both edges the bold treatment. A new activation after completion starts a replacement range.",
           "Selection applies immediately and does not close the popup.",
           "Changing category replaces the option-pane subtree so checkbox and other option visuals mount in their new state instead of transitioning from the previous category's row state.",
-          "The trigger reports how many filter categories have selections. footerLayout=summary adds a full-width selected-count footer only while values are selected; footerLayout=categories-clear always reserves the category-pane footer height while keeping its inactive divider hidden, then reveals the divider and only its left-aligned Clear action while values are selected."
+          "The trigger reports how many filter categories have selections. footerLayout=summary adds a full-width selected-count footer only while values are selected; footerLayout=categories-clear always reserves the category-pane footer height while keeping its inactive divider hidden, then reveals the divider and only its left-aligned Clear action while values are selected.",
+          "The built-in trigger derives the shared surface-open wash from the rendered popup lifecycle, including closing. For an external trigger, the application owns that relationship and retains the wash until dsAfterClose; selected filter values remain independent."
         ],
         "responsiveBehavior": [
           "The popup defaults to the large menu-width token and clamps to the nearest data-ds-overlay-boundary rectangle or the viewport fallback.",
@@ -3934,6 +4204,10 @@
           {
             "label": "Storybook example",
             "path": "src/wc/components/FilterMenu/FilterMenu.stories.ts"
+          },
+          {
+            "label": "Surface ownership and trigger state",
+            "path": "src/docs/SurfaceOwnership.mdx"
           }
         ]
       },
@@ -4725,6 +4999,7 @@
           "pattern:menu-trigger"
         ],
         "accessibility": [
+          "An empty choice collection can show informational copy in a focusable non-modal dialog instead of rendering a fake disabled action. Escape and Tab retain the normal popup dismissal and anchor-focus behavior.",
           "Anchor the menu to the control that opens it and return focus to that control when the menu closes.",
           "Open with visible initial focus only when the trigger was activated from the keyboard.",
           "Keep disabled items discoverable only when their unavailable state is meaningful.",
@@ -4807,6 +5082,10 @@
             "type": "HTMLElement | undefined",
             "required": false
           },
+          "emptyMessage": {
+            "type": "string",
+            "required": false
+          },
           "initialFocusVisible": {
             "type": "boolean",
             "required": false
@@ -5403,6 +5682,7 @@
         ],
         "states": [
           "The fixed groups are Menu plus current area, followed by Search, Activity, Messages, and Agents.",
+          "The shell may retain Help in the context position while another global tool is selected; context identity and active selection are independent.",
           "Consumers that intentionally group multiple review tools can replace the Activity destination with Inbox.",
           "Selection promotes foreground to primary without painting a selected fill; unselected destinations use tertiary foreground.",
           "Opening Mobile Sheet Nav replaces the Menu glyph with Cross while preserving its accessible name.",
@@ -5475,6 +5755,10 @@
             "type": "string",
             "required": false
           },
+          "primaryDestination": {
+            "type": "'area' | 'help'",
+            "required": false
+          },
           "searchDot": {
             "type": "boolean",
             "required": false
@@ -5552,8 +5836,10 @@
         "states": [
           "Without multiple sections the center renders heading.",
           "With multiple sections the center renders the controlled MobileSectionSwitcher by default or an explicitly requested segmented TabGroup.",
+          "Primary section switching without subordinate navigation uses the viewport-edge sheet. Headers exposing both peer sections and subordinate views retain their two-level navigation.",
           "The segmented presentation uses the shared fill-width TabGroup contract and divides its centered two-thirds top-bar lane equally between options.",
-          "Optional subsections render in a second row and emit dsSubsectionChange without changing the primary section.",
+          "Optional subsections use a second row by default. When navigation already exposes peer sections, local views can sit beside a stable page title in one row; they never replace that title or its semantic heading.",
+          "The combined local-view presentation joins the page identity and selected subsection in one outlined sheet trigger. The semantic heading remains the page identity, while Back and page actions stay outside the trigger.",
           "Sections represent peer destinations at the current navigation level; subsections represent local views beneath the selected page or detail identity.",
           "Brand tone changes surface and foreground without changing geometry or interaction ownership."
         ],
@@ -5602,6 +5888,10 @@
             "type": "string",
             "required": false
           },
+          "subsectionsPlacement": {
+            "type": "'below' | 'inline' | 'combined'",
+            "required": false
+          },
           "subvalue": {
             "type": "string",
             "required": false
@@ -5648,12 +5938,12 @@
       "tag": "ds-mobile-section-switcher",
       "name": "mobile-section-switcher",
       "title": "MobileSectionSwitcher",
-      "summary": "Controlled mobile section chooser showing the current section, adjacent-position hints, and a complete tap menu.",
+      "summary": "Controlled mobile section chooser with a viewport-edge sheet for primary pages and an anchored menu for local views.",
       "intentStatus": "complete",
       "intent": {
         "audience": "specialized",
         "status": "experimental",
-        "summary": "Controlled mobile section chooser showing the current section, adjacent-position hints, and a complete tap menu.",
+        "summary": "Controlled mobile section chooser with a viewport-edge sheet for primary pages and an anchored menu for local views.",
         "useWhen": [
           "A mobile page or tool header must combine current-page identity with ordered peer-section navigation."
         ],
@@ -5670,13 +5960,17 @@
         "accessibility": [
           "The trigger exposes the current section, popup relationship, and expanded state.",
           "Decorative previous and next position hints are hidden from assistive technology.",
-          "The menu is always available so a future swipe gesture is never the only navigation mechanism.",
+          "The sheet is a native modal top-layer dialog: background content is inert, Escape and backdrop dismiss it, and focus returns to the trigger after exit motion. Arrow keys, Home, End, and initial-letter navigation move among enabled destinations.",
+          "The sheet initially focuses the current enabled destination, uses emphasis for selection, and never adds decorative icons to its rows.",
           "Peer destinations use menuitem semantics with aria-current on the active page; they do not present a radio-control affordance."
         ],
         "states": [
           "Selection is controlled and dsChange reports intent without mutating value.",
           "Dividers group menu items but never participate in previous or next resolution.",
-          "The first and last selectable sections expose only the available neighboring direction."
+          "The anchored local-view menu retains its neighboring-direction hints; the primary-page sheet uses an unfilled perimeter trigger without hints.",
+          "A sheet trigger can combine stable page identity and the current local view, separated by a decorative middle dot. The whole control opens only the supplied local destinations; long page names truncate before crowding out the active view.",
+          "Sheet selection emits navigation intent immediately while exit motion runs independently, so the controlled title can update without waiting for dismissal. Removing the owner or hiding its header closes the top layer without leaving the application blocked.",
+          "The trigger automatically retains the shared surface-open pressed wash through menu or sheet exit. Selecting a destination remains separate from owning the open surface."
         ],
         "responsiveBehavior": [
           "Use only in the dedicated mobile header presentation."
@@ -5685,6 +5979,10 @@
           {
             "label": "Storybook",
             "path": "src/wc/components/MobileSectionSwitcher/MobileSectionSwitcher.stories.ts"
+          },
+          {
+            "label": "Surface ownership and trigger state",
+            "path": "src/docs/SurfaceOwnership.mdx"
           }
         ]
       },
@@ -5694,6 +5992,14 @@
             "type": "string",
             "required": false
           },
+          "pageLabel": {
+            "type": "string",
+            "required": false
+          },
+          "presentation": {
+            "type": "'menu' | 'sheet'",
+            "required": false
+          },
           "sections": {
             "type": "TabItem[]",
             "required": false
@@ -5757,7 +6063,10 @@
           "Escape requests dismissal and opening moves focus to the selected or first available area."
         ],
         "states": [
-          "Dashboard and Settings change only the flat destination collection being browsed.",
+          "Dashboard and Settings change only the destination collection being browsed.",
+          "In nested mode, parents with child routes disclose inline without navigating. Only selecting a child emits route intent; parents without children retain direct navigation.",
+          "Nested branches use the same positional divider and staggered child motion as expanded desktop navigation, without adding disclosure chevrons. Dividers separate an expanded branch from its siblings, not from the outside edge of its group.",
+          "Opening the sheet reveals the current route's branch. Collapsed child groups are inert and hidden from assistive technology while the shared navigation motion runs; child targets keep the mobile row density.",
           "Area, Help, and Account events express intent while the application owns navigation and product behavior.",
           "Set routeSelectionActive to false while a global tool owns the mobile stage so the underlying router URL remains available without marking its area current.",
           "Set showAccount to false when account and user preferences already live in the supplied Settings navigation."
@@ -5809,6 +6118,10 @@
             "type": "boolean",
             "required": false
           },
+          "presentation": {
+            "type": "PanelNavPresentation",
+            "required": false
+          },
           "routeSelectionActive": {
             "type": "boolean",
             "required": false
@@ -5838,6 +6151,10 @@
           {
             "name": "dsClose",
             "detail": "void"
+          },
+          {
+            "name": "dsNavChildSelect",
+            "detail": "PanelNavChildSelectDetail"
           }
         ],
         "slots": []
@@ -6247,9 +6564,10 @@
           "Dashboard presents day-to-day operational destinations; Settings presents administrative and configuration destinations.",
           "The standard footer switches the entire destination collection and navStyle between Dashboard and Settings and exposes the user/account entry.",
           "The host owns the external user menu opened from dsNavUserAction.",
-          "While the external user menu is open or closing, accountMenuExpanded keeps its trigger visibly pressed without applying selected-destination foreground treatment in either expanded or collapsed presentation.",
+          "While the external user menu is open or closing, accountMenuSurfaceOpen keeps its trigger visibly pressed without applying selected-destination foreground treatment in either expanded or collapsed presentation.",
           "Item and header controls inherit the shared md control radius while local shell geometry continues to own collapsed layout and footer animation positioning.",
-          "On desktop, allow user-controlled expand and collapse and persist the preference with storageKey when cross-session persistence is appropriate."
+          "On desktop, allow user-controlled expand and collapse and persist the preference with storageKey when cross-session persistence is appropriate.",
+          "Flyout triggers automatically hold the shared surface-open wash through exit; expanded inline branches do not. For the external account surface, the application supplies accountMenuSurfaceOpen for its rendered lifetime and keeps accountMenuExpanded tied to disclosure semantics."
         ],
         "responsiveBehavior": [
           "At 1200px and wider, default to expanded, allow the user to expand or collapse, and restore the locally persisted desktop preference when available.",
@@ -6287,6 +6605,10 @@
           {
             "label": "Application shell composition",
             "path": "agent/patterns/application-shell/pattern.agent.json"
+          },
+          {
+            "label": "Surface ownership and trigger state",
+            "path": "src/docs/SurfaceOwnership.mdx"
           }
         ]
       },
@@ -6300,6 +6622,10 @@
             "type": "boolean",
             "required": false
           },
+          "accountMenuSurfaceOpen": {
+            "type": "boolean | undefined",
+            "required": false
+          },
           "activeChildId": {
             "type": "string",
             "required": false
@@ -6591,7 +6917,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."
@@ -6600,6 +6927,10 @@
           {
             "label": "Standalone examples",
             "path": "src/wc/components/PanelToolHeader/PanelToolHeader.stories.ts"
+          },
+          {
+            "label": "Surface ownership and trigger state",
+            "path": "src/docs/SurfaceOwnership.mdx"
           }
         ]
       },
@@ -6633,6 +6964,10 @@
             "type": "boolean",
             "required": false
           },
+          "menuSurfaceOpen": {
+            "type": "boolean | undefined",
+            "required": false
+          },
           "menuTriggerId": {
             "type": "string",
             "required": false
@@ -6713,7 +7048,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."
@@ -6736,6 +7072,10 @@
           {
             "label": "Storybook examples",
             "path": "src/wc/components/PanelToolSearch/PanelToolSearch.stories.ts"
+          },
+          {
+            "label": "Surface ownership and trigger state",
+            "path": "src/docs/SurfaceOwnership.mdx"
           }
         ]
       },
@@ -6765,6 +7105,10 @@
             "type": "boolean",
             "required": false
           },
+          "filterSurfaceOpen": {
+            "type": "boolean | undefined",
+            "required": false
+          },
           "filterTriggerId": {
             "type": "string",
             "required": false
@@ -6908,7 +7252,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.",
@@ -6947,6 +7292,10 @@
           {
             "label": "Application shell composition",
             "path": "agent/patterns/application-shell/pattern.agent.json"
+          },
+          {
+            "label": "Surface ownership and trigger state",
+            "path": "src/docs/SurfaceOwnership.mdx"
           }
         ]
       },
@@ -7539,7 +7888,7 @@
           "Create sections only for categories that are meaningful to customers, not merely to break a long list into arbitrary chunks.",
           "When any option supplies subtext, every row uses the same subtext structure and missing values render an em dash. Subtext should disambiguate or add decision-helpful information.",
           "Option labels and the selected trigger label stay on one line and truncate when constrained. Option subtext may wrap to at most two lines.",
-          "Use an option action only for a contextual menu about that user-managed option. The fixed ellipsis action appears on hover, keyboard activity, focus, and touch; expanded keeps it visible while its controlled menu is open. Activating it emits dsOptionAction without selecting the option or closing the Select popup.",
+          "Use an option action only for a contextual menu about that user-managed option. The fixed ellipsis action appears on hover, keyboard activity, focus, and touch; surfaceOpen keeps it visible while its controlled menu is rendered. Activating it emits dsOptionAction without selecting the option or closing the Select popup.",
           "Use option subtextActions for a compact set of immediate actions that belong to one option. They render beneath only that option's label using the standard supporting-text inset and rhythm, use action or negative semantic color, and emit dsOptionSubtextAction without selecting the option or closing the popup. Unlike descriptive subtext, they do not reserve a blank supporting line on neighboring options.",
           "The optional prefix icon and trailing indicator always use the parent surface's secondary foreground color, including when a selected value promotes the label to primary. When collapseLabel compact icon-only chrome is active, a selected value promotes the prefix icon to primary instead. The default down indicator communicates disclosure; up-down is reserved for compact value steppers such as pagination page size.",
           "While the popup is open, the trigger holds the pressed interaction wash without changing its resting foreground or selected-value treatment.",
@@ -7553,7 +7902,8 @@
           "The error trigger uses a 1.5px bold-negative inset stroke so invalid state remains distinguishable from the normal 1px border without changing control geometry. Set hasBorder to false for chrome where the trigger must remain borderless at rest, when selected or focused, and when invalid; error semantics and supporting copy remain available.",
           "An initially empty option set is not an expected Select use case. The no-results state describes a search with no matches, not a source with no choices.",
           "Use options for a flat list or sections for grouped choices; when sections are present they take precedence.",
-          "The background prop describes the actual parent surface and uses the same surface set as ButtonUnfilled."
+          "The background prop describes the actual parent surface and uses the same surface set as ButtonUnfilled.",
+          "Select owns its associated popup and automatically retains the shared surface-open pressed wash. Consumers do not synchronize a second flag for the built-in picker. Contextual option actions are externally owned: their surfaceOpen state keeps the action visible through the associated menu exit, independently of the selected option."
         ],
         "responsiveBehavior": [
           "Use width fill for form fields and width hug for compact filter bars. Override those defaults only when the owning layout has a clear constraint.",
@@ -7584,6 +7934,10 @@
           {
             "label": "Selection patterns",
             "path": "src/docs/SelectionPatterns.mdx"
+          },
+          {
+            "label": "Surface ownership and trigger state",
+            "path": "src/docs/SurfaceOwnership.mdx"
           }
         ]
       },
@@ -7866,11 +8220,13 @@
           "The optional paperTexture property adds a decorative Paper Design texture layer above the gradient or solid chrome frame; its color values are literal shader inputs rather than design tokens.",
           "Dashboard represents day-to-day operational work while Settings represents administrative and configuration work; route state selects the context.",
           "Replace navigation and pageChrome together from one completed route state.",
-          "When pageChrome.showBack marks a detail depth, mobile chrome keeps the page heading as its identity and presents only local subsections; peer route tabs remain in desktop BarNav rather than replacing the detail heading.",
+          "When pageChrome.showBack marks a detail depth, mobile chrome combines the page heading and active local subsection in one sheet trigger; peer route tabs remain in desktop BarNav rather than replacing the detail identity.",
           "Route-owned ordered page actions drive both BarTitle and MobileHeader. ShellApp forwards one flat page-action id and owns the derived mobile overflow menu so routes do not duplicate menu state or choices.",
+          "Managed mobile Back and page-action controls use the same large touch density as the mobile navigation header without increasing the shared header height.",
           "Managed ShellApp keeps the selected desktop section-navigation presentation and ShellPage present and owns page header stickiness and the content scroller.",
           "Route-owned pageChrome independently selects ShellPage contentInset, page-header seams, scroll compaction, expanded and compact header-divider visibility, and contentSurface. ShellApp forwards them while resolving whether desktop title geometry is page-local or shell-bar-owned.",
-          "The application filters unauthorized destinations, sections, and tools before passing them into shell components."
+          "The application filters unauthorized destinations, sections, and tools before passing them into shell components.",
+          "Application-owned header actions and the account trigger retain surface ownership across shell presentations. Supply surfaceOpen on header actions and accountMenuSurfaceOpen on navigation for rendered surface lifetimes; keep disclosure and selected-route state separate."
         ],
         "responsiveBehavior": [
           "ShellApp owns the fixed system breakpoints and resolves desktop at 1200px and wider, tablet from 768px through 1199px, and mobile below 768px.",
@@ -7879,9 +8235,9 @@
           "On desktop and tablet, panel section navigation replaces BarNav with compact BarTitle; collapsed PanelNav exposes child sections through its anchored flyout.",
           "When panel section navigation moves BarTitle into the shell bar, routed content starts at the standard 32px desktop or 16px tablet gutter and ShellPage reports no page-local sticky-header height.",
           "On mobile, ShellApp hides and inerts desktop chrome, uses a solid primary stage, and composes MobileHeader, MobileSheetNav, ShellTools, and the persistent MobileBarNav around the same application-owned content.",
-          "Changing sectionNavigation never changes mobile chrome; the preference may still be edited by an application Settings page.",
+          "The section-navigation preference also selects mobile navigation: bar preserves flat area selection and the header section picker; panel expands child routes inline in MobileSheetNav and combines the page title with any local subsection in one sheet trigger.",
           "Opening MobileSheetNav temporarily overlays the active routed page or global tool; closing it without selecting an area restores that same destination and its nested state. The sheet exposes the router-derived current area only while the routed area owns the mobile stage, so a global tool never leaves an underlying route highlighted.",
-          "Selecting Help from the managed mobile sheet activates the configured Help tool and promotes Help to the primary mobile destination instead of forwarding it as route navigation.",
+          "Selecting Help from the managed mobile sheet activates the configured Help tool and retains Help as the primary mobile destination across other tool selections until a routed area is selected or navigation changes. This mobile context does not alter desktop or tablet routing.",
           "Set navigation.showMobileAccount to false when the Settings destination collection already includes account and user preferences.",
           "When a suspended mobile document returns to the foreground, ShellApp refreshes the complete stage paint layer without remounting routed content or tool owners.",
           "When the application enables viewport-fit=cover, ShellApp reserves the shared top safe-area inset once for the complete mobile stage; nested routed, sheet, and tool headers must not add a second top inset.",
@@ -7929,6 +8285,10 @@
           {
             "label": "Application shell contract",
             "path": "agent/patterns/application-shell/pattern.agent.json"
+          },
+          {
+            "label": "Surface ownership and trigger state",
+            "path": "src/docs/SurfaceOwnership.mdx"
           }
         ]
       },
@@ -8287,7 +8647,8 @@
           "Items with mobileDestination inbox map to one mobile Inbox destination while retaining the actual active tool id; the canonical recipe exposes Activity directly and keeps Inbox grouping opt-in.",
           "Stable tool ids own named slots; label, order, rail placement, shortcut, and mobile destination are explicit item data.",
           "Application-owned rail accessories are forwarded unchanged to PanelTools on desktop and tablet and remain independent from activeTool and open.",
-          "Switching responsive mode must not recreate application-owned slotted product elements."
+          "Switching responsive mode must not recreate application-owned slotted product elements.",
+          "Header actions forward application-owned surfaceOpen through each presentation, independently of expanded semantics and pressed toggles."
         ],
         "responsiveBehavior": [
           "Desktop and tablet compose PanelTools-compatible rail and drawer chrome.",
@@ -8313,6 +8674,10 @@
           {
             "label": "PanelTools contract",
             "path": "src/wc/components/PanelTools/PanelTools.agent.json"
+          },
+          {
+            "label": "Surface ownership and trigger state",
+            "path": "src/docs/SurfaceOwnership.mdx"
           }
         ]
       },
@@ -9268,7 +9633,8 @@
           "Row selection owns the single sticky start lane. One explicitly sized application column can own the sticky end lane, or the start lane when selection is absent. Each sticky boundary owns one fixed divider and a row-clipped directional shadow that paints into the adjacent scrolling columns only while more inline content remains beyond that edge.",
           "Cells accept scalar content, standard primary-and-secondary or dual-primary text primitives, declarative Tag, wrapping multiple-Tag content, icon-only, icon-and-text, 16:9 Image, or ButtonUnfilled Action content, or explicit Empty and Blank absence values. Text objects may declare an optional href (and target) on the primary track only; the table renders a native anchor with the shared brand text-action treatment when the URL is safe, and leaves scalars unlinked. Standard secondary copy defaults to the secondary foreground and may declare a semantic Text color when the application data carries intent; an optional tertiary track uses the same subdued body-small recipe as secondary. Secondary and tertiary may also be a short list of colorable runs, rendered on one line with the table's middle-dot separator. A run may supply help to add the shared dotted underline and a bottom-start Tooltip when compact visible copy summarizes supplementary details; explicit line breaks create a compact unbulleted list without obscuring the current cell's earlier tracks. Dual-primary copy keeps both tracks primary unless explicitly colored and does not gain a tertiary track. Body data cells share 8px outer padding; header and group rows keep their own geometry. Text tracks, including Empty, keep 4px inline padding so copy lines up with column-header labels; Tag and icon-only tracks stay on the 8px cell chrome alone. Icon-and-text cells (`kind: 'icon-text'`) place one md prefix icon beside the same copy stack as a text cell. The icon slot takes 2px padding on every side, then a 2px flex gap before the copy; text-track padding stays on the copy. Omit iconLabel when the glyph is decorative. 20px content (body-medium text, md icon, and the row checkbox) sits in a 24px track so it stays optically aligned with 24px Tag and Action content. Single-track text, selection, tag-only, icon-only, icon-and-text, Action, Empty, Blank, and 1-track Image cells resolve a 40px base contract while two-track cells grow to 64px and three-track cells grow to 88px. Every later track adds 24px, so four tracks resolve to 112px, five to 136px, and the sequence may continue. Tracks stack with no gap. Wrapping primary on a 1-track cell uses that same rhythm: two wrapped lines share the 64px row and three wrapped lines share the 88px row. Wrapping secondary keeps primary on the first track and consumes later tracks: two secondary lines share the 88px row and three secondary lines share a 112px fourth track. Keep the same track count in every row of a table or group when those rows should share one height. Tag cells use the inset Tag recipe: md double-inset is a 24px control for tag-only and tag-with-text, while text-with-tag uses sm single-inset at 20px so the second-track pill sits in the same 24px lane. Multiple-Tag cells use `kind: 'tags'`, a positive `tracks` count, and small single-inset Tags that wrap naturally at the column edge. Each wrap line is a 24px track with no stack gap, matching text. The tallest cell establishes the native row height, so all sibling cells match even at four, five, or more tracks; virtual tables use the declared count as the initial estimate and measure responsive wrapping after paint. Action cells primarily use an icon-only Ellipses treatment, render a 24px small ButtonUnfilled, default to unbordered, and emit row, column, and action identities through dsCellAction. When an action cell declares items, that Ellipses trigger opens the shared ds-menu for commands, dividers, inactive rows, and destructive rows instead of emitting on click; choosing a command emits dsCellAction with that item's actionId. Omit items to keep a single-shot control. Image cells declare tracks 1, 2, or 3 so the 16:9 bordered preview fills that body-row content box (cell height minus 8px padding) and the column hugs the resulting width; omit tracks for the 1-track recipe, and keep image tracks aligned with the other cells in the table or group. Image cells fall back to an accessible placeholder when no source is supplied. Empty means the data applies but has no value and renders an em dash with localized assistive text; Blank means the data is not applicable and renders no content. Nullish values remain backward-compatible Empty values. Stable type, variant, and track-count hooks keep every cell family independently styleable.",
           "Score-and-text cells (`kind: score-text`) place the small 24px safety score at the top-right of the cell while the same one-, two-, or three-track copy stack as a standard text cell fills from the start edge. The score is top-aligned with the first text track, adds no inner padding, and defaults its accessible name prefix to Safety score. Score-and-text loading geometry uses the matching small score skeleton and declared copy tracks.",
-          "The public @ds-mo/ui/table.css export is the authoritative zero-specificity visual recipe. Override its --ds-table-* properties or target its stable element classes for product-specific styling."
+          "The public @ds-mo/ui/table.css export is the authoritative zero-specificity visual recipe. Override its --ds-table-* properties or target its stable element classes for product-specific styling.",
+          "Use surfaceOpenRowId to identify the interactive row associated with a visible detail panel or other contextual surface. The application owns opening, same-row toggling, switching records, and closing; retain the identity through exit motion, then clear it. Move it when panel navigation changes the displayed record. This pressed wash spans sticky and scrolling cells, follows stable row identity through virtualization, and never checks a checkbox or changes selectedRowIds. Group expansion remains an inline disclosure."
         ],
         "responsiveBehavior": [
           "The table keeps native semantics at narrow widths and scrolls horizontally instead of transforming into cards.",
@@ -9311,6 +9677,10 @@
           {
             "label": "Menu trigger composition",
             "path": "agent/patterns/menu-trigger/pattern.agent.json"
+          },
+          {
+            "label": "Surface ownership and trigger state",
+            "path": "src/docs/SurfaceOwnership.mdx"
           }
         ]
       },
@@ -9540,6 +9910,10 @@
             "type": "boolean",
             "required": false
           },
+          "surfaceOpenRowId": {
+            "type": "string | undefined",
+            "required": false
+          },
           "totalCount": {
             "type": "number | undefined",
             "required": false
@@ -9845,7 +10219,8 @@
         "states": [
           "options and grouping are controlled. A data option may supply product-owned orderOptions; otherwise Order defaults to Ascending and Descending. dsGroupChange reports a complete TableGroupingState and dsClear requests null grouping without mutating either input.",
           "Selecting a new data point starts at its first custom order option, or ascending when it has no custom order options. Re-selecting the active data point preserves its complete order state.",
-          "Selecting a data point or direction applies immediately and leaves the dialog open so the other pane can be changed."
+          "Selecting a data point or direction applies immediately and leaves the dialog open so the other pane can be changed.",
+          "The grouping picker automatically holds the shared surface-open wash through exit. Opening this picker is separate from expanding an inline table group."
         ],
         "responsiveBehavior": [
           "Use in the trailing region of ds-table-toolbar.",
@@ -9871,6 +10246,10 @@
           {
             "label": "Toolbar composition owner",
             "path": "src/wc/components/TableToolbar/TableToolbar.agent.json"
+          },
+          {
+            "label": "Surface ownership and trigger state",
+            "path": "src/docs/SurfaceOwnership.mdx"
           }
         ]
       },
@@ -9971,7 +10350,8 @@
         "states": [
           "views, value, and dirty are controlled. Dirty state is presented only for a selected custom view; the default template never shows the trigger dot or save/discard actions even if dirty is supplied. Selection, create, save, discard, rename, and remove events communicate intent and never mutate application records.",
           "The component owns only transient interaction state: the contextual menu, naming dialog, draft name, duplicate-name validation, and focus restoration.",
-          "The default view is a non-editable template. Application-owned custom views appear in a separate section with Rename and Remove actions. New view opens the naming dialog. When an editable selected view is dirty, that view row shows Save and negative Discard supporting actions while the footer remains dedicated to New view. The application decides which table state to capture, restore, and persist."
+          "The default view is a non-editable template. Application-owned custom views appear in a separate section with Rename and Remove actions. New view opens the naming dialog. When an editable selected view is dirty, that view row shows Save and negative Discard supporting actions while the footer remains dedicated to New view. The application decides which table state to capture, restore, and persist.",
+          "The built-in picker and contextual option menu each retain their own surface-open treatment. Opening a view menu does not select that view."
         ],
         "responsiveBehavior": [
           "The control remains a single toolbar item and relies on Select, Menu, and Modal collision and viewport behavior. Its trigger hugs short view names and is capped at the compact menu-width token so long names truncate while the dirty dot stays visible. Its choice popup keeps that same token as the minimum width.",
@@ -9996,6 +10376,10 @@
           {
             "label": "Toolbar composition owner",
             "path": "src/wc/components/TableToolbar/TableToolbar.agent.json"
+          },
+          {
+            "label": "Surface ownership and trigger state",
+            "path": "src/docs/SurfaceOwnership.mdx"
           }
         ]
       },
@@ -10123,7 +10507,8 @@
           "Selected scopes render as neutral md Chips using the double-inset recipe so they remain 24px high inside the 32px md search control and each can be removed directly.",
           "Backspace edits a non-empty field-picker query, then closes the open slash listbox when that query is empty. When the table query is empty and the listbox is already closed, the next Backspace removes the last selected field. Ordinary Backspace edits table query text when the listbox is closed.",
           "Duplicate, blank, and unknown field identities are ignored for presentation. Selected fields preserve the consumer's order.",
-          "Inactive search leaves the tab order, closes the field listbox, and does not emit query or field changes."
+          "Inactive search leaves the tab order, closes the field listbox, and does not emit query or field changes.",
+          "The field-picker action holds the shared surface-open wash while its listbox is visible; chosen search fields remain independent."
         ],
         "responsiveBehavior": [
           "The control fills the available inline size supplied by the table toolbar search slot. Selected Chips and the editable query share one horizontal editor lane so the md control does not grow vertically.",
@@ -10150,6 +10535,10 @@
           {
             "label": "Toolbar composition owner",
             "path": "src/wc/components/TableToolbar/TableToolbar.agent.json"
+          },
+          {
+            "label": "Surface ownership and trigger state",
+            "path": "src/docs/SurfaceOwnership.mdx"
           }
         ]
       },
@@ -10271,7 +10660,8 @@
           "columns and sort are controlled. dsSortChange reports the next TableSortState and never mutates those inputs. The same sort object is what column headers emit through the table.",
           "Selecting a different data field keeps the current direction, or starts ascending when no sort exists. Selecting a direction applies it to the current field, or to the first sortable field when no sort exists. Selecting the already-active field or direction is a no-op and does not toggle the way a header click does.",
           "The trigger stays Sort in regular-weight resting secondary chrome. Field and direction selection live in the menu and on column headers, so the trigger never uses active primary emphasis. It keeps pressed interaction paint without physically scaling inside the stable table caption row.",
-          "Compound sortable headers contribute one Data row per segment. Action columns never appear."
+          "Compound sortable headers contribute one Data row per segment. Action columns never appear.",
+          "The trigger automatically holds the shared surface-open wash through menu exit while the selected sort remains independently controlled."
         ],
         "responsiveBehavior": [
           "Place the control in the trailing region of ds-table-toolbar with Filter and Group.",
@@ -10297,6 +10687,10 @@
           {
             "label": "Toolbar composition owner",
             "path": "src/wc/components/TableToolbar/TableToolbar.agent.json"
+          },
+          {
+            "label": "Surface ownership and trigger state",
+            "path": "src/docs/SurfaceOwnership.mdx"
           }
         ]
       },
@@ -10496,7 +10890,8 @@
           "isInset opts into reduced outer geometry only when Tag is nested inside a control of the same density. The default single inset removes 4px overall; insetDepth double removes 8px overall and falls back to single at xs to protect minimum icon geometry. Semantic styling, typography, icons, gaps, radius, and interaction remain unchanged.",
           "Labels stay on one line and truncate only when the owner supplies a maximum width.",
           "Omitted interactive renders static metadata with no focus, event, or suffix. Interactive adds the fixed ChevronUpDown suffix and emits dsClick without toggling expanded internally.",
-          "isInactive disables only the interactive button and applies the shared inactive treatment."
+          "isInactive disables only the interactive button and applies the shared inactive treatment.",
+          "Interactive tags use surfaceOpen for the associated menu lifecycle, including exit motion. This holds the shared pressed wash without changing the intent that describes the metadata value. Static tags never acquire surface ownership."
         ],
         "responsiveBehavior": [
           "The owner selects md, sm, or xs density to match its local layout and owns collection wrapping, overflow, and condensation. Use isInset only for same-density control nesting.",
@@ -10517,6 +10912,10 @@
           {
             "label": "Storybook examples",
             "path": "src/wc/components/Tag/Tag.stories.ts"
+          },
+          {
+            "label": "Surface ownership and trigger state",
+            "path": "src/docs/SurfaceOwnership.mdx"
           }
         ]
       },
@@ -10573,6 +10972,10 @@
           "size": {
             "type": "TagSize",
             "required": false
+          },
+          "surfaceOpen": {
+            "type": "boolean | undefined",
+            "required": false
           }
         },
         "events": [