@ds-mo/ui 12.1.0 → 12.2.0

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

@@ -2,7 +2,7 @@
   "$schema": "https://ui.shadcn.com/schema/registry-item.json",
   "name": "conversation-list",
   "title": "ConversationList",
-  "description": "Scrollable conversation-list region with dedicated empty and floating-action placement.",
+  "description": "Scrollable conversation-list region with dedicated empty and persistent action placement.",
   "type": "registry:ui",
   "meta": {
     "library": "@ds-mo/ui",
@@ -13,7 +13,7 @@
     "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."
       ],
@@ -23,17 +23,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": [
         {
@@ -43,12 +50,32 @@
       ]
     },
     "api": {
-      "props": {},
+      "props": {
+        "actionLayout": {
+          "type": "ConversationListActionLayout",
+          "resolvedType": "\"floating\" | \"footer\"",
+          "attribute": "action-layout",
+          "default": "'floating'",
+          "required": false,
+          "mutable": false,
+          "description": "Corner icon action or full-width persistent footer action."
+        }
+      },
       "events": [],
       "methods": [],
       "slots": []
     },
-    "props": {},
+    "props": {
+      "actionLayout": {
+        "type": "ConversationListActionLayout",
+        "resolvedType": "\"floating\" | \"footer\"",
+        "attribute": "action-layout",
+        "default": "'floating'",
+        "required": false,
+        "mutable": false,
+        "description": "Corner icon action or full-width persistent footer action."
+      }
+    },
     "events": [],
     "methods": [],
     "slots": [],
@@ -89,12 +116,12 @@
   "files": [
     {
       "path": "src/wc/components/ConversationList/ConversationList.css",
-      "content": ":host {\n  display: block;\n  width: 100%;\n  height: 100%;\n  min-height: 0;\n  box-sizing: border-box;\n  -webkit-user-select: none;\n  user-select: none;\n}\n\n.conversation-list {\n  position: relative;\n  display: flex;\n  flex-direction: column;\n  width: 100%;\n  height: 100%;\n  min-height: 0;\n  box-sizing: border-box;\n}\n\n.conversation-list__content {\n  position: relative;\n  flex: 1 1 auto;\n  min-height: 0;\n  overflow: auto;\n  padding: var(--dimension-space-100);\n  padding-bottom: calc(var(--dimension-size-600) + var(--dimension-size-100));\n  box-sizing: border-box;\n}\n\n.conversation-list__empty {\n  display: contents;\n}\n\n.conversation-list__actions {\n  position: absolute;\n  right: var(--dimension-space-200);\n  bottom: var(--dimension-space-200);\n  z-index: var(--dimension-z-index-floating);\n}\n\n.conversation-list__actions-surface {\n  display: flex;\n  border-radius: var(--dimension-radius-half);\n  box-shadow: var(--effect-elevation-elevated-md);\n}\n\n.conversation-list__actions-surface:empty {\n  display: none;\n}\n",
+      "content": ":host {\n  display: block;\n  position: relative;\n  width: 100%;\n  height: 100%;\n  min-height: 0;\n  box-sizing: border-box;\n  -webkit-user-select: none;\n  user-select: none;\n}\n\n.conversation-list {\n  position: relative;\n  display: flex;\n  flex-direction: column;\n  width: 100%;\n  height: 100%;\n  min-height: 0;\n  box-sizing: border-box;\n}\n\n.conversation-list__viewport {\n  position: relative;\n  flex: 1 1 auto;\n  min-height: 0;\n  overflow: auto;\n  box-sizing: border-box;\n}\n\n.conversation-list__content {\n  position: relative;\n  min-height: 100%;\n  padding: var(--dimension-space-100);\n  padding-bottom: calc(\n    var(--dimension-space-100) + var(--ds-scroll-overlay-block-size, 0px)\n  );\n  box-sizing: border-box;\n}\n\n.conversation-list__fade {\n  position: absolute;\n  right: 0;\n  bottom: 0;\n  left: 0;\n  z-index: 1;\n  height: var(--ds-scroll-overlay-fade-block-size, 0);\n  pointer-events: none;\n  background-color: var(\n    --ds-scroll-overlay-surface-color,\n    var(--_shell-chrome-bg, var(--color-background-primary))\n  );\n  --ds-scroll-edge-fade-size: 100%;\n}\n\n.conversation-list__fade::before {\n  content: '';\n  position: absolute;\n  inset: 0;\n  background-image: var(\n    --ds-scroll-overlay-surface-image,\n    var(--ds-shell-gradient-image, none)\n  );\n  background-position: var(--ds-scroll-overlay-surface-position, 0 0);\n  background-attachment: fixed;\n  background-size: var(\n    --ds-scroll-overlay-surface-size,\n    var(--ds-shell-gradient-size, auto)\n  );\n  background-repeat: no-repeat;\n  opacity: var(\n    --ds-scroll-overlay-surface-image-opacity,\n    var(--ds-shell-gradient-opacity, 1)\n  );\n}\n\n.conversation-list__empty {\n  display: contents;\n}\n\n.conversation-list__actions {\n  position: absolute;\n  right: 0;\n  bottom: 0;\n  z-index: var(--dimension-z-index-floating);\n  padding: 0 var(--dimension-space-200) var(--dimension-space-200) 0;\n}\n\n.conversation-list__actions--footer {\n  left: 0;\n  padding: 0 var(--dimension-space-100) var(--dimension-space-100);\n}\n\n.conversation-list__actions-surface {\n  display: flex;\n  border-radius: var(--dimension-radius-half);\n  box-shadow: var(--effect-elevation-elevated-md);\n}\n\n.conversation-list__actions--footer .conversation-list__actions-surface {\n  width: 100%;\n}\n\n.conversation-list__actions-surface:empty {\n  display: none;\n}\n",
       "type": "registry:ui"
     },
     {
       "path": "src/wc/components/ConversationList/ConversationList.tsx",
-      "content": "import { Component, h, Host } from '@stencil/core';\n\n@Component({\n  tag: 'ds-conversation-list',\n  styleUrl: 'ConversationList.css',\n  scoped: true,\n})\nexport class ConversationList {\n  render() {\n    return (\n      <Host>\n        <div class=\"conversation-list\">\n          <div class=\"conversation-list__content\">\n            <slot />\n            <div class=\"conversation-list__empty\">\n              <slot name=\"empty\" />\n            </div>\n          </div>\n          <div class=\"conversation-list__actions\">\n            <div class=\"conversation-list__actions-surface\">\n              <slot name=\"actions\" />\n            </div>\n          </div>\n        </div>\n      </Host>\n    );\n  }\n}\n",
+      "content": "import { Component, Element, h, Host, Prop } from '@stencil/core';\nimport { ScrollOverlayController } from '../../utils/scroll-overlay-controller';\n\nexport type ConversationListActionLayout = 'floating' | 'footer';\n\n@Component({\n  tag: 'ds-conversation-list',\n  styleUrl: 'ConversationList.css',\n  styleUrls: ['../../utils/scroll-edge-fade.css'],\n  scoped: true,\n})\nexport class ConversationList {\n  @Element() el!: HTMLElement;\n\n  /** Corner icon action or full-width persistent footer action. */\n  @Prop() actionLayout: ConversationListActionLayout = 'floating';\n\n  private viewport?: HTMLElement;\n  private content?: HTMLElement;\n  private overlay?: HTMLElement;\n  private scrollOverlayController?: ScrollOverlayController;\n  private emptySlotObserver?: MutationObserver;\n\n  componentDidLoad(): void {\n    if (!this.viewport || !this.content || !this.overlay) return;\n    this.scrollOverlayController = new ScrollOverlayController({\n      host: this.el,\n      viewport: this.viewport,\n      content: this.content,\n      overlay: this.overlay,\n      overlayContentSelector: '[slot=\"actions\"]',\n    });\n    this.scrollOverlayController.connect();\n    this.syncEmptyStateLayout();\n    this.emptySlotObserver = new MutationObserver(this.syncEmptyStateLayout);\n    this.emptySlotObserver.observe(this.el, { childList: true, subtree: true });\n  }\n\n  disconnectedCallback(): void {\n    this.scrollOverlayController?.disconnect();\n    this.emptySlotObserver?.disconnect();\n  }\n\n  private syncEmptyStateLayout = (): void => {\n    const emptyState = this.el.querySelector<HTMLElement>('[slot=\"empty\"]');\n    if (emptyState) {\n      emptyState.style.setProperty('position', 'absolute');\n      emptyState.style.setProperty('inset-block-start', '0');\n      emptyState.style.setProperty('inset-inline', '0');\n      emptyState.style.setProperty(\n        'inset-block-end',\n        'var(--ds-scroll-overlay-block-size, 0)',\n      );\n      emptyState.style.setProperty('height', 'auto');\n      emptyState.style.setProperty('box-sizing', 'border-box');\n    }\n    this.scrollOverlayController?.sync();\n  };\n\n  render() {\n    return (\n      <Host>\n        <div class=\"conversation-list\">\n          <div\n            class=\"conversation-list__viewport\"\n            ref={element => {\n              this.viewport = element;\n            }}\n            onScroll={() => this.scrollOverlayController?.sync()}\n          >\n            <div\n              class=\"conversation-list__content\"\n              ref={element => {\n                this.content = element;\n              }}\n            >\n              <slot />\n              <div class=\"conversation-list__empty\">\n                <slot name=\"empty\" />\n              </div>\n            </div>\n          </div>\n          <div\n            class=\"conversation-list__fade scroll-edge-fade scroll-edge-fade--top\"\n            aria-hidden=\"true\"\n          />\n          <div\n            class={{\n              'conversation-list__actions': true,\n              'conversation-list__actions--footer': this.actionLayout === 'footer',\n            }}\n            ref={element => {\n              this.overlay = element;\n            }}\n          >\n            <div class=\"conversation-list__actions-surface\">\n              <slot name=\"actions\" />\n            </div>\n          </div>\n        </div>\n      </Host>\n    );\n  }\n}\n",
       "type": "registry:ui"
     }
   ]

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

@@ -2,7 +2,7 @@
   "$schema": "https://ui.shadcn.com/schema/registry-item.json",
   "name": "markdown",
   "title": "Markdown",
-  "description": "Safe CommonMark and GFM renderer built from parsed nodes without raw HTML injection.",
+  "description": "Optional safe CommonMark and GFM renderer that emits semantic nodes without raw HTML injection and consumes the shared prose CSS contract.",
   "type": "registry:ui",
   "meta": {
     "library": "@ds-mo/ui",
@@ -13,19 +13,19 @@
     "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": [
@@ -34,7 +34,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."
@@ -42,7 +43,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"
         }
       ]
     },
