@ds-mo/ui 12.0.0 → 12.2.0

package/README.md

@@ -94,7 +94,7 @@ All tags are `ds-*` custom elements. Grouped by role (see Storybook for props an
 
 ### Navigation
 - **TabGroup** (horizontal local views), **PanelSubNav** (vertical local views)
-- **ShellApp**, **PanelNav**, **BarNav**, **PanelTools**
+- **ShellApp**, **ShellPage**, **PanelNav**, **BarNav**, **BarTitle**, **BarWorkflow**, **PanelTools**
 
 ### Status & layout
 - **EmptyState**, **Loader**, **Skeleton**, **CardSetting**, **CardDataVizDonut**
@@ -103,6 +103,23 @@ All tags are `ds-*` custom elements. Grouped by role (see Storybook for props an
 
 All styling uses TokoMo CSS custom properties. No hardcoded colors, sizes, or shadows — everything maps to the token system. Components will render unstyled if `@ds-mo/tokens` is not imported.
 
+## Semantic prose
+
+Safe semantic DOM produced by Markdown, CMS, or documentation renderers can use the renderer-neutral prose stylesheet:
+
+```css
+@import '@ds-mo/ui/prose.css';
+```
+
+```html
+<article class="ds-prose">
+  <h2>Summary</h2>
+  <p>Renderer-owned semantic content.</p>
+</article>
+```
+
+The application remains responsible for parsing and content safety. Use `data-ds-prose="off"` on embedded product UI, and wrap wide tables in `.ds-prose__table-scroll`. See the [prose foundation decision](docs/prose-foundation.md).
+
 ## Icon pattern
 
 Components that accept icons use a named `icon` slot:

package/dist/.build-stamp

@@ -1 +1 @@
-1784701897260
+1784783184986

package/dist/agent-patterns.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "1.0.0",
   "package": "@ds-mo/ui",
-  "packageVersion": "12.0.0",
+  "packageVersion": "12.2.0",
   "kind": "patterns",
   "entries": [
     {
@@ -45,6 +45,7 @@
         "The application owns scripted or real transport, immutable response parts, retry, stop, generated titles, and persistence.",
         "User-sent prompts use MessageBubble's user variant and body-medium regular default with secondary foreground; the application does not promote ordinary sent-message copy to body-large.",
         "AgentResponse renders directly in Message without a MessageBubble surface, owns ordered display only, and never reveals private reasoning.",
+        "Markdown parsing and safe node creation belong to the renderer; the renderer-neutral @ds-mo/ui/prose.css surface owns only semantic-tree styling.",
         "Tool-call components display execution state but do not request participant approval."
       ],
       "accessibility": [
@@ -443,7 +444,7 @@
       ],
       "responsiveBehavior": [
         "Let ShellPage select expanded, compact, and constrained variants from its own capacity and scroll position.",
-        "Set primaryAction.collapse to never only when the action must preserve visible hierarchy, such as Save in create and edit flows.",
+        "Set primaryAction.collapse to never only when an ordinary routed-page action must preserve visible hierarchy; create and edit workflows use BarWorkflow instead.",
         "Use contentInset none only for deliberately full-bleed products such as maps and canvases.",
         "Place TabGroup inside ShellPage content for inner-page panels; route-level sections remain in BarTitle."
       ],

package/dist/agent.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "1.0.0",
   "package": "@ds-mo/ui",
-  "packageVersion": "12.0.0",
+  "packageVersion": "12.2.0",
   "kind": "components",
   "entries": [
     {
@@ -113,15 +113,20 @@
         ],
         "states": [
           "The owner replaces immutable part arrays as scripted or live output changes.",
-          "AgentResponse renders directly in Message without borrowing a plain MessageBubble surface."
+          "AgentResponse renders directly in Message without borrowing a plain MessageBubble surface.",
+          "Markdown parts use the optional safe renderer; prose CSS owns only semantic-tree styling and never response ordering or streaming state."
         ],
         "responsiveBehavior": [
-          "Rich content uses the available transcript width while respecting readable measure and overflow constraints."
+          "Rich content uses the available transcript width while respecting readable measure and local overflow constraints."
         ],
         "references": [
           {
-            "label": "Storybook examples",
-            "path": "src/wc/components/MessageScroller/MessageScroller.stories.ts"
+            "label": "Representative streamed response",
+            "path": "src/wc/components/AgentResponse/AgentResponse.stories.ts"
+          },
+          {
+            "label": "Prose distribution decision",
+            "path": "docs/prose-foundation.md"
           }
         ]
       },
@@ -414,7 +419,7 @@
         "status": "experimental",
         "summary": "Compact icon avatar for visually identifying a person, group, channel, or conversation type.",
         "useWhen": [
-          "A list or message composition needs a consistent 32px circular identity marker represented by an icon."
+          "A list or message composition needs a consistent circular identity marker represented by an icon at md, sm, or xs control density."
         ],
         "avoidWhen": [
           "The identity has a supplied photograph, initials, presence state, or editable profile behavior; those variants are not part of this primitive."
@@ -425,10 +430,11 @@
         ],
         "accessibility": [
           "Provide label only when the icon communicates meaning that surrounding text does not already convey.",
-          "Omit label when the owning row or message already provides an equivalent accessible name."
+          "Omit label when the owning row or message already provides an equivalent accessible name.",
+          "Treat primary and secondary as general icon hierarchy; an owning product may map that hierarchy to states such as unread and read, but Avatar does not own those states."
         ],
         "responsiveBehavior": [
-          "The avatar keeps its fixed 32px circle and 20px icon at every viewport size."
+          "The selected size stays fixed across viewports: md is a 32px circle with a 20px icon, sm is 24px with 16px, and xs is 16px with 12px."
         ],
         "references": [
           {
@@ -450,6 +456,10 @@
           "label": {
             "type": "string | undefined",
             "required": false
+          },
+          "size": {
+            "type": "AvatarSize",
+            "required": false
           }
         },
         "events": [],
@@ -767,16 +777,16 @@
       "tag": "ds-bar-title",
       "name": "bar-title",
       "title": "BarTitle",
-      "summary": "Page-level title chrome with optional Back navigation, supporting description, inline active-section menu, one primary action, grouped overflow actions, and explicit expanded, compact, or constrained variants.",
+      "summary": "Page-level title chrome with optional route navigation, supporting description, inline active-section menu, one primary action, grouped overflow actions, and explicit expanded, compact, or constrained variants.",
       "intentStatus": "complete",
       "intent": {
         "audience": "general",
         "status": "stable",
-        "summary": "Page-level title chrome with optional Back navigation, supporting description, inline active-section menu, one primary action, grouped overflow actions, and explicit expanded, compact, or constrained variants.",
+        "summary": "Page-level title chrome with optional route navigation, supporting description, inline active-section menu, one primary action, grouped overflow actions, and explicit expanded, compact, or constrained variants.",
         "useWhen": [
           "A top-level page needs one h1 above its content.",
           "A list or detail page has multiple route-level sections that belong in the inline active-section menu.",
-          "A detail, create, or edit page needs a page-level Back action.",
+          "A detail page needs a page-level Back action.",
           "A page needs one primary action plus optional secondary or destructive overflow commands."
         ],
         "avoidWhen": [
@@ -787,6 +797,11 @@
           "Automatic sticky or responsive page orchestration is required; compose BarTitle in ShellPage rather than implementing it in the header."
         ],
         "alternatives": [
+          {
+            "when": "A create or edit workflow needs Exit, persistent step navigation, and a final Save or Submit action.",
+            "component": "component:ds-bar-workflow",
+            "reason": "BarWorkflow owns compact-only workflow progression rather than responsive page identity."
+          },
           {
             "when": "The header belongs to a PanelTools product view.",
             "component": "component:ds-panel-tool-header",
@@ -819,8 +834,8 @@
           "Omitting Back, sections, primaryAction, and actions produces the top-level title-only header.",
           "Two or more selectable sections add the inline section trigger; one section does not render a redundant menu.",
           "Dividers in sections or actions create separate Menu groups without becoming selectable rows.",
-          "expanded renders the larger heading, optional description, inset divider, and an xs icon-label Back breadcrumb above a flush-left h1; compact renders 48px chrome with inline Back; constrained uses compact chrome and moves an auto-collapse primary action into overflow.",
-          "primaryAction collapse defaults to auto. Use never for Save-like actions whose hierarchy must remain visible in constrained layouts."
+          "expanded renders the larger heading, optional description, inset divider, and an xs icon-label Back breadcrumb in the top inset. The title and right-side actions share one top alignment whether Back is present, while the description remains in the left title column; compact renders 48px chrome with inline Back; constrained uses compact chrome and moves an auto-collapse primary action into overflow.",
+          "primaryAction collapse defaults to auto. Use never for exceptional actions whose hierarchy must remain visible in constrained layouts."
         ],
         "responsiveBehavior": [
           "BarTitle does not observe viewport, shell, scroll, or container state. Its owner selects an explicit variant.",
@@ -943,6 +958,164 @@
         "tooltip"
       ]
     },
+    {
+      "id": "component:ds-bar-workflow",
+      "tag": "ds-bar-workflow",
+      "name": "bar-workflow",
+      "title": "BarWorkflow",
+      "summary": "Compact bold-brand create/edit workflow chrome with Exit, controlled previous and next step navigation, and a final Save or Submit action.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "general",
+        "status": "stable",
+        "summary": "Compact bold-brand create/edit workflow chrome with Exit, controlled previous and next step navigation, and a final Save or Submit action.",
+        "useWhen": [
+          "A create or edit flow needs persistent page-level Exit and step navigation.",
+          "A single-step form needs the same compact workflow chrome and final Save or Submit action.",
+          "Next or Submit must remain visible while the application owns validation and the current step."
+        ],
+        "avoidWhen": [
+          "The header identifies a routed page, list, or detail view; use BarTitle instead.",
+          "The steps must be visibly enumerated or expose progress; BarWorkflow uses steps only to resolve its navigation controls.",
+          "The header belongs to a PanelTools drawer or fullscreen pane; use PanelToolHeader through PanelTools instead.",
+          "The interaction is a local wizard inside page content rather than page-level workflow chrome."
+        ],
+        "alternatives": [
+          {
+            "when": "A routed page needs responsive title, section, Back, and page-action presentations.",
+            "component": "component:ds-bar-title",
+            "reason": "BarTitle owns page identity and capacity variants rather than workflow progression."
+          },
+          {
+            "when": "The workflow belongs to a tool drawer or fullscreen tool pane.",
+            "component": "component:ds-panel-tool-header",
+            "reason": "PanelToolHeader owns tool-pane navigation and actions within PanelTools."
+          }
+        ],
+        "commonlyComposedWith": [
+          "component:ds-shell-page",
+          "component:ds-button-filled",
+          "component:ds-button-unfilled",
+          "component:ds-text",
+          "component:ds-tooltip"
+        ],
+        "patterns": [],
+        "accessibility": [
+          "Provide one concise workflow heading; BarWorkflow renders exactly one h1 and appends the controlled current-step count as heading · X/N only for multi-step workflows.",
+          "Provide a workflow-specific Exit accessible name that describes the consequence or destination.",
+          "Give every step a stable id and concise label even though step labels are not rendered as visible progress.",
+          "Previous is omitted on the first step; it appears from step two onward. Next remains visible on intermediate steps and becomes the final labeled Check action on the last step.",
+          "Use submitAction.type=submit inside a form so the final action preserves native submission semantics."
+        ],
+        "states": [
+          "BarWorkflow always renders compact 48px bold-brand chrome and has no expanded, constrained, or responsive variant.",
+          "An unrecognized value resolves navigation from the first step without mutating the controlled value.",
+          "The first step omits Previous. Intermediate steps show Previous and Next. The last step replaces Next with the Check Save or Submit action.",
+          "The default empty steps array is a single-step flow with the plain heading, no Previous control, and the final action visible. An explicit one-step array behaves the same way.",
+          "isNextInactive blocks forward navigation while preserving the Next control; the target step's isInactive state also blocks entry.",
+          "submitAction owns the final label, native button type, inactive state, and loading state."
+        ],
+        "responsiveBehavior": [
+          "BarWorkflow does not expose a presentation variant and never collapses its navigation actions.",
+          "The heading truncates before Exit, Previous, and Next or Submit lose their complete hit targets.",
+          "When slotted into ShellPage, BarWorkflow remains compact while ShellPage continues to provide sticky placement."
+        ],
+        "frameworkCaveats": {
+          "customElements": [
+            "Assign steps and submitAction as JavaScript properties and replace their identities when controlled state changes.",
+            "Update value after dsStepChange, handle dsExit in the workflow owner, and use dsSubmit only when product behavior supplements native form submission."
+          ],
+          "react": [
+            "Pass steps and submitAction directly to DsBarWorkflow and keep value controlled in the workflow route.",
+            "Place DsBarWorkflow in DsShellPage with slot=header when sticky page placement is required."
+          ],
+          "angular": [
+            "Bind steps and submitAction on the standalone DsBarWorkflow adapter and update value from dsStepChange.",
+            "Place ds-bar-workflow in ds-shell-page with slot=header and keep the form or router outlet in ShellPage content."
+          ]
+        },
+        "references": [
+          {
+            "label": "Workflow states and controlled navigation",
+            "path": "src/wc/components/BarWorkflow/BarWorkflow.stories.ts"
+          },
+          {
+            "label": "Cross-browser workflow behavior",
+            "path": "tests/e2e/bar-workflow.spec.ts"
+          }
+        ]
+      },
+      "api": {
+        "props": {
+          "exitAriaLabel": {
+            "type": "string",
+            "required": false
+          },
+          "exitLabel": {
+            "type": "string",
+            "required": false
+          },
+          "heading": {
+            "type": "string",
+            "required": true
+          },
+          "isNextInactive": {
+            "type": "boolean",
+            "required": false
+          },
+          "nextLabel": {
+            "type": "string",
+            "required": false
+          },
+          "previousLabel": {
+            "type": "string",
+            "required": false
+          },
+          "steps": {
+            "type": "BarWorkflowStep[]",
+            "required": false
+          },
+          "submitAction": {
+            "type": "BarWorkflowSubmitAction",
+            "required": false
+          },
+          "value": {
+            "type": "string",
+            "required": false
+          }
+        },
+        "events": [
+          {
+            "name": "dsExit",
+            "detail": "MouseEvent"
+          },
+          {
+            "name": "dsStepChange",
+            "detail": "string"
+          },
+          {
+            "name": "dsSubmit",
+            "detail": "MouseEvent"
+          }
+        ],
+        "slots": []
+      },
+      "exports": {
+        "customElement": "ds-bar-workflow",
+        "react": "DsBarWorkflow",
+        "angular": "DsBarWorkflow"
+      },
+      "dependencies": [
+        "@ds-mo/ui",
+        "@ds-mo/tokens"
+      ],
+      "componentDependencies": [
+        "button-filled",
+        "button-unfilled",
+        "text",
+        "tooltip"
+      ]
+    },
     {
       "id": "component:ds-button-filled",
       "tag": "ds-button-filled",
@@ -2498,12 +2671,12 @@
       "tag": "ds-conversation-list",
       "name": "conversation-list",
       "title": "ConversationList",
-      "summary": "Scrollable conversation-list region with dedicated empty and floating-action placement.",
+      "summary": "Scrollable conversation-list region with dedicated empty and persistent action placement.",
       "intentStatus": "complete",
       "intent": {
         "audience": "general",
         "status": "experimental",
-        "summary": "Scrollable conversation-list region with dedicated empty and floating-action placement.",
+        "summary": "Scrollable conversation-list region with dedicated empty and persistent action placement.",
         "useWhen": [
           "A messaging-like surface needs a reusable history list with empty and action regions."
         ],
@@ -2513,17 +2686,24 @@
         "commonlyComposedWith": [
           "component:ds-conversation-list-section",
           "component:ds-conversation-list-item",
-          "component:ds-empty-state"
+          "component:ds-empty-state",
+          "component:ds-scroll-overlay"
         ],
         "patterns": [
           "pattern:conversation"
         ],
         "accessibility": [
           "Provide an accessible list label through the surrounding heading or region.",
-          "Keep the empty message descriptive and the floating action explicitly named."
+          "Keep the empty message descriptive and every persistent action explicitly named."
+        ],
+        "states": [
+          "The default floating action stays at the lower end corner.",
+          "actionLayout footer stretches a long action between 8px side and bottom insets.",
+          "Both action layouts share the always-active scroll-overlay fade controller, reserve measured end clearance, and begin fading 8px before the visible action.",
+          "ConversationList paints its measured fade on a separate surface-aware layer so contextual row actions retain a real backdrop for blur; hovered, focused, and menu-open rows rise above that decorative fade."
         ],
         "responsiveBehavior": [
-          "The list fills its owner, scrolls independently, and keeps its action at the lower end corner."
+          "The list fills its owner, scrolls independently, and keeps its persistent action above scrolling rows."
         ],
         "references": [
           {
@@ -2533,7 +2713,12 @@
         ]
       },
       "api": {
-        "props": {},
+        "props": {
+          "actionLayout": {
+            "type": "ConversationListActionLayout",
+            "required": false
+          }
+        },
         "events": [],
         "slots": []
       },
@@ -2687,7 +2872,7 @@
           "The visible heading labels the section and must describe the relationship shared by its rows."
         ],
         "responsiveBehavior": [
-          "Rows remain full width while the heading stays visible in document order."
+          "Rows remain full width with a 4px gap between adjacent items while the heading stays visible in document order."
         ],
         "references": [
           {
@@ -3508,24 +3693,24 @@
       "tag": "ds-markdown",
       "name": "markdown",
       "title": "Markdown",
-      "summary": "Safe CommonMark and GFM renderer built from parsed nodes without raw HTML injection.",
+      "summary": "Optional safe CommonMark and GFM renderer that emits semantic nodes without raw HTML injection and consumes the shared prose CSS contract.",
       "intentStatus": "complete",
       "intent": {
         "audience": "specialized",
         "status": "experimental",
-        "summary": "Safe CommonMark and GFM renderer built from parsed nodes without raw HTML injection.",
+        "summary": "Optional safe CommonMark and GFM renderer that emits semantic nodes without raw HTML injection and consumes the shared prose CSS contract.",
         "useWhen": [
-          "Trusted or untrusted message text needs headings, lists, links, tables, tasks, quotes, and code."
+          "A serializable Markdown string needs the design system's safe, opinionated renderer for headings, lists, links, tables, tasks, quotes, and code."
         ],
         "avoidWhen": [
+          "The application already owns a safe semantic-DOM renderer and only needs @ds-mo/ui/prose.css.",
           "The application needs arbitrary HTML, custom plugins, or a full document CMS renderer."
         ],
         "commonlyComposedWith": [
-          "component:ds-code-block",
-          "component:ds-message-bubble"
+          "component:ds-agent-response",
+          "component:ds-code-block"
         ],
         "patterns": [
-          "pattern:conversation",
           "pattern:agent-chat"
         ],
         "accessibility": [
@@ -3534,7 +3719,8 @@
           "Link text must remain descriptive in authored content."
         ],
         "states": [
-          "Streaming updates are coalesced to one parse and render per animation frame."
+          "Streaming updates are coalesced to one parse and render per animation frame.",
+          "Typography, rhythm, opt-out, and overflow styling come from the renderer-neutral .ds-prose source rather than a Markdown-only recipe."
         ],
         "responsiveBehavior": [
           "Tables and code scroll horizontally instead of forcing the transcript wider."
@@ -3542,7 +3728,11 @@
         "references": [
           {
             "label": "Storybook examples",
-            "path": "src/wc/components/MessageScroller/MessageScroller.stories.ts"
+            "path": "src/wc/components/AgentResponse/AgentResponse.stories.ts"
+          },
+          {
+            "label": "Prose distribution decision",
+            "path": "docs/prose-foundation.md"
           }
         ]
       },
@@ -3631,14 +3821,14 @@
         "states": [
           "The host owns open state and responds to selection and close events.",
           "Use either flat items or sections, not both.",
-          "After dsSelect from a switch row, update switchValue in the items property so the controlled indicator reflects the new state.",
-          "For selectionMode single, keep exactly one item isSelected and update the items property after dsSelect.",
+          "After dsSelect from a switch row, replace the items or sections array with updated switchValue data so the controlled indicator reflects the new state.",
+          "For selectionMode single, keep exactly one item isSelected and replace the items or sections array after dsSelect; Menu never mutates consumer-owned selection data.",
           "Arrays, objects, and element anchors must be assigned as JavaScript properties.",
           "Use a swatch-picker section for a small curated visual preference and apply dsSwatchSelect immediately without closing the popup; the legacy gradient-picker section and dsGradientSelect remain compatibility-only."
         ],
         "responsiveBehavior": [
           "Keep the default choice-cell anchor alignment so the first or last interactive row edge aligns with its trigger, matching Select; use popup-frame only for deliberate custom frame geometry.",
-          "Choose placement relative to the trigger and allow the component to clamp the popup to the viewport.",
+          "Treat side as the preferred placement. When the popup cannot fit there and the opposite side offers more room, Menu flips on that main axis before clamping the final position to the viewport.",
           "Avoid fixed widths that exceed narrow viewports."
         ],
         "frameworkCaveats": {
@@ -4072,7 +4262,7 @@
           "Selection and transcript interaction release automatic following.",
           "Opening saved history, message jumps, and prepended history preserve deliberate position.",
           "The scroll-to-latest action is absent at the live edge, appears only after the reader moves away, and disappears again after returning to the newest message.",
-          "Place a composer container with 8px padding on every side in the overlay slot so messages scroll behind it; the scroller measures its live height, reserves matching transcript clearance, and keeps scroll-to-latest above it."
+          "Place a composer container with 8px padding on every side in the overlay slot so messages scroll behind it; the shared scroll-overlay controller tracks every composer growth step, reserves matching transcript clearance, begins the fade 8px before the visible composer, and keeps scroll-to-latest above it."
         ],
         "responsiveBehavior": [
           "Transcript width is readable while the scroll region fills available height."
@@ -4781,7 +4971,7 @@
         ],
         "accessibility": [
           "Provide an aria-label that names the searched domain, such as Search agent chats or Search messages.",
-          "The standard search clear action restores focus, exposes its localized name in a tooltip, and emits both the empty query and dsClear.",
+          "The standard search clear action restores focus, uses the concise localized clearLabel by itself for both its tooltip and accessible name, and emits both the empty query and dsClear.",
           "When showFilter is enabled, provide stable filterTriggerId and filterControls values, synchronize filterExpanded with the controlled menu, and restore focus after selection; filterAriaLabel also labels its tooltip."
         ],
         "states": [
@@ -5256,6 +5446,85 @@
         "text"
       ]
     },
+    {
+      "id": "component:ds-scroll-overlay",
+      "tag": "ds-scroll-overlay",
+      "name": "scroll-overlay",
+      "title": "ScrollOverlay",
+      "summary": "Generic scroll owner for content that moves behind a persistent footer action or composer with an always-active alpha fade.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "general",
+        "status": "experimental",
+        "summary": "Generic scroll owner for content that moves behind a persistent footer action or composer with an always-active alpha fade.",
+        "useWhen": [
+          "A bounded region owns scrolling while footer actions remain overlaid and continuously visible.",
+          "The final content must clear a live-height footer while earlier content can move behind it."
+        ],
+        "avoidWhen": [
+          "The footer belongs in normal document flow rather than overlaying content.",
+          "Another component already owns scrolling and cannot delegate its scrollport to this component."
+        ],
+        "commonlyComposedWith": [
+          "component:ds-button-filled",
+          "component:ds-message-composer"
+        ],
+        "accessibility": [
+          "Provide scrollLabel when the scrollport needs its own named, keyboard-focusable region.",
+          "Keep footer actions keyboard accessible and explicitly named; the fade is decorative and never intercepts pointer input."
+        ],
+        "states": [
+          "The alpha mask remains active at every scroll position and moves in content coordinates so it stays pinned behind the footer without masking native scrollbars.",
+          "The component measures the complete overlay for end clearance, measures its visible child for fade depth, and begins the fade 8px before that visible content.",
+          "An md 32px footer action with 8px bottom inset therefore produces a 48px fade; variable-height composers produce a correspondingly taller measured fade."
+        ],
+        "responsiveBehavior": [
+          "The scrollport and overlay fill the available width and height; the owner supplies responsive sizing and overlay insets."
+        ],
+        "frameworkCaveats": {
+          "customElements": [
+            "Place scrollable content in the default slot and one footer wrapper in the overlay slot; use dsScroll only when the application needs position data."
+          ],
+          "react": [
+            "Use DsScrollOverlay with ordinary children plus an element carrying slot=\"overlay\"."
+          ],
+          "angular": [
+            "Import DsScrollOverlay and project the persistent footer wrapper with slot=\"overlay\"."
+          ]
+        },
+        "references": [
+          {
+            "label": "Storybook examples",
+            "path": "src/wc/components/ScrollOverlay/ScrollOverlay.stories.ts"
+          }
+        ]
+      },
+      "api": {
+        "props": {
+          "scrollLabel": {
+            "type": "string | undefined",
+            "required": false
+          }
+        },
+        "events": [
+          {
+            "name": "dsScroll",
+            "detail": "ScrollOverlayScrollDetail"
+          }
+        ],
+        "slots": []
+      },
+      "exports": {
+        "customElement": "ds-scroll-overlay",
+        "react": "DsScrollOverlay",
+        "angular": "DsScrollOverlay"
+      },
+      "dependencies": [
+        "@ds-mo/ui",
+        "@ds-mo/tokens"
+      ],
+      "componentDependencies": []
+    },
     {
       "id": "component:ds-select",
       "tag": "ds-select",
@@ -6115,15 +6384,16 @@
       "tag": "ds-shell-page",
       "name": "shell-page",
       "title": "ShellPage",
-      "summary": "The standard routed-page boundary inside ShellApp, owning sticky BarTitle placement, container-aware header variants, stable scroll compaction, and optional page-content inset without creating a nested scroll container.",
+      "summary": "The standard routed-page boundary inside ShellApp, owning sticky BarTitle or BarWorkflow placement, container-aware BarTitle variants, stable scroll compaction, and optional page-content inset without creating a nested scroll container.",
       "intentStatus": "complete",
       "intent": {
         "audience": "general",
         "status": "stable",
-        "summary": "The standard routed-page boundary inside ShellApp, owning sticky BarTitle placement, container-aware header variants, stable scroll compaction, and optional page-content inset without creating a nested scroll container.",
+        "summary": "The standard routed-page boundary inside ShellApp, owning sticky BarTitle or BarWorkflow placement, container-aware BarTitle variants, stable scroll compaction, and optional page-content inset without creating a nested scroll container.",
         "useWhen": [
           "Rendering a standard routed page inside ShellApp's default content region.",
           "BarTitle should expand at a roomy page top, compact after scroll, or use constrained action layout when the page column narrows.",
+          "BarWorkflow needs sticky page-level placement while remaining compact.",
           "Pages need consistent content gutters with an explicit full-bleed option."
         ],
         "avoidWhen": [
@@ -6146,6 +6416,7 @@
         "commonlyComposedWith": [
           "component:ds-shell-app",
           "component:ds-bar-title",
+          "component:ds-bar-workflow",
           "component:ds-tab-group"
         ],
         "patterns": [
@@ -6153,7 +6424,7 @@
         ],
         "accessibility": [
           "ShellPage exposes the routed page as the main landmark; render exactly one active ShellPage inside ShellApp.",
-          "Provide exactly one BarTitle through the header slot so the page has one h1.",
+          "Provide exactly one BarTitle or BarWorkflow through the header slot so the page has one h1.",
           "Keep loading, empty, validation, error, progress, success, and failure communication in the default product-content slot.",
           "Responsive variant changes preserve the same heading, controls, accessible names, and keyboard focus targets."
         ],
@@ -6161,26 +6432,28 @@
           "headerPresentation=auto selects expanded, compact, or constrained from ShellPage's own inline capacity and scroll position.",
           "expanded, compact, and constrained are explicit overrides for exceptional layouts and deterministic examples.",
           "contentInset=default supplies standard page gutters; none permits maps, canvases, and other full-bleed content.",
-          "The required header slot accepts one BarTitle. The default slot owns router output and all page product content."
+          "The required header slot accepts one BarTitle or BarWorkflow. The default slot owns router output and all page product content."
         ],
         "responsiveBehavior": [
           "ShellPage observes its own rendered width instead of viewport media queries or ShellApp desktop/tablet modes.",
           "Roomy pages expand at the top and compact after scroll; medium-capacity pages start compact; narrow pages use the constrained header variant.",
+          "A newly navigated header resolves current page capacity before it is revealed, so persistent tool or navigation chrome cannot flash the expanded presentation first.",
           "Token-based capacity bands use hysteresis so opening tools or resizing navigation cannot oscillate near a boundary.",
           "Scroll compaction preserves the expanded page flow offset so content never jumps beneath the sticky header.",
-          "ShellPage relies on ShellApp's content scroller and never introduces nested scrolling."
+          "ShellPage relies on ShellApp's content scroller and never introduces nested scrolling.",
+          "BarWorkflow remains compact and is not assigned BarTitle's capacity or scroll variants."
         ],
         "frameworkCaveats": {
           "customElements": [
-            "Import ShellPage and BarTitle, place one ds-bar-title in slot=header, and render route content as default children.",
+            "Import ShellPage with BarTitle or BarWorkflow, place one header in slot=header, and render route content as default children.",
             "Do not set BarTitle.variant while ShellPage owns headerPresentation."
           ],
           "react": [
-            "Render DsBarTitle with slot=header inside DsShellPage and keep routed content as the remaining children.",
+            "Render DsBarTitle or DsBarWorkflow with slot=header inside DsShellPage and keep routed content as the remaining children.",
             "Use contentInset none only for deliberately full-bleed page products."
           ],
           "angular": [
-            "Import the generated standalone DsShellPage and DsBarTitle adapters, preserve slot=header, and place router-outlet in the ShellPage default slot.",
+            "Import the generated standalone DsShellPage adapter with DsBarTitle or DsBarWorkflow, preserve slot=header, and place router-outlet in the ShellPage default slot.",
             "Do not add another overflow auto wrapper around the routed page."
           ]
         },