@@ -129,12 +134,12 @@
   "files": [
     {
       "path": "src/wc/components/Markdown/Markdown.css",
-      "content": ":host {\n  display: block;\n  min-width: 0;\n  color: inherit;\n  box-sizing: border-box;\n  -webkit-user-select: text;\n  user-select: text;\n}\n\n.markdown {\n  min-width: 0;\n  font-family: var(--typography-font-family);\n  font-size: var(--typography-fontsize-md);\n  line-height: var(--typography-lineheight-md);\n  font-weight: var(--typography-weight-regular);\n  letter-spacing: var(--typography-letterspacing-negative-half);\n  overflow-wrap: anywhere;\n}\n\n.markdown > :first-child {\n  margin-top: 0;\n}\n\n.markdown > :last-child {\n  margin-bottom: 0;\n}\n\np,\nul,\nol,\nblockquote,\n.markdown__table-wrap,\nds-code-block {\n  margin: 0 0 var(--dimension-space-150);\n}\n\nh1,\nh2,\nh3,\nh4,\nh5,\nh6 {\n  margin: var(--dimension-space-200) 0 var(--dimension-space-100);\n  color: var(--color-foreground-primary);\n  font-family: var(--typography-font-family);\n  font-weight: var(--typography-weight-semibold);\n}\n\nh1,\nh2 {\n  font-size: var(--typography-fontsize-xl);\n  line-height: var(--typography-lineheight-xl);\n}\n\nh3,\nh4,\nh5,\nh6 {\n  font-size: var(--typography-fontsize-lg);\n  line-height: var(--typography-lineheight-lg);\n}\n\nul,\nol {\n  padding-left: var(--dimension-space-300);\n}\n\nli + li {\n  margin-top: var(--dimension-space-050);\n}\n\nli > input {\n  margin-right: var(--dimension-space-050);\n}\n\nblockquote {\n  padding-left: var(--dimension-space-150);\n  border-left: var(--dimension-stroke-width-025) solid var(--color-border-secondary);\n  color: var(--color-foreground-secondary);\n}\n\na {\n  color: var(--color-foreground-brand);\n  text-decoration: underline;\n}\n\ncode:not(ds-code-block code) {\n  padding: var(--dimension-space-012) var(--dimension-space-025);\n  border-radius: var(--dimension-radius-025);\n  background: var(--color-background-secondary);\n  font-family: var(--typography-fontfamily-mono);\n  font-size: var(--typography-fontsize-sm);\n}\n\nhr {\n  margin: var(--dimension-space-200) 0;\n  border: none;\n  border-top: var(--dimension-stroke-width-012) solid var(--color-border-tertiary);\n}\n\n.markdown__table-wrap {\n  overflow-x: auto;\n}\n\ntable {\n  width: 100%;\n  border-collapse: collapse;\n}\n\nth,\ntd {\n  padding: var(--dimension-space-075);\n  border: var(--dimension-stroke-width-012) solid var(--color-border-tertiary);\n  text-align: left;\n  vertical-align: top;\n}\n\nth {\n  font-weight: var(--typography-weight-semibold);\n}\n",
+      "content": "@import '../../styles/prose.css';\n\n:host {\n  display: block;\n  min-width: 0;\n  color: inherit;\n  box-sizing: border-box;\n  -webkit-user-select: text;\n  user-select: text;\n}\n",
       "type": "registry:ui"
     },
     {
       "path": "src/wc/components/Markdown/Markdown.tsx",
-      "content": "import { Component, h, Host, Prop, State, VNode, Watch } from '@stencil/core';\nimport type { Nodes, Root } from 'mdast';\n\ntype MarkdownRender = VNode | string | null | MarkdownRender[];\ntype MarkdownParser = {\n  fromMarkdown: typeof import('mdast-util-from-markdown').fromMarkdown;\n  gfmFromMarkdown: typeof import('mdast-util-gfm').gfmFromMarkdown;\n  gfm: typeof import('micromark-extension-gfm').gfm;\n};\n\nlet parserPromise: Promise<MarkdownParser> | undefined;\n\nfunction loadParser(): Promise<MarkdownParser> {\n  parserPromise ??= Promise.all([\n    import('mdast-util-from-markdown'),\n    import('mdast-util-gfm'),\n    import('micromark-extension-gfm'),\n  ]).then(([fromMarkdownModule, gfmFromMarkdownModule, gfmModule]) => ({\n    fromMarkdown: fromMarkdownModule.fromMarkdown,\n    gfmFromMarkdown: gfmFromMarkdownModule.gfmFromMarkdown,\n    gfm: gfmModule.gfm,\n  }));\n  return parserPromise;\n}\n\nfunction safeHref(value: string | null | undefined): string | undefined {\n  if (!value) return undefined;\n  try {\n    const url = new URL(value, document.baseURI);\n    if (!['http:', 'https:', 'mailto:'].includes(url.protocol)) return undefined;\n    return url.href;\n  } catch {\n    return undefined;\n  }\n}\n\n@Component({\n  tag: 'ds-markdown',\n  styleUrl: 'Markdown.css',\n  scoped: true,\n})\nexport class Markdown {\n  @Prop() content: string = '';\n  @Prop() streaming: boolean = false;\n\n  @State() private tree: Root | null = null;\n  private parseFrame?: number;\n  private parseRevision = 0;\n\n  componentWillLoad() {\n    // The browser-targeted named-character decoder used by the Markdown parser\n    // creates a DOM element when its module is evaluated. Keep public package\n    // imports server-safe by loading that parser only in a browser context.\n    if (typeof document !== 'undefined') return this.parse();\n  }\n\n  disconnectedCallback() {\n    this.parseRevision += 1;\n    if (this.parseFrame && typeof cancelAnimationFrame === 'function') {\n      cancelAnimationFrame(this.parseFrame);\n    }\n  }\n\n  @Watch('content')\n  scheduleParse() {\n    if (typeof requestAnimationFrame !== 'function') return;\n    if (this.parseFrame) cancelAnimationFrame(this.parseFrame);\n    this.parseFrame = requestAnimationFrame(() => {\n      this.parseFrame = undefined;\n      void this.parse();\n    });\n  }\n\n  private async parse() {\n    const revision = ++this.parseRevision;\n    try {\n      const { fromMarkdown, gfmFromMarkdown, gfm } = await loadParser();\n      const tree = fromMarkdown(this.content, {\n        extensions: [gfm()],\n        mdastExtensions: [gfmFromMarkdown()],\n      });\n      if (revision === this.parseRevision) this.tree = tree;\n    } catch {\n      if (revision === this.parseRevision) this.tree = null;\n    }\n  }\n\n  private children(node: Nodes): MarkdownRender[] {\n    if (!('children' in node)) return [];\n    return node.children.map(child => this.renderNode(child));\n  }\n\n  private renderNode(node: Nodes): MarkdownRender {\n    switch (node.type) {\n      case 'root':\n        return this.children(node);\n      case 'text':\n        // Keep prose text on an element boundary. Besides giving streaming updates a\n        // stable render target, this avoids axe-core treating a bare Stencil text\n        // vnode as an element while it generates a contrast-result selector.\n        return <span class=\"markdown__text\">{node.value}</span>;\n      case 'paragraph':\n        return <p class=\"markdown__paragraph\">{this.children(node)}</p>;\n      case 'heading': {\n        const Tag = `h${node.depth}`;\n        return <Tag class=\"markdown__heading\">{this.children(node)}</Tag>;\n      }\n      case 'strong':\n        return <strong class=\"markdown__strong\">{this.children(node)}</strong>;\n      case 'emphasis':\n        return <em class=\"markdown__emphasis\">{this.children(node)}</em>;\n      case 'delete':\n        return <del class=\"markdown__delete\">{this.children(node)}</del>;\n      case 'blockquote':\n        return <blockquote class=\"markdown__blockquote\">{this.children(node)}</blockquote>;\n      case 'break':\n        return <br class=\"markdown__break\" />;\n      case 'thematicBreak':\n        return <hr class=\"markdown__thematic-break\" />;\n      case 'inlineCode':\n        return <code class=\"markdown__inline-code\">{node.value}</code>;\n      case 'code':\n        return (\n          <ds-code-block\n            class=\"markdown__code-block\"\n            code={node.value}\n            language={node.lang ?? ''}\n            filename={node.meta ?? ''}\n          />\n        );\n      case 'link': {\n        const href = safeHref(node.url);\n        return href ? (\n          <a class=\"markdown__link\" href={href} target=\"_blank\" rel=\"noopener noreferrer\">\n            {this.children(node)}\n          </a>\n        ) : (\n          this.children(node)\n        );\n      }\n      case 'list': {\n        const Tag = node.ordered ? 'ol' : 'ul';\n        return (\n          <Tag class=\"markdown__list\" start={node.ordered && node.start ? node.start : undefined}>\n            {this.children(node)}\n          </Tag>\n        );\n      }\n      case 'listItem':\n        return (\n          <li class=\"markdown__list-item\">\n            {typeof node.checked === 'boolean' ? (\n              <input\n                class=\"markdown__task-indicator\"\n                type=\"checkbox\"\n                checked={node.checked}\n                disabled\n                aria-hidden=\"true\"\n                tabIndex={-1}\n              />\n            ) : null}\n            {this.children(node)}\n          </li>\n        );\n      case 'table': {\n        const [heading, ...rows] = node.children;\n        return (\n          <div class=\"markdown__table-wrap\">\n            <table class=\"markdown__table\">\n              {heading ? (\n                <thead class=\"markdown__table-head\">\n                  <tr class=\"markdown__table-row\">\n                    {heading.children.map(cell => (\n                      <th class=\"markdown__table-heading\" scope=\"col\">\n                        {this.children(cell)}\n                      </th>\n                    ))}\n                  </tr>\n                </thead>\n              ) : null}\n              <tbody class=\"markdown__table-body\">{rows.map(row => this.renderNode(row))}</tbody>\n            </table>\n          </div>\n        );\n      }\n      case 'tableRow':\n        return <tr class=\"markdown__table-row\">{this.children(node)}</tr>;\n      case 'tableCell':\n        return <td class=\"markdown__table-cell\">{this.children(node)}</td>;\n      case 'image': {\n        const href = safeHref(node.url);\n        return href ? (\n          <a class=\"markdown__image-link\" href={href} target=\"_blank\" rel=\"noopener noreferrer\">\n            {node.alt || 'View image'}\n          </a>\n        ) : (\n          node.alt || null\n        );\n      }\n      case 'html':\n      case 'definition':\n      case 'footnoteDefinition':\n        return null;\n      case 'footnoteReference':\n        return <sup class=\"markdown__footnote\">{node.label}</sup>;\n      default:\n        return this.children(node);\n    }\n  }\n\n  render() {\n    return (\n      <Host aria-busy={this.streaming ? 'true' : undefined}>\n        <div class=\"markdown\">\n          {this.tree ? (\n            this.renderNode(this.tree)\n          ) : (\n            <p class=\"markdown__paragraph\">\n              <span class=\"markdown__text\">{this.content}</span>\n            </p>\n          )}\n        </div>\n      </Host>\n    );\n  }\n}\n",
+      "content": "import { Component, h, Host, Prop, State, VNode, Watch } from '@stencil/core';\nimport type { Nodes, Root } from 'mdast';\n\ntype MarkdownRender = VNode | string | null | MarkdownRender[];\ntype MarkdownParser = {\n  fromMarkdown: typeof import('mdast-util-from-markdown').fromMarkdown;\n  gfmFromMarkdown: typeof import('mdast-util-gfm').gfmFromMarkdown;\n  gfm: typeof import('micromark-extension-gfm').gfm;\n};\n\nlet parserPromise: Promise<MarkdownParser> | undefined;\n\nfunction loadParser(): Promise<MarkdownParser> {\n  parserPromise ??= Promise.all([\n    import('mdast-util-from-markdown'),\n    import('mdast-util-gfm'),\n    import('micromark-extension-gfm'),\n  ]).then(([fromMarkdownModule, gfmFromMarkdownModule, gfmModule]) => ({\n    fromMarkdown: fromMarkdownModule.fromMarkdown,\n    gfmFromMarkdown: gfmFromMarkdownModule.gfmFromMarkdown,\n    gfm: gfmModule.gfm,\n  }));\n  return parserPromise;\n}\n\nfunction safeHref(value: string | null | undefined): string | undefined {\n  if (!value) return undefined;\n  try {\n    const url = new URL(value, document.baseURI);\n    if (!['http:', 'https:', 'mailto:'].includes(url.protocol)) return undefined;\n    return url.href;\n  } catch {\n    return undefined;\n  }\n}\n\n@Component({\n  tag: 'ds-markdown',\n  styleUrl: 'Markdown.css',\n  scoped: true,\n})\nexport class Markdown {\n  @Prop() content: string = '';\n  @Prop() streaming: boolean = false;\n\n  @State() private tree: Root | null = null;\n  private parseFrame?: number;\n  private parseRevision = 0;\n\n  componentWillLoad() {\n    // The browser-targeted named-character decoder used by the Markdown parser\n    // creates a DOM element when its module is evaluated. Keep public package\n    // imports server-safe by loading that parser only in a browser context.\n    if (typeof document !== 'undefined') return this.parse();\n  }\n\n  disconnectedCallback() {\n    this.parseRevision += 1;\n    if (this.parseFrame && typeof cancelAnimationFrame === 'function') {\n      cancelAnimationFrame(this.parseFrame);\n    }\n  }\n\n  @Watch('content')\n  scheduleParse() {\n    if (typeof requestAnimationFrame !== 'function') return;\n    if (this.parseFrame) cancelAnimationFrame(this.parseFrame);\n    this.parseFrame = requestAnimationFrame(() => {\n      this.parseFrame = undefined;\n      void this.parse();\n    });\n  }\n\n  private async parse() {\n    const revision = ++this.parseRevision;\n    try {\n      const { fromMarkdown, gfmFromMarkdown, gfm } = await loadParser();\n      const tree = fromMarkdown(this.content, {\n        extensions: [gfm()],\n        mdastExtensions: [gfmFromMarkdown()],\n      });\n      if (revision === this.parseRevision) this.tree = tree;\n    } catch {\n      if (revision === this.parseRevision) this.tree = null;\n    }\n  }\n\n  private children(node: Nodes): MarkdownRender[] {\n    if (!('children' in node)) return [];\n    return node.children.map(child => this.renderNode(child));\n  }\n\n  private renderNode(node: Nodes): MarkdownRender {\n    switch (node.type) {\n      case 'root':\n        return this.children(node);\n      case 'text':\n        // Keep prose text on an element boundary. Besides giving streaming updates a\n        // stable render target, this avoids axe-core treating a bare Stencil text\n        // vnode as an element while it generates a contrast-result selector.\n        return <span class=\"markdown__text\">{node.value}</span>;\n      case 'paragraph':\n        return <p class=\"markdown__paragraph\">{this.children(node)}</p>;\n      case 'heading': {\n        const Tag = `h${node.depth}`;\n        return <Tag class=\"markdown__heading\">{this.children(node)}</Tag>;\n      }\n      case 'strong':\n        return <strong class=\"markdown__strong\">{this.children(node)}</strong>;\n      case 'emphasis':\n        return <em class=\"markdown__emphasis\">{this.children(node)}</em>;\n      case 'delete':\n        return <del class=\"markdown__delete\">{this.children(node)}</del>;\n      case 'blockquote':\n        return <blockquote class=\"markdown__blockquote\">{this.children(node)}</blockquote>;\n      case 'break':\n        return <br class=\"markdown__break\" />;\n      case 'thematicBreak':\n        return <hr class=\"markdown__thematic-break\" />;\n      case 'inlineCode':\n        return <code class=\"markdown__inline-code\">{node.value}</code>;\n      case 'code':\n        return (\n          <ds-code-block\n            class=\"markdown__code-block\"\n            data-ds-prose=\"off\"\n            code={node.value}\n            language={node.lang ?? ''}\n            filename={node.meta ?? ''}\n          />\n        );\n      case 'link': {\n        const href = safeHref(node.url);\n        return href ? (\n          <a class=\"markdown__link\" href={href} target=\"_blank\" rel=\"noopener noreferrer\">\n            {this.children(node)}\n          </a>\n        ) : (\n          this.children(node)\n        );\n      }\n      case 'list': {\n        const Tag = node.ordered ? 'ol' : 'ul';\n        return (\n          <Tag class=\"markdown__list\" start={node.ordered && node.start ? node.start : undefined}>\n            {this.children(node)}\n          </Tag>\n        );\n      }\n      case 'listItem':\n        return (\n          <li class=\"markdown__list-item\">\n            {typeof node.checked === 'boolean' ? (\n              <input\n                class=\"markdown__task-indicator\"\n                type=\"checkbox\"\n                checked={node.checked}\n                disabled\n                aria-hidden=\"true\"\n                tabIndex={-1}\n              />\n            ) : null}\n            {this.children(node)}\n          </li>\n        );\n      case 'table': {\n        const [heading, ...rows] = node.children;\n        return (\n          <div class=\"markdown__table-wrap ds-prose__table-scroll\" tabIndex={0}>\n            <table class=\"markdown__table\">\n              {heading ? (\n                <thead class=\"markdown__table-head\">\n                  <tr class=\"markdown__table-row\">\n                    {heading.children.map(cell => (\n                      <th class=\"markdown__table-heading\" scope=\"col\">\n                        {this.children(cell)}\n                      </th>\n                    ))}\n                  </tr>\n                </thead>\n              ) : null}\n              <tbody class=\"markdown__table-body\">{rows.map(row => this.renderNode(row))}</tbody>\n            </table>\n          </div>\n        );\n      }\n      case 'tableRow':\n        return <tr class=\"markdown__table-row\">{this.children(node)}</tr>;\n      case 'tableCell':\n        return <td class=\"markdown__table-cell\">{this.children(node)}</td>;\n      case 'image': {\n        const href = safeHref(node.url);\n        return href ? (\n          <a class=\"markdown__image-link\" href={href} target=\"_blank\" rel=\"noopener noreferrer\">\n            {node.alt || 'View image'}\n          </a>\n        ) : (\n          node.alt || null\n        );\n      }\n      case 'html':\n      case 'definition':\n      case 'footnoteDefinition':\n        return null;\n      case 'footnoteReference':\n        return <sup class=\"markdown__footnote\">{node.label}</sup>;\n      default:\n        return this.children(node);\n    }\n  }\n\n  render() {\n    return (\n      <Host aria-busy={this.streaming ? 'true' : undefined}>\n        <div class=\"markdown ds-prose\">\n          {this.tree ? (\n            this.renderNode(this.tree)\n          ) : (\n            <p class=\"markdown__paragraph\">\n              <span class=\"markdown__text\">{this.content}</span>\n            </p>\n          )}\n        </div>\n      </Host>\n    );\n  }\n}\n",
       "type": "registry:ui"
     }
   ]

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

@@ -61,14 +61,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": {
@@ -205,7 +205,8 @@
           "attribute": "side",
           "default": "'bottom'",
           "required": false,
-          "mutable": false
+          "mutable": false,
+          "description": "Preferred side; placement flips to the opposite side when that offers a better fit."
         },
         "sideOffset": {
           "type": "number | string",
@@ -371,7 +372,8 @@
         "attribute": "side",
         "default": "'bottom'",
         "required": false,
-        "mutable": false
+        "mutable": false,
+        "description": "Preferred side; placement flips to the opposite side when that offers a better fit."
       },
       "sideOffset": {
         "type": "number | string",
@@ -468,12 +470,12 @@
   "files": [
     {
       "path": "src/wc/components/Menu/Menu.css",
-      "content": "@import '../../utils/choice-list.css';\n\n/* Inactive: `.ds-control-inactive` (25% opacity). */\n\n.menu-item--destructive .menu-item__label {\n  /* Beat ds-text color-* host classes for destructive rows. */\n  color: var(--color-foreground-bold-negative) !important;\n}\n\n/* Standard md icon zone keeps the dot aligned with other control suffixes. */\n.menu-item__dot-box {\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  flex-shrink: 0;\n  width: var(--ds-control-icon, var(--dimension-iconography-md));\n  height: var(--ds-control-icon, var(--dimension-iconography-md));\n  pointer-events: none;\n}\n\n/* ── Switch suffix ───────────────────────────────────────────────────────── */\n\n.menu-item__switch {\n  flex-shrink: 0;\n}\n\n/* ── Single-selection radio indicator ───────────────────────────────────── */\n\n.menu-item__radio-box {\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  flex-shrink: 0;\n  width: var(--ds-control-icon, var(--dimension-iconography-md));\n  height: var(--ds-control-icon, var(--dimension-iconography-md));\n  pointer-events: none;\n}\n\n.menu-item__radio {\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  box-sizing: border-box;\n  width: var(--dimension-iconography-sm);\n  height: var(--dimension-iconography-sm);\n  border-radius: var(--dimension-radius-half);\n  box-shadow: inset 0 0 0 var(--dimension-stroke-width-015) var(--color-foreground-tertiary);\n}\n\n.menu-item__radio--checked {\n  background-color: var(--color-background-bold-brand);\n  box-shadow: none;\n}\n\n.menu-item__radio-dot {\n  width: var(--dimension-size-100);\n  height: var(--dimension-size-100);\n  border-radius: var(--dimension-radius-half);\n  background-color: var(--color-foreground-on-bold-background-primary);\n}\n",
+      "content": "@import '../../utils/choice-list.css';\n\n/* Inactive: `.ds-control-inactive` (50% opacity). */\n\n.menu-item--destructive .menu-item__label {\n  /* Beat ds-text color-* host classes for destructive rows. */\n  color: var(--color-foreground-bold-negative) !important;\n}\n\n/* Standard md icon zone keeps the dot aligned with other control suffixes. */\n.menu-item__dot-box {\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  flex-shrink: 0;\n  width: var(--ds-control-icon, var(--dimension-iconography-md));\n  height: var(--ds-control-icon, var(--dimension-iconography-md));\n  pointer-events: none;\n}\n\n/* ── Switch suffix ───────────────────────────────────────────────────────── */\n\n.menu-item__switch {\n  flex-shrink: 0;\n}\n\n/* ── Single-selection radio indicator ───────────────────────────────────── */\n\n.menu-item__radio-box {\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  flex-shrink: 0;\n  width: var(--ds-control-icon, var(--dimension-iconography-md));\n  height: var(--ds-control-icon, var(--dimension-iconography-md));\n  pointer-events: none;\n}\n\n.menu-item__radio {\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  box-sizing: border-box;\n  width: var(--dimension-iconography-sm);\n  height: var(--dimension-iconography-sm);\n  border-radius: var(--dimension-radius-half);\n  box-shadow: inset 0 0 0 var(--dimension-stroke-width-015) var(--color-foreground-tertiary);\n}\n\n.menu-item__radio--checked {\n  background-color: var(--color-background-bold-brand);\n  box-shadow: none;\n}\n\n.menu-item__radio-dot {\n  width: var(--dimension-size-100);\n  height: var(--dimension-size-100);\n  border-radius: var(--dimension-radius-half);\n  background-color: var(--color-foreground-on-bold-background-primary);\n}\n",
       "type": "registry:ui"
     },
     {
       "path": "src/wc/components/Menu/Menu.tsx",
-      "content": "import {\n  Component,\n  Prop,\n  State,\n  Event,\n  EventEmitter,\n  Element,\n  Watch,\n  Listen,\n  h,\n  Host,\n} from '@stencil/core';\nimport {\n  choicePopupMinWidth,\n  resolveChoicePopupAlignOffset,\n  resolveCssLengthPx,\n  resolveMotionTimeMs,\n  TOKEN_CSS_LENGTHS,\n  TOKEN_DEFAULTS,\n  type ChoicePopupAnchorAlignment,\n} from '../../utils';\nimport { computeMenuPosition, type MenuAlign, type MenuSide } from './menu-position';\nimport type { MenuItemData, MenuSection } from './menu-types';\n\nexport type MenuSelectionMode = 'none' | 'single';\nimport {\n  isMenuGradientPickerSection,\n  isMenuPickerSection,\n  isMenuSwatchPickerSection,\n} from './menu-types';\nimport {\n  shellGradientPickerSections,\n  type ShellGradientPreset,\n} from '../../shell/shell-gradient-presets';\n\n/** rAF retries while the popup mounts or the anchor resolves. */\nconst POSITION_RETRY_BUDGET = 8;\nconst MENU_FOCUSABLE_SELECTOR = [\n  'a[href]',\n  'button:not([disabled])',\n  'input:not([disabled]):not([type=\"hidden\"])',\n  'select:not([disabled])',\n  'textarea:not([disabled])',\n  '[tabindex]:not([tabindex=\"-1\"])',\n].join(',');\n\nfunction snapshotMenuSections(sections: MenuSection[]): MenuSection[] {\n  return sections.map(section => {\n    if (isMenuGradientPickerSection(section)) return { ...section };\n    if (isMenuSwatchPickerSection(section)) {\n      return {\n        ...section,\n        options: section.options?.map(option => ({ ...option })),\n        sections: section.sections?.map(swatchSection => ({\n          ...swatchSection,\n          options: swatchSection.options.map(option => ({ ...option })),\n        })),\n      };\n    }\n    return { ...section, items: section.items.map(item => ({ ...item })) };\n  });\n}\n\n@Component({\n  tag: 'ds-menu',\n  styleUrl: 'Menu.css',\n  scoped: true,\n})\nexport class Menu {\n  @Element() el!: HTMLElement;\n\n  @Prop({ mutable: true }) open: boolean = false;\n  @Prop() items: MenuItemData[] = [];\n  /** Give ordinary rows mutually-exclusive radio-menu semantics using isSelected. */\n  @Prop() selectionMode: MenuSelectionMode = 'none';\n  @Prop() sections: MenuSection[] = [];\n  @Prop() side: MenuSide = 'bottom';\n  @Prop() align: MenuAlign = 'start';\n  /** Align choice-row edges to the anchor by default; use `popup-frame` only for custom frame geometry. */\n  @Prop() anchorAlignment: ChoicePopupAnchorAlignment = 'choice-cell';\n  /** Gap between anchor and menu — number (px) or TokoMo length (`var(--dimension-space-050)`, etc.). */\n  @Prop() sideOffset: number | string = TOKEN_CSS_LENGTHS.space050;\n  /** Cross-axis offset — number (px) or TokoMo length. */\n  @Prop() alignOffset: number | string = 0;\n  @Prop() menuWidth: string | undefined;\n  @Prop() minWidth: string | undefined;\n  /** External trigger element to position against. Set via JS: menuEl.anchor = buttonEl */\n  @Prop() anchor: HTMLElement | undefined;\n  /** ID of the external trigger element for positioning */\n  @Prop() anchorId: string | undefined;\n  /** Show a visible ring on the initially focused menu item. Use only when the opener was keyboard-driven. */\n  @Prop() initialFocusVisible: boolean = false;\n  /** Accessible name for the popup menu. */\n  @Prop() menuLabel: string = 'Menu';\n\n  @State() private shouldRender: boolean = false;\n  @State() private closing: boolean = false;\n  @State() private pos: { x: number; y: number } = { x: 0, y: 0 };\n  @State() private focusedIndex: number = 0;\n  @State() private positionReady: boolean = false;\n  @State() private focusRingVisible: boolean = false;\n\n  @Event() dsClose!: EventEmitter<void>;\n  /** Emitted after the popup's exit motion is complete and its rendered content is removed. */\n  @Event() dsAfterClose!: EventEmitter<void>;\n  @Event() dsSelect!: EventEmitter<MenuItemData>;\n  /** Emitted when a `gradient-picker` section swatch is chosen. */\n  @Event() dsGradientSelect!: EventEmitter<ShellGradientPreset>;\n  /** Emitted when a generic `swatch-picker` section option is chosen. */\n  @Event() dsSwatchSelect!: EventEmitter<string>;\n\n  private clickOutsideHandler: ((e: MouseEvent) => void) | null = null;\n  private scrollResizeHandler: (() => void) | null = null;\n  private closeTimer: ReturnType<typeof setTimeout> | null = null;\n  private itemEls: HTMLElement[] = [];\n  private positionRetryRaf: number | null = null;\n  private livePositionRaf: number | null = null;\n  private listenersReady = false;\n  /** Last content actually painted while open; retained unchanged through exit motion. */\n  private lastRenderedSections: MenuSection[] = [];\n  private closingSections: MenuSection[] | null = null;\n\n  componentDidLoad() {\n    if (this.open) this.onOpenChange(true);\n  }\n\n  componentDidRender() {\n    if (!this.shouldRender) return;\n    const popup = this.el.querySelector<HTMLElement>('.menu-popup');\n    if (!popup || typeof popup.showPopover !== 'function') return;\n    if (!popup.matches(':popover-open')) popup.showPopover();\n  }\n\n  disconnectedCallback() {\n    this.cancelPositionRetry();\n    this.cancelLivePositionUpdate();\n    this.teardownListeners();\n  }\n\n  @Watch('open')\n  onOpenChange(isOpen: boolean) {\n    if (isOpen) {\n      this.teardownListeners();\n      this.closingSections = null;\n      this.shouldRender = true;\n      this.closing = false;\n      this.positionReady = false;\n      this.listenersReady = false;\n      this.focusRingVisible = this.initialFocusVisible;\n      this.listenersReady = true;\n      this.setupListeners();\n      this.schedulePositionUpdate(() => {\n        this.focusInitialItem();\n      });\n    } else if (this.shouldRender) {\n      this.cancelPositionRetry();\n      this.captureClosingSections();\n      this.closing = true;\n      this.teardownListeners();\n      this.listenersReady = false;\n      const closeAnimationMs = this.closeAnimationMs;\n      if (closeAnimationMs <= 0) {\n        this.finishClose();\n        return;\n      }\n      this.closeTimer = setTimeout(() => {\n        this.closeTimer = null;\n        this.finishClose();\n      }, closeAnimationMs);\n    }\n  }\n\n  @Watch('anchor')\n  @Watch('anchorId')\n  onAnchorChange() {\n    if (this.open) this.schedulePositionUpdate();\n  }\n\n  @Watch('side')\n  @Watch('align')\n  @Watch('anchorAlignment')\n  @Watch('sideOffset')\n  @Watch('alignOffset')\n  onPositionPropsChange() {\n    if (this.open) this.schedulePositionUpdate();\n  }\n\n  private get viewportPadPx(): number {\n    return resolveCssLengthPx(TOKEN_DEFAULTS.space050, TOKEN_DEFAULTS.space050);\n  }\n\n  private get sideOffsetPx(): number {\n    return resolveCssLengthPx(this.sideOffset, TOKEN_DEFAULTS.space050);\n  }\n\n  private get alignOffsetPx(): number {\n    return resolveCssLengthPx(this.alignOffset, 0);\n  }\n\n  private get popupFallbackWidthPx(): number {\n    return resolveCssLengthPx(TOKEN_DEFAULTS.menuWidthXs, TOKEN_DEFAULTS.menuWidthXs);\n  }\n\n  private get popupFallbackHeightPx(): number {\n    return resolveCssLengthPx(TOKEN_DEFAULTS.menuFallbackHeight, TOKEN_DEFAULTS.menuFallbackHeight);\n  }\n\n  private get closeAnimationMs(): number {\n    return resolveMotionTimeMs(TOKEN_DEFAULTS.motionShort2, TOKEN_DEFAULTS.animationDurationShort3);\n  }\n\n  private finishClose() {\n    const popup = this.el.querySelector<HTMLElement>('.menu-popup');\n    if (popup?.matches(':popover-open')) popup.hidePopover();\n    this.shouldRender = false;\n    this.closing = false;\n    this.lastRenderedSections = [];\n    this.closingSections = null;\n    this.dsAfterClose.emit();\n  }\n\n  private captureClosingSections() {\n    if (this.closingSections) return;\n    const visibleSections = this.lastRenderedSections.length\n      ? this.lastRenderedSections\n      : this.activeSections;\n    this.closingSections = snapshotMenuSections(visibleSections);\n  }\n\n  private get resolvedAnchor(): HTMLElement | null {\n    if (this.anchor) return this.anchor;\n    if (this.anchorId) return document.getElementById(this.anchorId);\n    return null;\n  }\n\n  private get anchorFocusTarget(): HTMLElement | null {\n    const anchor = this.resolvedAnchor;\n    if (!anchor) return null;\n    if (anchor.matches(MENU_FOCUSABLE_SELECTOR)) return anchor;\n    return anchor.querySelector<HTMLElement>(MENU_FOCUSABLE_SELECTOR) ?? anchor;\n  }\n\n  private focusAnchor() {\n    const anchor = this.resolvedAnchor as\n      | (HTMLElement & { setFocus?: () => Promise<void> | void })\n      | null;\n    if (anchor?.setFocus) {\n      anchor.setFocus();\n      return;\n    }\n    this.anchorFocusTarget?.focus();\n  }\n\n  private moveFocusAfterTab(backwards: boolean) {\n    const anchor = this.anchorFocusTarget;\n    if (!anchor) return;\n    if (backwards) {\n      anchor.focus();\n      return;\n    }\n\n    const candidates = Array.from(\n      document.querySelectorAll<HTMLElement>(MENU_FOCUSABLE_SELECTOR)\n    ).filter(\n      element =>\n        !element.closest('.menu-popup') &&\n        !element.closest('[inert]') &&\n        element.getClientRects().length > 0\n    );\n    const index = candidates.indexOf(anchor);\n    (candidates[index + 1] ?? anchor).focus();\n  }\n\n  private compositeTabLeavesPopup(event: KeyboardEvent): boolean {\n    const popup = this.el.querySelector<HTMLElement>('.menu-popup');\n    if (!popup) return true;\n    const focusables = Array.from(\n      popup.querySelectorAll<HTMLElement>(MENU_FOCUSABLE_SELECTOR)\n    ).filter(element => element.getClientRects().length > 0);\n    const currentIndex = focusables.indexOf(event.target as HTMLElement);\n    if (currentIndex < 0) return true;\n    return event.shiftKey ? currentIndex === 0 : currentIndex === focusables.length - 1;\n  }\n\n  private get activeSections(): MenuSection[] {\n    if (this.sections.length > 0) return this.sections;\n    if (this.items.length > 0) return [{ items: this.items }];\n    return [];\n  }\n\n  private get flatItems(): MenuItemData[] {\n    return this.activeSections.flatMap(section =>\n      isMenuPickerSection(section) ? [] : section.items\n    );\n  }\n\n  /** Rich preference content is a non-modal dialog, not an ARIA action menu. */\n  private get hasCompositeSections(): boolean {\n    return this.activeSections.some(isMenuPickerSection);\n  }\n\n  private cancelPositionRetry() {\n    if (this.positionRetryRaf !== null) {\n      cancelAnimationFrame(this.positionRetryRaf);\n      this.positionRetryRaf = null;\n    }\n  }\n\n  private cancelLivePositionUpdate() {\n    if (this.livePositionRaf !== null) {\n      cancelAnimationFrame(this.livePositionRaf);\n      this.livePositionRaf = null;\n    }\n  }\n\n  /** Reposition after the current scroll/layout frame without hiding the open popup. */\n  private scheduleLivePositionUpdate() {\n    if (this.livePositionRaf !== null) return;\n    this.livePositionRaf = requestAnimationFrame(() => {\n      if (this.shouldRender && !this.closing) this.calculatePosition();\n      // Scroll-driven owners such as ShellPage may commit their compact header\n      // render in this frame. Re-read once after that render, then stop tracking.\n      this.livePositionRaf = requestAnimationFrame(() => {\n        this.livePositionRaf = null;\n        if (this.shouldRender && !this.closing) this.calculatePosition();\n      });\n    });\n  }\n\n  /** Retry until anchor + popup exist — do not reveal at 0,0 on a failed first pass. */\n  private schedulePositionUpdate(onReady?: () => void) {\n    if (!this.open) return;\n\n    this.cancelPositionRetry();\n    this.positionReady = false;\n\n    let remaining = POSITION_RETRY_BUDGET;\n\n    const attempt = () => {\n      this.positionRetryRaf = null;\n      if (!this.open) return;\n\n      if (this.calculatePosition()) {\n        this.positionReady = true;\n        onReady?.();\n        return;\n      }\n\n      if (remaining > 0) {\n        remaining -= 1;\n        this.positionRetryRaf = requestAnimationFrame(attempt);\n      }\n    };\n\n    this.positionRetryRaf = requestAnimationFrame(attempt);\n  }\n\n  /** @returns `true` when anchor and popup were found and `pos` was updated. */\n  private calculatePosition(): boolean {\n    const anchorEl = this.resolvedAnchor;\n    if (!anchorEl) return false;\n    const popup = this.el.querySelector('.menu-popup') as HTMLElement | null;\n    if (!popup) return false;\n\n    const anchorRect = anchorEl.getBoundingClientRect();\n    const sectionInsetPx = this.viewportPadPx;\n    if (!this.minWidth) {\n      if (\n        this.anchorAlignment === 'choice-cell' &&\n        (this.side === 'top' || this.side === 'bottom')\n      ) {\n        popup.style.minWidth = `max(var(--dimension-menu-width-xs), ${choicePopupMinWidth(\n          anchorRect.width,\n          sectionInsetPx\n        )}px)`;\n      } else {\n        popup.style.removeProperty('min-width');\n      }\n    }\n\n    const next = computeMenuPosition({\n      anchorRect,\n      popupWidth: popup.offsetWidth || this.popupFallbackWidthPx,\n      popupHeight: popup.offsetHeight || this.popupFallbackHeightPx,\n      side: this.side,\n      align: this.align,\n      sideOffsetPx: this.sideOffsetPx,\n      alignOffsetPx: resolveChoicePopupAlignOffset({\n        align: this.align,\n        alignOffsetPx: this.alignOffsetPx,\n        sectionInsetPx,\n        anchorAlignment: this.anchorAlignment,\n      }),\n      viewportPadPx: this.viewportPadPx,\n      viewportWidth: window.innerWidth,\n      viewportHeight: window.innerHeight,\n    });\n    if (next.x !== this.pos.x || next.y !== this.pos.y) this.pos = next;\n    return true;\n  }\n\n  /** Focus the selected item when present, otherwise the first enabled item. */\n  private focusInitialItem() {\n    if (this.hasCompositeSections) {\n      requestAnimationFrame(() => {\n        this.el.querySelector<HTMLElement>('.menu-popup [tabindex=\"0\"]')?.focus();\n      });\n      return;\n    }\n\n    const flat = this.flatItems;\n    const selectedIdx = flat.findIndex(it => it.isSelected && !it.isInactive);\n    const firstEnabledIdx = flat.findIndex(it => !it.isInactive);\n    this.focusedIndex = selectedIdx >= 0 ? selectedIdx : firstEnabledIdx >= 0 ? firstEnabledIdx : 0;\n\n    requestAnimationFrame(() => {\n      const btns = this.el.querySelectorAll<HTMLElement>('.menu-item');\n      btns[this.focusedIndex]?.focus();\n    });\n  }\n\n  private setupListeners() {\n    this.clickOutsideHandler = (e: MouseEvent) => {\n      const t = e.target as Node;\n      const popup = this.el.querySelector('.menu-popup');\n      const anchorEl = this.resolvedAnchor;\n      if (popup?.contains(t) || anchorEl?.contains(t)) return;\n      this.close();\n    };\n\n    this.scrollResizeHandler = () => this.scheduleLivePositionUpdate();\n\n    document.addEventListener('mousedown', this.clickOutsideHandler, true);\n    window.addEventListener('scroll', this.scrollResizeHandler, true);\n    window.addEventListener('resize', this.scrollResizeHandler);\n  }\n\n  private teardownListeners() {\n    this.cancelLivePositionUpdate();\n    if (this.clickOutsideHandler) {\n      document.removeEventListener('mousedown', this.clickOutsideHandler, true);\n      this.clickOutsideHandler = null;\n    }\n    if (this.scrollResizeHandler) {\n      window.removeEventListener('scroll', this.scrollResizeHandler, true);\n      window.removeEventListener('resize', this.scrollResizeHandler);\n      this.scrollResizeHandler = null;\n    }\n    if (this.closeTimer) {\n      clearTimeout(this.closeTimer);\n      this.closeTimer = null;\n    }\n  }\n\n  private close(restoreFocus = true) {\n    this.captureClosingSections();\n    if (restoreFocus) this.focusAnchor();\n    this.dsClose.emit();\n    this.open = false;\n    this.onOpenChange(false);\n  }\n\n  @Listen('keydown')\n  handleKeyDown(e: KeyboardEvent) {\n    if (!this.shouldRender || this.closing) return;\n\n    if (e.key === 'Escape') {\n      e.preventDefault();\n      this.close();\n      return;\n    }\n\n    if (e.key === 'Tab') {\n      if (this.hasCompositeSections && !this.compositeTabLeavesPopup(e)) return;\n      e.preventDefault();\n      this.close(false);\n      this.moveFocusAfterTab(e.shiftKey);\n      return;\n    }\n\n    if (this.hasCompositeSections) return;\n\n    const flat = this.flatItems;\n    const enabled = flat\n      .map((it, i) => ({ it, i }))\n      .filter(({ it }) => !it.isInactive)\n      .map(({ i }) => i);\n    if (!enabled.length) return;\n\n    const cur = enabled.indexOf(this.focusedIndex);\n    const safe = cur < 0 ? 0 : cur;\n\n    switch (e.key) {\n      case 'ArrowDown':\n        e.preventDefault();\n        e.stopPropagation();\n        this.focusRingVisible = true;\n        this.focusedIndex = enabled[(safe + 1) % enabled.length];\n        this.focusItem(this.focusedIndex);\n        break;\n      case 'ArrowUp':\n        e.preventDefault();\n        e.stopPropagation();\n        this.focusRingVisible = true;\n        this.focusedIndex = enabled[(safe - 1 + enabled.length) % enabled.length];\n        this.focusItem(this.focusedIndex);\n        break;\n      case 'Home':\n        e.preventDefault();\n        e.stopPropagation();\n        this.focusRingVisible = true;\n        this.focusedIndex = enabled[0];\n        this.focusItem(this.focusedIndex);\n        break;\n      case 'End':\n        e.preventDefault();\n        e.stopPropagation();\n        this.focusRingVisible = true;\n        this.focusedIndex = enabled[enabled.length - 1];\n        this.focusItem(this.focusedIndex);\n        break;\n    }\n  }\n\n  private focusItem(idx: number) {\n    const btns = this.el.querySelectorAll<HTMLElement>('.menu-item');\n    btns[idx]?.focus();\n  }\n\n  private handleItemClick(item: MenuItemData) {\n    if (item.isInactive) return;\n    // Consumers commonly change the item source while handling selection.\n    // Capture first so the exit animation never paints the next menu context.\n    this.captureClosingSections();\n    this.dsSelect.emit(item);\n  }\n\n  private handleGradientSelect(preset: ShellGradientPreset) {\n    this.dsGradientSelect.emit(preset);\n  }\n\n  private handleSwatchSelect(value: string) {\n    this.dsSwatchSelect.emit(value);\n  }\n\n  render() {\n    if (!this.shouldRender) return <Host style={{ display: 'contents' }} />;\n\n    const sections = this.closing\n      ? (this.closingSections ?? this.lastRenderedSections)\n      : this.activeSections;\n    const hasCompositeSections = sections.some(isMenuPickerSection);\n    if (!this.closing) {\n      this.lastRenderedSections = snapshotMenuSections(sections);\n      this.closingSections = null;\n    }\n    let flatIdx = 0;\n\n    const popupStyle: Record<string, string> = {\n      position: 'fixed',\n      left: '0',\n      top: '0',\n      transform: `translate(${Math.round(this.pos.x)}px, ${Math.round(this.pos.y)}px)`,\n      zIndex: '9998',\n      visibility: this.positionReady ? 'visible' : 'hidden',\n    };\n\n    if (this.menuWidth) popupStyle['width'] = this.menuWidth;\n    if (this.minWidth) popupStyle['min-width'] = this.minWidth;\n\n    return (\n      <Host style={{ display: 'contents' }}>\n        <div\n          popover=\"manual\"\n          class={{\n            'menu-popup': true,\n            'menu-popup--closing': this.closing,\n            'ds-choice-popup': true,\n            'ds-choice-popup--closing': this.closing,\n          }}\n          style={popupStyle}\n          role={hasCompositeSections ? 'dialog' : 'menu'}\n          aria-label={this.menuLabel}\n          aria-orientation={hasCompositeSections ? undefined : 'vertical'}\n        >\n          <div class=\"ds-choice-list\">\n            {sections.map((section, si) => (\n              <div\n                key={si}\n                class={{\n                  'menu-section': true,\n                  'menu-section--divided': si < sections.length - 1,\n                  'menu-section--gradient-picker': isMenuPickerSection(section),\n                  'ds-choice-section': true,\n                  'ds-choice-section--divided': si < sections.length - 1,\n                }}\n                role={section.header ? 'group' : undefined}\n                aria-label={section.header}\n              >\n                {section.header && (\n                  <ds-text\n                    class=\"section-header ds-choice-section__header ds-control--md\"\n                    as=\"span\"\n                    variant=\"text-body-small\"\n                    emphasis\n                    color=\"primary\"\n                    aria-hidden=\"true\"\n                  >\n                    {section.header}\n                  </ds-text>\n                )}\n                {isMenuGradientPickerSection(section) ? (\n                  <ds-swatch-picker\n                    value={section.value}\n                    groupLabel={section.header ?? 'Shell gradient theme'}\n                    sections={shellGradientPickerSections()}\n                    onDsChange={(e: CustomEvent<string>) => {\n                      e.stopPropagation();\n                      this.handleGradientSelect(e.detail as ShellGradientPreset);\n                    }}\n                  />\n                ) : isMenuSwatchPickerSection(section) ? (\n                  <ds-swatch-picker\n                    value={section.value}\n                    groupLabel={section.groupLabel ?? section.header ?? 'Swatch options'}\n                    options={section.options ?? []}\n                    sections={section.sections ?? []}\n                    onDsChange={(e: CustomEvent<string>) => {\n                      e.stopPropagation();\n                      this.handleSwatchSelect(e.detail);\n                    }}\n                  />\n                ) : (\n                  section.items.map(item => {\n                    const idx = flatIdx++;\n                    const isFocused = this.focusedIndex === idx;\n                    const isRadioItem =\n                      !hasCompositeSections &&\n                      this.selectionMode === 'single' &&\n                      !item.showSwitch;\n                    return (\n                      <button\n                        key={idx}\n                        type=\"button\"\n                        class={{\n                          'menu-item': true,\n                          'ds-choice-item': true,\n                          'ds-control--md': true,\n                          'ds-focus-ring-inset': true,\n                          'ds-focus-ring--visible': isFocused && this.focusRingVisible,\n                          'ds-interaction-fill': !item.isInactive,\n                          'ds-interaction-fill--selected': !!item.isSelected && !item.isInactive,\n                          'menu-item--selected': !!item.isSelected,\n                          'ds-control-inactive': !!item.isInactive,\n                          'menu-item--destructive': !!item.isDestructive,\n                          'menu-item--focused': isFocused,\n                        }}\n                        role={\n                          hasCompositeSections\n                            ? undefined\n                            : item.showSwitch\n                            ? 'menuitemcheckbox'\n                            : isRadioItem\n                            ? 'menuitemradio'\n                            : 'menuitem'\n                        }\n                        aria-checked={\n                          !hasCompositeSections && item.showSwitch\n                            ? String(!!item.switchValue)\n                            : isRadioItem\n                            ? String(!!item.isSelected)\n                            : undefined\n                        }\n                        aria-pressed={\n                          hasCompositeSections\n                            ? String(item.showSwitch ? !!item.switchValue : !!item.isSelected)\n                            : undefined\n                        }\n                        aria-current={\n                          !hasCompositeSections &&\n                          !item.showSwitch &&\n                          !isRadioItem &&\n                          item.isSelected\n                            ? 'true'\n                            : undefined\n                        }\n                        disabled={item.isInactive}\n                        tabIndex={hasCompositeSections ? 0 : isFocused ? 0 : -1}\n                        onMouseDown={() => {\n                          this.focusRingVisible = false;\n                        }}\n                        onClick={() => this.handleItemClick(item)}\n                        onFocus={() => {\n                          this.focusedIndex = idx;\n                        }}\n                      >\n                        {isRadioItem && (\n                          <span\n                            class=\"menu-item__radio-box ds-interaction-fill__content\"\n                            aria-hidden=\"true\"\n                          >\n                            <span\n                              class={{\n                                'menu-item__radio': true,\n                                'menu-item__radio--checked': !!item.isSelected,\n                              }}\n                            >\n                              {item.isSelected && <span class=\"menu-item__radio-dot\" />}\n                            </span>\n                          </span>\n                        )}\n                        <div class=\"menu-item__content ds-choice-item__content ds-interaction-fill__content\">\n                          <ds-text\n                            class=\"menu-item__label ds-choice-item__label\"\n                            as=\"span\"\n                            variant=\"text-body-medium\"\n                            color={item.isSelected ? 'primary' : 'secondary'}\n                          >\n                            {item.label}\n                          </ds-text>\n                          {item.subtext && (\n                            <ds-text\n                              class=\"menu-item__subtext ds-choice-item__subtext\"\n                              as=\"span\"\n                              variant=\"text-body-small\"\n                              color=\"secondary\"\n                            >\n                              {item.subtext}\n                            </ds-text>\n                          )}\n                        </div>\n                        {item.dot && (\n                          <span\n                            class=\"menu-item__dot-box ds-interaction-fill__content\"\n                            aria-hidden=\"true\"\n                          >\n                            <ds-badge\n                              class=\"menu-item__dot\"\n                              variant=\"dot\"\n                              hasRing={false}\n                              label=\"\"\n                            />\n                          </span>\n                        )}\n                        {item.showSwitch && (\n                          <ds-switch\n                            class=\"menu-item__switch ds-interaction-fill__content\"\n                            size=\"md\"\n                            checked={!!item.switchValue}\n                            presentation\n                          />\n                        )}\n                      </button>\n                    );\n                  })\n                )}\n              </div>\n            ))}\n          </div>\n        </div>\n      </Host>\n    );\n  }\n}\n",
+      "content": "import {\n  Component,\n  Prop,\n  State,\n  Event,\n  EventEmitter,\n  Element,\n  Watch,\n  Listen,\n  h,\n  Host,\n} from '@stencil/core';\nimport {\n  choicePopupMinWidth,\n  resolveChoicePopupAlignOffset,\n  resolveCssLengthPx,\n  resolveMotionTimeMs,\n  TOKEN_CSS_LENGTHS,\n  TOKEN_DEFAULTS,\n  type ChoicePopupAnchorAlignment,\n} from '../../utils';\nimport { computeMenuPosition, type MenuAlign, type MenuSide } from './menu-position';\nimport type { MenuItemData, MenuSection } from './menu-types';\n\nexport type MenuSelectionMode = 'none' | 'single';\nimport {\n  isMenuGradientPickerSection,\n  isMenuPickerSection,\n  isMenuSwatchPickerSection,\n} from './menu-types';\nimport {\n  shellGradientPickerSections,\n  type ShellGradientPreset,\n} from '../../shell/shell-gradient-presets';\n\n/** rAF retries while the popup mounts or the anchor resolves. */\nconst POSITION_RETRY_BUDGET = 8;\nconst MENU_FOCUSABLE_SELECTOR = [\n  'a[href]',\n  'button:not([disabled])',\n  'input:not([disabled]):not([type=\"hidden\"])',\n  'select:not([disabled])',\n  'textarea:not([disabled])',\n  '[tabindex]:not([tabindex=\"-1\"])',\n].join(',');\n\nfunction snapshotMenuSections(sections: MenuSection[]): MenuSection[] {\n  return sections.map(section => {\n    if (isMenuGradientPickerSection(section)) return { ...section };\n    if (isMenuSwatchPickerSection(section)) {\n      return {\n        ...section,\n        options: section.options?.map(option => ({ ...option })),\n        sections: section.sections?.map(swatchSection => ({\n          ...swatchSection,\n          options: swatchSection.options.map(option => ({ ...option })),\n        })),\n      };\n    }\n    return { ...section, items: section.items.map(item => ({ ...item })) };\n  });\n}\n\n@Component({\n  tag: 'ds-menu',\n  styleUrl: 'Menu.css',\n  scoped: true,\n})\nexport class Menu {\n  @Element() el!: HTMLElement;\n\n  @Prop({ mutable: true }) open: boolean = false;\n  @Prop() items: MenuItemData[] = [];\n  /** Give ordinary rows mutually-exclusive radio-menu semantics using isSelected. */\n  @Prop() selectionMode: MenuSelectionMode = 'none';\n  @Prop() sections: MenuSection[] = [];\n  /** Preferred side; placement flips to the opposite side when that offers a better fit. */\n  @Prop() side: MenuSide = 'bottom';\n  @Prop() align: MenuAlign = 'start';\n  /** Align choice-row edges to the anchor by default; use `popup-frame` only for custom frame geometry. */\n  @Prop() anchorAlignment: ChoicePopupAnchorAlignment = 'choice-cell';\n  /** Gap between anchor and menu — number (px) or TokoMo length (`var(--dimension-space-050)`, etc.). */\n  @Prop() sideOffset: number | string = TOKEN_CSS_LENGTHS.space050;\n  /** Cross-axis offset — number (px) or TokoMo length. */\n  @Prop() alignOffset: number | string = 0;\n  @Prop() menuWidth: string | undefined;\n  @Prop() minWidth: string | undefined;\n  /** External trigger element to position against. Set via JS: menuEl.anchor = buttonEl */\n  @Prop() anchor: HTMLElement | undefined;\n  /** ID of the external trigger element for positioning */\n  @Prop() anchorId: string | undefined;\n  /** Show a visible ring on the initially focused menu item. Use only when the opener was keyboard-driven. */\n  @Prop() initialFocusVisible: boolean = false;\n  /** Accessible name for the popup menu. */\n  @Prop() menuLabel: string = 'Menu';\n\n  @State() private shouldRender: boolean = false;\n  @State() private closing: boolean = false;\n  @State() private pos: { x: number; y: number } = { x: 0, y: 0 };\n  @State() private focusedIndex: number = 0;\n  @State() private positionReady: boolean = false;\n  @State() private focusRingVisible: boolean = false;\n\n  @Event() dsClose!: EventEmitter<void>;\n  /** Emitted after the popup's exit motion is complete and its rendered content is removed. */\n  @Event() dsAfterClose!: EventEmitter<void>;\n  @Event() dsSelect!: EventEmitter<MenuItemData>;\n  /** Emitted when a `gradient-picker` section swatch is chosen. */\n  @Event() dsGradientSelect!: EventEmitter<ShellGradientPreset>;\n  /** Emitted when a generic `swatch-picker` section option is chosen. */\n  @Event() dsSwatchSelect!: EventEmitter<string>;\n\n  private clickOutsideHandler: ((e: MouseEvent) => void) | null = null;\n  private scrollResizeHandler: (() => void) | null = null;\n  private closeTimer: ReturnType<typeof setTimeout> | null = null;\n  private positionRetryRaf: number | null = null;\n  private livePositionRaf: number | null = null;\n  /** Last content actually painted while open; retained unchanged through exit motion. */\n  private lastRenderedSections: MenuSection[] = [];\n  private closingSections: MenuSection[] | null = null;\n\n  componentDidLoad() {\n    if (this.open) this.onOpenChange(true);\n  }\n\n  componentDidRender() {\n    if (!this.shouldRender) return;\n    const popup = this.el.querySelector<HTMLElement>('.menu-popup');\n    if (!popup || typeof popup.showPopover !== 'function') return;\n    if (!popup.matches(':popover-open')) popup.showPopover();\n  }\n\n  disconnectedCallback() {\n    this.cancelPositionRetry();\n    this.cancelLivePositionUpdate();\n    this.teardownListeners();\n  }\n\n  @Watch('open')\n  onOpenChange(isOpen: boolean) {\n    if (isOpen) {\n      this.teardownListeners();\n      this.closingSections = null;\n      this.shouldRender = true;\n      this.closing = false;\n      this.positionReady = false;\n      this.focusRingVisible = this.initialFocusVisible;\n      this.setupListeners();\n      this.schedulePositionUpdate(() => {\n        this.focusInitialItem();\n      });\n    } else if (this.shouldRender) {\n      this.cancelPositionRetry();\n      this.captureClosingSections();\n      this.closing = true;\n      this.teardownListeners();\n      const closeAnimationMs = this.closeAnimationMs;\n      if (closeAnimationMs <= 0) {\n        this.finishClose();\n        return;\n      }\n      this.closeTimer = setTimeout(() => {\n        this.closeTimer = null;\n        this.finishClose();\n      }, closeAnimationMs);\n    }\n  }\n\n  @Watch('anchor')\n  @Watch('anchorId')\n  onAnchorChange() {\n    if (this.open) this.schedulePositionUpdate();\n  }\n\n  @Watch('side')\n  @Watch('align')\n  @Watch('anchorAlignment')\n  @Watch('sideOffset')\n  @Watch('alignOffset')\n  onPositionPropsChange() {\n    if (this.open) this.schedulePositionUpdate();\n  }\n\n  private get viewportPadPx(): number {\n    return resolveCssLengthPx(TOKEN_DEFAULTS.space050, TOKEN_DEFAULTS.space050);\n  }\n\n  private get sideOffsetPx(): number {\n    return resolveCssLengthPx(this.sideOffset, TOKEN_DEFAULTS.space050);\n  }\n\n  private get alignOffsetPx(): number {\n    return resolveCssLengthPx(this.alignOffset, 0);\n  }\n\n  private get popupFallbackWidthPx(): number {\n    return resolveCssLengthPx(TOKEN_DEFAULTS.menuWidthXs, TOKEN_DEFAULTS.menuWidthXs);\n  }\n\n  private get popupFallbackHeightPx(): number {\n    return resolveCssLengthPx(TOKEN_DEFAULTS.menuFallbackHeight, TOKEN_DEFAULTS.menuFallbackHeight);\n  }\n\n  private get closeAnimationMs(): number {\n    return resolveMotionTimeMs(TOKEN_DEFAULTS.motionShort2, TOKEN_DEFAULTS.animationDurationShort3);\n  }\n\n  private finishClose() {\n    const popup = this.el.querySelector<HTMLElement>('.menu-popup');\n    if (popup?.matches(':popover-open')) popup.hidePopover();\n    this.shouldRender = false;\n    this.closing = false;\n    this.lastRenderedSections = [];\n    this.closingSections = null;\n    this.dsAfterClose.emit();\n  }\n\n  private captureClosingSections() {\n    if (this.closingSections) return;\n    const visibleSections = this.lastRenderedSections.length\n      ? this.lastRenderedSections\n      : this.activeSections;\n    this.closingSections = snapshotMenuSections(visibleSections);\n  }\n\n  private get resolvedAnchor(): HTMLElement | null {\n    if (this.anchor) return this.anchor;\n    if (this.anchorId) return document.getElementById(this.anchorId);\n    return null;\n  }\n\n  private get anchorFocusTarget(): HTMLElement | null {\n    const anchor = this.resolvedAnchor;\n    if (!anchor) return null;\n    if (anchor.matches(MENU_FOCUSABLE_SELECTOR)) return anchor;\n    return anchor.querySelector<HTMLElement>(MENU_FOCUSABLE_SELECTOR) ?? anchor;\n  }\n\n  private focusAnchor() {\n    const anchor = this.resolvedAnchor as\n      | (HTMLElement & { setFocus?: () => Promise<void> | void })\n      | null;\n    if (anchor?.setFocus) {\n      anchor.setFocus();\n      return;\n    }\n    this.anchorFocusTarget?.focus();\n  }\n\n  private moveFocusAfterTab(backwards: boolean) {\n    const anchor = this.anchorFocusTarget;\n    if (!anchor) return;\n    if (backwards) {\n      anchor.focus();\n      return;\n    }\n\n    const candidates = Array.from(\n      document.querySelectorAll<HTMLElement>(MENU_FOCUSABLE_SELECTOR)\n    ).filter(\n      element =>\n        !element.closest('.menu-popup') &&\n        !element.closest('[inert]') &&\n        element.getClientRects().length > 0\n    );\n    const index = candidates.indexOf(anchor);\n    (candidates[index + 1] ?? anchor).focus();\n  }\n\n  private compositeTabLeavesPopup(event: KeyboardEvent): boolean {\n    const popup = this.el.querySelector<HTMLElement>('.menu-popup');\n    if (!popup) return true;\n    const focusables = Array.from(\n      popup.querySelectorAll<HTMLElement>(MENU_FOCUSABLE_SELECTOR)\n    ).filter(element => element.getClientRects().length > 0);\n    const currentIndex = focusables.indexOf(event.target as HTMLElement);\n    if (currentIndex < 0) return true;\n    return event.shiftKey ? currentIndex === 0 : currentIndex === focusables.length - 1;\n  }\n\n  private get activeSections(): MenuSection[] {\n    if (this.sections.length > 0) return this.sections;\n    if (this.items.length > 0) return [{ items: this.items }];\n    return [];\n  }\n\n  private get flatItems(): MenuItemData[] {\n    return this.activeSections.flatMap(section =>\n      isMenuPickerSection(section) ? [] : section.items\n    );\n  }\n\n  /** Rich preference content is a non-modal dialog, not an ARIA action menu. */\n  private get hasCompositeSections(): boolean {\n    return this.activeSections.some(isMenuPickerSection);\n  }\n\n  private cancelPositionRetry() {\n    if (this.positionRetryRaf !== null) {\n      cancelAnimationFrame(this.positionRetryRaf);\n      this.positionRetryRaf = null;\n    }\n  }\n\n  private cancelLivePositionUpdate() {\n    if (this.livePositionRaf !== null) {\n      cancelAnimationFrame(this.livePositionRaf);\n      this.livePositionRaf = null;\n    }\n  }\n\n  /** Reposition after the current scroll/layout frame without hiding the open popup. */\n  private scheduleLivePositionUpdate() {\n    if (this.livePositionRaf !== null) return;\n    this.livePositionRaf = requestAnimationFrame(() => {\n      if (this.shouldRender && !this.closing) this.calculatePosition();\n      // Scroll-driven owners such as ShellPage may commit their compact header\n      // render in this frame. Re-read once after that render, then stop tracking.\n      this.livePositionRaf = requestAnimationFrame(() => {\n        this.livePositionRaf = null;\n        if (this.shouldRender && !this.closing) this.calculatePosition();\n      });\n    });\n  }\n\n  /** Retry until anchor + popup exist — do not reveal at 0,0 on a failed first pass. */\n  private schedulePositionUpdate(onReady?: () => void) {\n    if (!this.open) return;\n\n    this.cancelPositionRetry();\n    this.positionReady = false;\n\n    let remaining = POSITION_RETRY_BUDGET;\n\n    const attempt = () => {\n      this.positionRetryRaf = null;\n      if (!this.open) return;\n\n      if (this.calculatePosition()) {\n        this.positionReady = true;\n        onReady?.();\n        return;\n      }\n\n      if (remaining > 0) {\n        remaining -= 1;\n        this.positionRetryRaf = requestAnimationFrame(attempt);\n      }\n    };\n\n    this.positionRetryRaf = requestAnimationFrame(attempt);\n  }\n\n  /** @returns `true` when anchor and popup were found and `pos` was updated. */\n  private calculatePosition(): boolean {\n    const anchorEl = this.resolvedAnchor;\n    if (!anchorEl) return false;\n    const popup = this.el.querySelector('.menu-popup') as HTMLElement | null;\n    if (!popup) return false;\n\n    const anchorRect = anchorEl.getBoundingClientRect();\n    const sectionInsetPx = this.viewportPadPx;\n    if (!this.minWidth) {\n      if (\n        this.anchorAlignment === 'choice-cell' &&\n        (this.side === 'top' || this.side === 'bottom')\n      ) {\n        popup.style.minWidth = `max(var(--dimension-menu-width-xs), ${choicePopupMinWidth(\n          anchorRect.width,\n          sectionInsetPx\n        )}px)`;\n      } else {\n        popup.style.removeProperty('min-width');\n      }\n    }\n\n    const next = computeMenuPosition({\n      anchorRect,\n      popupWidth: popup.offsetWidth || this.popupFallbackWidthPx,\n      popupHeight: popup.offsetHeight || this.popupFallbackHeightPx,\n      side: this.side,\n      align: this.align,\n      sideOffsetPx: this.sideOffsetPx,\n      alignOffsetPx: resolveChoicePopupAlignOffset({\n        align: this.align,\n        alignOffsetPx: this.alignOffsetPx,\n        sectionInsetPx,\n        anchorAlignment: this.anchorAlignment,\n      }),\n      viewportPadPx: this.viewportPadPx,\n      viewportWidth: window.innerWidth,\n      viewportHeight: window.innerHeight,\n    });\n    if (next.x !== this.pos.x || next.y !== this.pos.y) this.pos = next;\n    return true;\n  }\n\n  /** Focus the selected item when present, otherwise the first enabled item. */\n  private focusInitialItem() {\n    if (this.hasCompositeSections) {\n      requestAnimationFrame(() => {\n        this.el.querySelector<HTMLElement>('.menu-popup [tabindex=\"0\"]')?.focus();\n      });\n      return;\n    }\n\n    const flat = this.flatItems;\n    const selectedIdx = flat.findIndex(it => it.isSelected && !it.isInactive);\n    const firstEnabledIdx = flat.findIndex(it => !it.isInactive);\n    this.focusedIndex = selectedIdx >= 0 ? selectedIdx : firstEnabledIdx >= 0 ? firstEnabledIdx : 0;\n\n    requestAnimationFrame(() => {\n      const btns = this.el.querySelectorAll<HTMLElement>('.menu-item');\n      btns[this.focusedIndex]?.focus();\n    });\n  }\n\n  private setupListeners() {\n    this.clickOutsideHandler = (e: MouseEvent) => {\n      const t = e.target as Node;\n      const popup = this.el.querySelector('.menu-popup');\n      const anchorEl = this.resolvedAnchor;\n      if (popup?.contains(t) || anchorEl?.contains(t)) return;\n      this.close();\n    };\n\n    this.scrollResizeHandler = () => this.scheduleLivePositionUpdate();\n\n    document.addEventListener('mousedown', this.clickOutsideHandler, true);\n    window.addEventListener('scroll', this.scrollResizeHandler, true);\n    window.addEventListener('resize', this.scrollResizeHandler);\n  }\n\n  private teardownListeners() {\n    this.cancelLivePositionUpdate();\n    if (this.clickOutsideHandler) {\n      document.removeEventListener('mousedown', this.clickOutsideHandler, true);\n      this.clickOutsideHandler = null;\n    }\n    if (this.scrollResizeHandler) {\n      window.removeEventListener('scroll', this.scrollResizeHandler, true);\n      window.removeEventListener('resize', this.scrollResizeHandler);\n      this.scrollResizeHandler = null;\n    }\n    if (this.closeTimer) {\n      clearTimeout(this.closeTimer);\n      this.closeTimer = null;\n    }\n  }\n\n  private close(restoreFocus = true) {\n    this.captureClosingSections();\n    if (restoreFocus) this.focusAnchor();\n    this.dsClose.emit();\n    this.open = false;\n    this.onOpenChange(false);\n  }\n\n  @Listen('keydown')\n  handleKeyDown(e: KeyboardEvent) {\n    if (!this.shouldRender || this.closing) return;\n\n    if (e.key === 'Escape') {\n      e.preventDefault();\n      this.close();\n      return;\n    }\n\n    if (e.key === 'Tab') {\n      if (this.hasCompositeSections && !this.compositeTabLeavesPopup(e)) return;\n      e.preventDefault();\n      this.close(false);\n      this.moveFocusAfterTab(e.shiftKey);\n      return;\n    }\n\n    if (this.hasCompositeSections) return;\n\n    const flat = this.flatItems;\n    const enabled = flat\n      .map((it, i) => ({ it, i }))\n      .filter(({ it }) => !it.isInactive)\n      .map(({ i }) => i);\n    if (!enabled.length) return;\n\n    const cur = enabled.indexOf(this.focusedIndex);\n    const safe = cur < 0 ? 0 : cur;\n\n    switch (e.key) {\n      case 'ArrowDown':\n        e.preventDefault();\n        e.stopPropagation();\n        this.focusRingVisible = true;\n        this.focusedIndex = enabled[(safe + 1) % enabled.length];\n        this.focusItem(this.focusedIndex);\n        break;\n      case 'ArrowUp':\n        e.preventDefault();\n        e.stopPropagation();\n        this.focusRingVisible = true;\n        this.focusedIndex = enabled[(safe - 1 + enabled.length) % enabled.length];\n        this.focusItem(this.focusedIndex);\n        break;\n      case 'Home':\n        e.preventDefault();\n        e.stopPropagation();\n        this.focusRingVisible = true;\n        this.focusedIndex = enabled[0];\n        this.focusItem(this.focusedIndex);\n        break;\n      case 'End':\n        e.preventDefault();\n        e.stopPropagation();\n        this.focusRingVisible = true;\n        this.focusedIndex = enabled[enabled.length - 1];\n        this.focusItem(this.focusedIndex);\n        break;\n    }\n  }\n\n  private focusItem(idx: number) {\n    const btns = this.el.querySelectorAll<HTMLElement>('.menu-item');\n    btns[idx]?.focus();\n  }\n\n  private handleItemClick(item: MenuItemData) {\n    if (item.isInactive) return;\n    // Consumers commonly change the item source while handling selection.\n    // Capture first so the exit animation never paints the next menu context.\n    this.captureClosingSections();\n    this.dsSelect.emit(item);\n  }\n\n  private handleGradientSelect(preset: ShellGradientPreset) {\n    this.dsGradientSelect.emit(preset);\n  }\n\n  private handleSwatchSelect(value: string) {\n    this.dsSwatchSelect.emit(value);\n  }\n\n  render() {\n    if (!this.shouldRender) return <Host style={{ display: 'contents' }} />;\n\n    const sections = this.closing\n      ? (this.closingSections ?? this.lastRenderedSections)\n      : this.activeSections;\n    const hasCompositeSections = sections.some(isMenuPickerSection);\n    if (!this.closing) {\n      this.lastRenderedSections = snapshotMenuSections(sections);\n      this.closingSections = null;\n    }\n    let flatIdx = 0;\n\n    const popupStyle: Record<string, string> = {\n      position: 'fixed',\n      left: '0',\n      top: '0',\n      transform: `translate(${Math.round(this.pos.x)}px, ${Math.round(this.pos.y)}px)`,\n      zIndex: '9998',\n      visibility: this.positionReady ? 'visible' : 'hidden',\n    };\n\n    if (this.menuWidth) popupStyle['width'] = this.menuWidth;\n    if (this.minWidth) popupStyle['min-width'] = this.minWidth;\n\n    return (\n      <Host style={{ display: 'contents' }}>\n        <div\n          popover=\"manual\"\n          class={{\n            'menu-popup': true,\n            'menu-popup--closing': this.closing,\n            'ds-choice-popup': true,\n            'ds-choice-popup--closing': this.closing,\n          }}\n          style={popupStyle}\n          role={hasCompositeSections ? 'dialog' : 'menu'}\n          aria-label={this.menuLabel}\n          aria-orientation={hasCompositeSections ? undefined : 'vertical'}\n        >\n          <div class=\"ds-choice-list\">\n            {sections.map((section, si) => (\n              <div\n                key={si}\n                class={{\n                  'menu-section': true,\n                  'menu-section--divided': si < sections.length - 1,\n                  'menu-section--gradient-picker': isMenuPickerSection(section),\n                  'ds-choice-section': true,\n                  'ds-choice-section--divided': si < sections.length - 1,\n                }}\n                role={section.header ? 'group' : undefined}\n                aria-label={section.header}\n              >\n                {section.header && (\n                  <ds-text\n                    class=\"section-header ds-choice-section__header ds-control--md\"\n                    as=\"span\"\n                    variant=\"text-body-small\"\n                    emphasis\n                    color=\"primary\"\n                    aria-hidden=\"true\"\n                  >\n                    {section.header}\n                  </ds-text>\n                )}\n                {isMenuGradientPickerSection(section) ? (\n                  <ds-swatch-picker\n                    value={section.value}\n                    groupLabel={section.header ?? 'Shell gradient theme'}\n                    sections={shellGradientPickerSections()}\n                    onDsChange={(e: CustomEvent<string>) => {\n                      e.stopPropagation();\n                      this.handleGradientSelect(e.detail as ShellGradientPreset);\n                    }}\n                  />\n                ) : isMenuSwatchPickerSection(section) ? (\n                  <ds-swatch-picker\n                    value={section.value}\n                    groupLabel={section.groupLabel ?? section.header ?? 'Swatch options'}\n                    options={section.options ?? []}\n                    sections={section.sections ?? []}\n                    onDsChange={(e: CustomEvent<string>) => {\n                      e.stopPropagation();\n                      this.handleSwatchSelect(e.detail);\n                    }}\n                  />\n                ) : (\n                  section.items.map(item => {\n                    const idx = flatIdx++;\n                    const isFocused = this.focusedIndex === idx;\n                    const isRadioItem =\n                      !hasCompositeSections &&\n                      this.selectionMode === 'single' &&\n                      !item.showSwitch;\n                    return (\n                      <button\n                        key={idx}\n                        type=\"button\"\n                        class={{\n                          'menu-item': true,\n                          'ds-choice-item': true,\n                          'ds-control--md': true,\n                          'ds-focus-ring-inset': true,\n                          'ds-focus-ring--visible': isFocused && this.focusRingVisible,\n                          'ds-interaction-fill': !item.isInactive,\n                          'ds-interaction-fill--selected': !!item.isSelected && !item.isInactive,\n                          'menu-item--selected': !!item.isSelected,\n                          'ds-control-inactive': !!item.isInactive,\n                          'menu-item--destructive': !!item.isDestructive,\n                          'menu-item--focused': isFocused,\n                        }}\n                        role={\n                          hasCompositeSections\n                            ? undefined\n                            : item.showSwitch\n                            ? 'menuitemcheckbox'\n                            : isRadioItem\n                            ? 'menuitemradio'\n                            : 'menuitem'\n                        }\n                        aria-checked={\n                          !hasCompositeSections && item.showSwitch\n                            ? String(!!item.switchValue)\n                            : isRadioItem\n                            ? String(!!item.isSelected)\n                            : undefined\n                        }\n                        aria-pressed={\n                          hasCompositeSections\n                            ? String(item.showSwitch ? !!item.switchValue : !!item.isSelected)\n                            : undefined\n                        }\n                        aria-current={\n                          !hasCompositeSections &&\n                          !item.showSwitch &&\n                          !isRadioItem &&\n                          item.isSelected\n                            ? 'true'\n                            : undefined\n                        }\n                        disabled={item.isInactive}\n                        tabIndex={hasCompositeSections ? 0 : isFocused ? 0 : -1}\n                        onMouseDown={() => {\n                          this.focusRingVisible = false;\n                        }}\n                        onClick={() => this.handleItemClick(item)}\n                        onFocus={() => {\n                          this.focusedIndex = idx;\n                        }}\n                      >\n                        {isRadioItem && (\n                          <span\n                            class=\"menu-item__radio-box ds-interaction-fill__content\"\n                            aria-hidden=\"true\"\n                          >\n                            <span\n                              class={{\n                                'menu-item__radio': true,\n                                'menu-item__radio--checked': !!item.isSelected,\n                              }}\n                            >\n                              {item.isSelected && <span class=\"menu-item__radio-dot\" />}\n                            </span>\n                          </span>\n                        )}\n                        <div class=\"menu-item__content ds-choice-item__content ds-interaction-fill__content\">\n                          <ds-text\n                            class=\"menu-item__label ds-choice-item__label\"\n                            as=\"span\"\n                            variant=\"text-body-medium\"\n                            color={item.isSelected ? 'primary' : 'secondary'}\n                          >\n                            {item.label}\n                          </ds-text>\n                          {item.subtext && (\n                            <ds-text\n                              class=\"menu-item__subtext ds-choice-item__subtext\"\n                              as=\"span\"\n                              variant=\"text-body-small\"\n                              color=\"secondary\"\n                            >\n                              {item.subtext}\n                            </ds-text>\n                          )}\n                        </div>\n                        {item.dot && (\n                          <span\n                            class=\"menu-item__dot-box ds-interaction-fill__content\"\n                            aria-hidden=\"true\"\n                          >\n                            <ds-badge\n                              class=\"menu-item__dot\"\n                              variant=\"dot\"\n                              hasRing={false}\n                              label=\"\"\n                            />\n                          </span>\n                        )}\n                        {item.showSwitch && (\n                          <ds-switch\n                            class=\"menu-item__switch ds-interaction-fill__content\"\n                            size=\"md\"\n                            checked={!!item.switchValue}\n                            presentation\n                          />\n                        )}\n                      </button>\n                    );\n                  })\n                )}\n              </div>\n            ))}\n          </div>\n        </div>\n      </Host>\n    );\n  }\n}\n",
       "type": "registry:ui"
     },
     {

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

@@ -36,7 +36,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."
@@ -206,12 +206,12 @@
   "files": [
     {
       "path": "src/wc/components/MessageScroller/MessageScroller.css",
-      "content": ":host {\n  display: block;\n  width: 100%;\n  height: 100%;\n  min-height: 0;\n  box-sizing: border-box;\n}\n\n.message-scroller {\n  position: relative;\n  width: 100%;\n  height: 100%;\n  min-height: 0;\n}\n\n.message-scroller__viewport {\n  width: 100%;\n  height: 100%;\n  min-height: 0;\n  overflow: auto;\n  overscroll-behavior: contain;\n  box-sizing: border-box;\n}\n\n.message-scroller__viewport:focus-visible {\n  outline: var(--dimension-stroke-width-025) solid var(--color-border-bold-brand);\n  outline-offset: calc(-1 * var(--dimension-stroke-width-025));\n}\n\n.message-scroller__content {\n  display: flex;\n  flex-direction: column;\n  gap: var(--dimension-space-300);\n  width: 100%;\n  max-width: var(--dimension-panel-width-2xl);\n  min-height: 100%;\n  margin-inline: auto;\n  padding-block-start: var(--dimension-space-200);\n  padding-inline: var(--dimension-space-200);\n  padding-block-end: calc(\n    var(--dimension-space-200) + var(--ds-message-scroller-overlay-block-size, 0px)\n  );\n  box-sizing: border-box;\n}\n\n.message-scroller__overlay {\n  position: absolute;\n  right: 0;\n  bottom: 0;\n  left: 0;\n  z-index: var(--dimension-z-index-floating);\n}\n\n.message-scroller__control {\n  position: absolute;\n  bottom: calc(\n    var(--ds-message-scroller-overlay-content-block-size, 0px) + var(--dimension-space-200)\n  );\n  left: 50%;\n  z-index: var(--dimension-z-index-floating);\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  border-radius: var(--dimension-radius-half);\n  background: var(--color-background-transparent);\n  box-shadow: var(--effect-elevation-elevated-md);\n  transform: translateX(-50%);\n  -webkit-backdrop-filter: blur(var(--effect-blur-sm));\n  backdrop-filter: blur(var(--effect-blur-sm));\n}\n",
+      "content": ":host {\n  display: block;\n  width: 100%;\n  height: 100%;\n  min-height: 0;\n  box-sizing: border-box;\n}\n\n.message-scroller {\n  position: relative;\n  width: 100%;\n  height: 100%;\n  min-height: 0;\n}\n\n.message-scroller__viewport {\n  width: 100%;\n  height: 100%;\n  min-height: 0;\n  overflow: auto;\n  overscroll-behavior: contain;\n  box-sizing: border-box;\n}\n\n.message-scroller__viewport:focus-visible {\n  outline: var(--dimension-stroke-width-025) solid var(--color-border-bold-brand);\n  outline-offset: calc(-1 * var(--dimension-stroke-width-025));\n}\n\n.message-scroller__content {\n  display: flex;\n  flex-direction: column;\n  gap: var(--dimension-space-300);\n  width: 100%;\n  max-width: var(--dimension-panel-width-2xl);\n  min-height: 100%;\n  margin-inline: auto;\n  padding-block-start: var(--dimension-space-200);\n  padding-inline: var(--dimension-space-200);\n  padding-block-end: calc(\n    var(--dimension-space-200) + var(--ds-scroll-overlay-block-size, 0px)\n  );\n  box-sizing: border-box;\n}\n\n.message-scroller__overlay {\n  position: absolute;\n  right: 0;\n  bottom: 0;\n  left: 0;\n  z-index: var(--dimension-z-index-floating);\n}\n\n.message-scroller__control {\n  position: absolute;\n  bottom: calc(\n    var(--ds-scroll-overlay-content-block-size, 0px) + var(--dimension-space-200)\n  );\n  left: 50%;\n  z-index: var(--dimension-z-index-floating);\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  border-radius: var(--dimension-radius-half);\n  background: var(--color-background-transparent);\n  box-shadow: var(--effect-elevation-elevated-md);\n  transform: translateX(-50%);\n  -webkit-backdrop-filter: blur(var(--effect-blur-sm));\n  backdrop-filter: blur(var(--effect-blur-sm));\n}\n",
       "type": "registry:ui"
     },
     {
       "path": "src/wc/components/MessageScroller/MessageScroller.tsx",
-      "content": "import {\n  Component,\n  Element,\n  Event,\n  EventEmitter,\n  h,\n  Host,\n  Method,\n  Prop,\n  State,\n} from '@stencil/core';\nimport type { MessageScrollerPosition } from '../conversation-types';\n\nconst LIVE_EDGE_THRESHOLD = 24;\n\n@Component({\n  tag: 'ds-message-scroller',\n  styleUrl: 'MessageScroller.css',\n  styleUrls: ['../../utils/scroll-edge-fade.css'],\n  scoped: true,\n})\nexport class MessageScroller {\n  @Element() el!: HTMLElement;\n\n  @Prop() busy: boolean = false;\n  @Prop() autoFollow: boolean = true;\n  @Prop() defaultPosition: MessageScrollerPosition = 'last-anchor';\n  @Prop() messagesLabel: string = 'Messages';\n\n  @Event() dsReachStart!: EventEmitter<void>;\n\n  @State() private showScrollToLatest = false;\n\n  private viewport?: HTMLElement;\n  private content?: HTMLElement;\n  private overlay?: HTMLElement;\n  private resizeObserver?: ResizeObserver;\n  private overlayResizeObserver?: ResizeObserver;\n  private mutationObserver?: MutationObserver;\n  private following = true;\n  private atStart = false;\n  private programmatic = false;\n  private previousScrollHeight = 0;\n  private overlayBlockSize = 0;\n  private overlayContentBlockSize = 0;\n\n  componentDidLoad() {\n    this.connectObservers();\n    requestAnimationFrame(() => this.applyDefaultPosition());\n    document.addEventListener('selectionchange', this.handleSelectionChange);\n  }\n\n  disconnectedCallback() {\n    this.resizeObserver?.disconnect();\n    this.overlayResizeObserver?.disconnect();\n    this.mutationObserver?.disconnect();\n    document.removeEventListener('selectionchange', this.handleSelectionChange);\n  }\n\n  @Method()\n  async scrollToMessage(id: string): Promise<boolean> {\n    const message = Array.from(\n      this.el.querySelectorAll<HTMLElement & { messageId?: string }>('ds-message')\n    ).find(item => item.messageId === id || item.getAttribute('message-id') === id);\n    if (!message) return false;\n    this.following = false;\n    this.showScrollToLatest = true;\n    message.scrollIntoView({ block: 'start', behavior: this.motionBehavior() });\n    return true;\n  }\n\n  @Method()\n  async scrollToStart() {\n    this.scrollTo(0);\n    this.following = false;\n    this.showScrollToLatest = Boolean(\n      this.viewport && this.viewport.scrollHeight > this.viewport.clientHeight\n    );\n  }\n\n  @Method()\n  async scrollToEnd() {\n    this.following = true;\n    this.showScrollToLatest = false;\n    this.scrollTo(this.viewport?.scrollHeight ?? 0);\n  }\n\n  private motionBehavior(): ScrollBehavior {\n    return matchMedia('(prefers-reduced-motion: reduce)').matches ? 'auto' : 'smooth';\n  }\n\n  private scrollTo(top: number) {\n    if (!this.viewport) return;\n    this.programmatic = true;\n    this.viewport.scrollTo({ top, behavior: this.motionBehavior() });\n    requestAnimationFrame(() => {\n      this.programmatic = false;\n    });\n  }\n\n  private connectObservers() {\n    if (!this.viewport || !this.content) return;\n    this.previousScrollHeight = this.viewport.scrollHeight;\n    this.resizeObserver = new ResizeObserver(() => this.handleContentGrowth());\n    this.resizeObserver.observe(this.content);\n    this.resizeObserver.observe(this.viewport);\n    if (this.overlay) {\n      this.overlayResizeObserver = new ResizeObserver(entries => {\n        const blockSize = Math.ceil(entries[0]?.contentRect.height ?? 0);\n        this.overlayBlockSize = blockSize;\n        this.el.style.setProperty('--ds-message-scroller-overlay-block-size', `${blockSize}px`);\n        this.syncOverlayContentBlockSize();\n        this.handleContentGrowth();\n      });\n      this.overlayResizeObserver.observe(this.overlay);\n    }\n    this.mutationObserver = new MutationObserver(() => this.handleContentGrowth());\n    this.mutationObserver.observe(this.content, {\n      childList: true,\n      subtree: true,\n      characterData: true,\n    });\n  }\n\n  private handleContentGrowth() {\n    if (!this.viewport) return;\n    const nextHeight = this.viewport.scrollHeight;\n    const delta = nextHeight - this.previousScrollHeight;\n    if (delta > 0 && this.viewport.scrollTop <= LIVE_EDGE_THRESHOLD && !this.following) {\n      this.viewport.scrollTop += delta;\n    } else if (this.autoFollow && this.following) {\n      this.viewport.scrollTop = nextHeight;\n    }\n    this.previousScrollHeight = nextHeight;\n    this.showScrollToLatest = !this.following && !this.isAtLiveEdge();\n    this.syncContentFade();\n  }\n\n  private syncContentFade() {\n    if (!this.viewport || !this.content) return;\n    const fadeEnd = Math.max(this.viewport.scrollTop + this.viewport.clientHeight, 0);\n    const fadeStart = Math.max(fadeEnd - this.overlayContentBlockSize, 0);\n    this.content.style.setProperty('--ds-scroll-edge-fade-window-start', `${fadeStart}px`);\n    this.content.style.setProperty('--ds-scroll-edge-fade-window-end', `${fadeEnd}px`);\n  }\n\n  private syncOverlayContentBlockSize() {\n    if (!this.overlay) return;\n    const assigned = this.el.querySelector<HTMLElement>('[slot=\"overlay\"]');\n    if (!(assigned instanceof HTMLElement)) {\n      this.overlayContentBlockSize = this.overlayBlockSize;\n    } else {\n      const visibleContent =\n        assigned.firstElementChild instanceof HTMLElement ? assigned.firstElementChild : assigned;\n      const topInset = Math.max(\n        Math.ceil(visibleContent.getBoundingClientRect().top - this.overlay.getBoundingClientRect().top),\n        0\n      );\n      this.overlayContentBlockSize = Math.max(this.overlayBlockSize - topInset, 0);\n    }\n    this.el.style.setProperty(\n      '--ds-message-scroller-overlay-content-block-size',\n      `${this.overlayContentBlockSize}px`\n    );\n  }\n\n  private applyDefaultPosition() {\n    if (!this.viewport) return;\n    if (this.defaultPosition === 'start') {\n      this.viewport.scrollTop = 0;\n      this.following = false;\n      this.showScrollToLatest = this.viewport.scrollHeight > this.viewport.clientHeight;\n      this.syncContentFade();\n      return;\n    }\n    if (this.defaultPosition === 'last-anchor') {\n      const anchors = this.el.querySelectorAll<HTMLElement>('ds-message[scroll-anchor]');\n      const last = anchors.item(anchors.length - 1);\n      if (last) {\n        last.scrollIntoView({ block: 'start' });\n        this.following = this.isAtLiveEdge();\n        this.showScrollToLatest = !this.following;\n        this.syncContentFade();\n        return;\n      }\n    }\n    this.viewport.scrollTop = this.viewport.scrollHeight;\n    this.following = true;\n    this.showScrollToLatest = false;\n    this.syncContentFade();\n  }\n\n  private isAtLiveEdge(): boolean {\n    if (!this.viewport) return true;\n    return (\n      this.viewport.scrollHeight - this.viewport.clientHeight - this.viewport.scrollTop <=\n      LIVE_EDGE_THRESHOLD\n    );\n  }\n\n  private handleScroll = () => {\n    if (!this.viewport) return;\n    this.syncContentFade();\n    if (this.programmatic) return;\n    this.following = this.isAtLiveEdge();\n    this.showScrollToLatest = !this.following;\n    const nextAtStart = this.viewport.scrollTop <= LIVE_EDGE_THRESHOLD;\n    if (nextAtStart && !this.atStart) this.dsReachStart.emit();\n    this.atStart = nextAtStart;\n  };\n\n  private releaseFollow = () => {\n    this.following = false;\n    this.showScrollToLatest = !this.isAtLiveEdge();\n  };\n\n  private handleSelectionChange = () => {\n    const selection = document.getSelection();\n    if (\n      selection &&\n      !selection.isCollapsed &&\n      selection.anchorNode &&\n      this.el.contains(selection.anchorNode)\n    ) {\n      this.following = false;\n      this.showScrollToLatest = !this.isAtLiveEdge();\n    }\n  };\n\n  render() {\n    return (\n      <Host>\n        <div class=\"message-scroller\">\n          <div\n            class=\"message-scroller__viewport\"\n            ref={element => {\n              this.viewport = element;\n            }}\n            role=\"region\"\n            aria-label={this.messagesLabel}\n            tabIndex={0}\n            onScroll={this.handleScroll}\n            onPointerDown={this.releaseFollow}\n            onKeyDown={(event: KeyboardEvent) => {\n              if (['ArrowUp', 'PageUp', 'Home'].includes(event.key)) this.releaseFollow();\n            }}\n          >\n            <div\n              class=\"message-scroller__content scroll-edge-fade--block-window\"\n              ref={element => {\n                this.content = element;\n              }}\n              role=\"log\"\n              aria-live=\"polite\"\n              aria-relevant=\"additions\"\n              aria-busy={this.busy ? 'true' : undefined}\n            >\n              <slot />\n            </div>\n          </div>\n          <div\n            class=\"message-scroller__overlay\"\n            ref={element => {\n              this.overlay = element;\n            }}\n          >\n            <slot name=\"overlay\" />\n          </div>\n          {this.showScrollToLatest ? (\n            <div class=\"message-scroller__control\">\n              <ds-tooltip label=\"Scroll to latest message\" side=\"top\" size=\"sm\">\n                <ds-button-unfilled\n                  variant=\"icon\"\n                  icon=\"ChevronDown\"\n                  size=\"md\"\n                  rounded\n                  hasBorder={false}\n                  aria-label=\"Scroll to latest message\"\n                  onDsClick={() => void this.scrollToEnd()}\n                />\n              </ds-tooltip>\n            </div>\n          ) : null}\n        </div>\n      </Host>\n    );\n  }\n}\n",
+      "content": "import {\n  Component,\n  Element,\n  Event,\n  EventEmitter,\n  h,\n  Host,\n  Method,\n  Prop,\n  State,\n} from '@stencil/core';\nimport type { MessageScrollerPosition } from '../conversation-types';\nimport { ScrollOverlayController } from '../../utils/scroll-overlay-controller';\n\nconst LIVE_EDGE_THRESHOLD = 24;\n\n@Component({\n  tag: 'ds-message-scroller',\n  styleUrl: 'MessageScroller.css',\n  styleUrls: ['../../utils/scroll-edge-fade.css'],\n  scoped: true,\n})\nexport class MessageScroller {\n  @Element() el!: HTMLElement;\n\n  @Prop() busy: boolean = false;\n  @Prop() autoFollow: boolean = true;\n  @Prop() defaultPosition: MessageScrollerPosition = 'last-anchor';\n  @Prop() messagesLabel: string = 'Messages';\n\n  @Event() dsReachStart!: EventEmitter<void>;\n\n  @State() private showScrollToLatest = false;\n\n  private viewport?: HTMLElement;\n  private content?: HTMLElement;\n  private overlay?: HTMLElement;\n  private scrollOverlayController?: ScrollOverlayController;\n  private mutationObserver?: MutationObserver;\n  private following = true;\n  private atStart = false;\n  private programmatic = false;\n  private previousScrollHeight = 0;\n\n  componentDidLoad() {\n    this.connectObservers();\n    requestAnimationFrame(() => this.applyDefaultPosition());\n    document.addEventListener('selectionchange', this.handleSelectionChange);\n  }\n\n  disconnectedCallback() {\n    this.scrollOverlayController?.disconnect();\n    this.mutationObserver?.disconnect();\n    document.removeEventListener('selectionchange', this.handleSelectionChange);\n  }\n\n  @Method()\n  async scrollToMessage(id: string): Promise<boolean> {\n    const message = Array.from(\n      this.el.querySelectorAll<HTMLElement & { messageId?: string }>('ds-message')\n    ).find(item => item.messageId === id || item.getAttribute('message-id') === id);\n    if (!message) return false;\n    this.following = false;\n    this.showScrollToLatest = true;\n    message.scrollIntoView({ block: 'start', behavior: this.motionBehavior() });\n    return true;\n  }\n\n  @Method()\n  async scrollToStart() {\n    this.scrollTo(0);\n    this.following = false;\n    this.showScrollToLatest = Boolean(\n      this.viewport && this.viewport.scrollHeight > this.viewport.clientHeight\n    );\n  }\n\n  @Method()\n  async scrollToEnd() {\n    this.following = true;\n    this.showScrollToLatest = false;\n    this.scrollTo(this.viewport?.scrollHeight ?? 0);\n  }\n\n  private motionBehavior(): ScrollBehavior {\n    return matchMedia('(prefers-reduced-motion: reduce)').matches ? 'auto' : 'smooth';\n  }\n\n  private scrollTo(top: number) {\n    if (!this.viewport) return;\n    this.programmatic = true;\n    this.viewport.scrollTo({ top, behavior: this.motionBehavior() });\n    requestAnimationFrame(() => {\n      this.programmatic = false;\n    });\n  }\n\n  private connectObservers() {\n    if (!this.viewport || !this.content || !this.overlay) return;\n    this.previousScrollHeight = this.viewport.scrollHeight;\n    this.scrollOverlayController = new ScrollOverlayController({\n      host: this.el,\n      viewport: this.viewport,\n      content: this.content,\n      overlay: this.overlay,\n      onGeometryChange: () => this.handleContentGrowth(),\n    });\n    this.scrollOverlayController.connect();\n    this.mutationObserver = new MutationObserver(() => this.handleContentGrowth());\n    this.mutationObserver.observe(this.content, {\n      childList: true,\n      subtree: true,\n      characterData: true,\n    });\n  }\n\n  private handleContentGrowth() {\n    if (!this.viewport) return;\n    const nextHeight = this.viewport.scrollHeight;\n    const delta = nextHeight - this.previousScrollHeight;\n    if (delta > 0 && this.viewport.scrollTop <= LIVE_EDGE_THRESHOLD && !this.following) {\n      this.viewport.scrollTop += delta;\n    } else if (this.autoFollow && this.following) {\n      this.viewport.scrollTop = nextHeight;\n    }\n    this.previousScrollHeight = nextHeight;\n    this.showScrollToLatest = !this.following && !this.isAtLiveEdge();\n    this.scrollOverlayController?.sync();\n  }\n\n  private applyDefaultPosition() {\n    if (!this.viewport) return;\n    if (this.defaultPosition === 'start') {\n      this.viewport.scrollTop = 0;\n      this.following = false;\n      this.showScrollToLatest = this.viewport.scrollHeight > this.viewport.clientHeight;\n      this.scrollOverlayController?.sync();\n      return;\n    }\n    if (this.defaultPosition === 'last-anchor') {\n      const anchors = this.el.querySelectorAll<HTMLElement>('ds-message[scroll-anchor]');\n      const last = anchors.item(anchors.length - 1);\n      if (last) {\n        last.scrollIntoView({ block: 'start' });\n        this.following = this.isAtLiveEdge();\n        this.showScrollToLatest = !this.following;\n        this.scrollOverlayController?.sync();\n        return;\n      }\n    }\n    this.viewport.scrollTop = this.viewport.scrollHeight;\n    this.following = true;\n    this.showScrollToLatest = false;\n    this.scrollOverlayController?.sync();\n  }\n\n  private isAtLiveEdge(): boolean {\n    if (!this.viewport) return true;\n    return (\n      this.viewport.scrollHeight - this.viewport.clientHeight - this.viewport.scrollTop <=\n      LIVE_EDGE_THRESHOLD\n    );\n  }\n\n  private handleScroll = () => {\n    if (!this.viewport) return;\n    this.scrollOverlayController?.sync();\n    if (this.programmatic) return;\n    this.following = this.isAtLiveEdge();\n    this.showScrollToLatest = !this.following;\n    const nextAtStart = this.viewport.scrollTop <= LIVE_EDGE_THRESHOLD;\n    if (nextAtStart && !this.atStart) this.dsReachStart.emit();\n    this.atStart = nextAtStart;\n  };\n\n  private releaseFollow = () => {\n    this.following = false;\n    this.showScrollToLatest = !this.isAtLiveEdge();\n  };\n\n  private handleSelectionChange = () => {\n    const selection = document.getSelection();\n    if (\n      selection &&\n      !selection.isCollapsed &&\n      selection.anchorNode &&\n      this.el.contains(selection.anchorNode)\n    ) {\n      this.following = false;\n      this.showScrollToLatest = !this.isAtLiveEdge();\n    }\n  };\n\n  render() {\n    return (\n      <Host>\n        <div class=\"message-scroller\">\n          <div\n            class=\"message-scroller__viewport\"\n            ref={element => {\n              this.viewport = element;\n            }}\n            role=\"region\"\n            aria-label={this.messagesLabel}\n            tabIndex={0}\n            onScroll={this.handleScroll}\n            onPointerDown={this.releaseFollow}\n            onKeyDown={(event: KeyboardEvent) => {\n              if (['ArrowUp', 'PageUp', 'Home'].includes(event.key)) this.releaseFollow();\n            }}\n          >\n            <div\n              class=\"message-scroller__content scroll-edge-fade--block-window\"\n              ref={element => {\n                this.content = element;\n              }}\n              role=\"log\"\n              aria-live=\"polite\"\n              aria-relevant=\"additions\"\n              aria-busy={this.busy ? 'true' : undefined}\n            >\n              <slot />\n            </div>\n          </div>\n          <div\n            class=\"message-scroller__overlay\"\n            ref={element => {\n              this.overlay = element;\n            }}\n          >\n            <slot name=\"overlay\" />\n          </div>\n          {this.showScrollToLatest ? (\n            <div class=\"message-scroller__control\">\n              <ds-tooltip label=\"Scroll to latest message\" side=\"top\" size=\"sm\">\n                <ds-button-unfilled\n                  variant=\"icon\"\n                  icon=\"ChevronDown\"\n                  size=\"md\"\n                  rounded\n                  hasBorder={false}\n                  aria-label=\"Scroll to latest message\"\n                  onDsClick={() => void this.scrollToEnd()}\n                />\n              </ds-tooltip>\n            </div>\n          ) : null}\n        </div>\n      </Host>\n    );\n  }\n}\n",
       "type": "registry:ui"
     }
   ]

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

@@ -30,7 +30,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": [