@ds-mo/ui 11.1.0 → 12.1.0

package/dist/mcp-data/registry/select-multi.json

@@ -721,7 +721,7 @@
       "peerDependencies": {
         "required": [
           "@ds-mo/tokens ^3.1.1",
-          "@ds-mo/icons ^6.3.0"
+          "@ds-mo/icons ^6.4.0"
         ],
         "frameworks": "Custom Elements; React 18/19 wrappers; Angular 19-22 standalone adapters."
       }
@@ -738,7 +738,8 @@
     "empty-state",
     "icon",
     "loader",
-    "text"
+    "text",
+    "tooltip"
   ],
   "files": [
     {

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

@@ -707,7 +707,7 @@
       "peerDependencies": {
         "required": [
           "@ds-mo/tokens ^3.1.1",
-          "@ds-mo/icons ^6.3.0"
+          "@ds-mo/icons ^6.4.0"
         ],
         "frameworks": "Custom Elements; React 18/19 wrappers; Angular 19-22 standalone adapters."
       }
@@ -723,7 +723,8 @@
     "empty-state",
     "icon",
     "loader",
-    "text"
+    "text",
+    "tooltip"
   ],
   "files": [
     {

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

@@ -0,0 +1,213 @@
+{
+  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+  "name": "shell-app",
+  "title": "ShellApp",
+  "description": "The single required workspace root for standard authenticated application pages, coordinating primary and secondary navigation, tools chrome, responsive composition, content geometry, shared styling, and shell behavior.",
+  "type": "registry:ui",
+  "meta": {
+    "library": "@ds-mo/ui",
+    "distribution": "npm",
+    "storybook": "https://zainadeel.github.io/compomo/?path=/story/shell-app",
+    "source": "src/wc/components/ShellApp/ShellApp.tsx",
+    "intentStatus": "complete",
+    "intent": {
+      "audience": "specialized",
+      "status": "stable",
+      "summary": "The single required workspace root for standard authenticated application pages, coordinating primary and secondary navigation, tools chrome, responsive composition, content geometry, shared styling, and shell behavior.",
+      "useWhen": [
+        "Building any standard authenticated product or workspace page with CompoMo.",
+        "PanelNav, BarNav, PanelTools, page content, shared chrome, responsive behavior, and shell shortcuts must be composed as one application frame.",
+        "Future application templates need the supported base-page composition boundary."
+      ],
+      "avoidWhen": [
+        "Building authentication, onboarding, public, marketing, print, error, or intentionally focused full-screen experiences that require a different layout.",
+        "Another ShellApp already exists in the page; applications must render exactly one and must never nest ShellApps.",
+        "Building content inside an existing ShellApp; render the page content rather than another shell."
+      ],
+      "commonlyComposedWith": [
+        "component:ds-panel-nav",
+        "component:ds-bar-nav",
+        "component:ds-panel-tools",
+        "component:ds-shell-page",
+        "component:ds-swatch-picker"
+      ],
+      "patterns": [
+        "pattern:application-shell",
+        "pattern:shell-page"
+      ],
+      "accessibility": [
+        "Keep primary destinations in PanelNav and secondary route sections in BarNav.",
+        "Ensure the default content region contains the page's single main landmark.",
+        "Keep PanelNav, BarNav, and PanelTools chrome available in the shell's supported desktop and tablet compositions.",
+        "Do not override browser keyboard chords when enabling shell shortcuts.",
+        "Require Search and Help as the minimum PanelTools actions and provide accessible labels for every tool.",
+        "Preserve focus and accessible names across navigation, collapse, overflow, and responsive presentation changes."
+      ],
+      "states": [
+        "Render exactly one ShellApp as the workspace root and never nest it.",
+        "PanelNav, BarNav, and PanelTools are required shell regions; PanelTools contains at least Search and Help even when no additional product tools apply.",
+        "The application router owns the current route, authorization filtering, Dashboard or Settings context, destination collections, section collections, and localized content labels.",
+        "ShellApp propagates navStyle and coordinates layout, gradient alignment, transitions, metrics, shortcuts, and responsive composition.",
+        "Set gradientPreset to the single resolved global chrome preference: neutral by default, none for solid chrome, or cool, neutral, warm, and fresh for token-based washes.",
+        "The application owns gradient preference persistence, cross-tab synchronization, and server or account precedence; ShellApp owns rendering the resolved preset across authenticated routes.",
+        "Dashboard represents day-to-day operational work while Settings represents administrative and configuration work; route state selects the context.",
+        "Update PanelNav groups, BarNav tabs and heading, navStyle, basePath, and currentUrl atomically from one resolved route state.",
+        "BarNav remains present: it shows route-section tabs when available and the active PanelNav destination label as heading otherwise.",
+        "Render one ShellPage as the default-slot child for each standard routed page; ShellApp owns the content scroller while ShellPage owns page header stickiness and content inset.",
+        "The application filters unauthorized destinations, sections, and tools before passing them into shell components."
+      ],
+      "responsiveBehavior": [
+        "ShellApp owns the fixed system breakpoints and resolves desktop at 1200px and wider, tablet from 768px through 1199px, and mobile below 768px.",
+        "On desktop, PanelNav defaults expanded, permits user collapse or expansion, and respects the locally persisted desktop preference.",
+        "On tablet, ShellApp keeps PanelNav permanently collapsed and prevents user expansion without overwriting the desktop preference.",
+        "On mobile, ShellApp remains the page root but replaces PanelNav and desktop navigation composition with a future dedicated mobile navigation design.",
+        "Keep PanelNav width, BarNav height, PanelTools chrome, and main-content origin stable except during intentional responsive or collapse transitions.",
+        "The current runtime does not yet implement the complete desktop, tablet, and mobile composition contract; consuming applications must enforce missing breakpoint behavior until ShellApp provides it."
+      ],
+      "frameworkCaveats": {
+        "customElements": [
+          "Assign complex navigation and tool collections as JavaScript properties on the slotted components.",
+          "Stamp route-derived nav-style before components connect when deterministic first paint is required."
+        ],
+        "react": [
+          "Use generated wrappers and preserve native slot names for PanelNav, BarNav, PanelTools, and main content.",
+          "Resolve all shell inputs from one router state before rendering the composition."
+        ],
+        "angular": [
+          "Use generated standalone adapters and preserve slot attributes in templates.",
+          "Bind complex inputs as properties and update navigation inputs atomically from one resolved router state.",
+          "Bind both nav-style attributes and properties when deterministic first paint is required."
+        ]
+      },
+      "references": [
+        {
+          "label": "Component guide",
+          "path": "src/wc/components/ShellApp/ShellApp.mdx"
+        },
+        {
+          "label": "Executable Storybook composition",
+          "path": "src/wc/components/ShellApp/ShellApp.stories.ts"
+        },
+        {
+          "label": "Framework integration",
+          "path": "docs/framework-integration.md"
+        },
+        {
+          "label": "Application shell contract",
+          "path": "agent/patterns/application-shell/pattern.agent.json"
+        }
+      ]
+    },
+    "api": {
+      "props": {
+        "gradientPreset": {
+          "type": "ShellGradientPreset",
+          "resolvedType": "\"cool\" | \"fresh\" | \"neutral\" | \"none\" | \"warm\"",
+          "attribute": "gradient-preset",
+          "default": "'neutral'",
+          "required": false,
+          "mutable": false,
+          "description": "Shell chrome wash preset. `none` renders solid chrome; the remaining\npresets use token-based washes that adapt to the active color theme."
+        },
+        "navStyle": {
+          "type": "NavChromeStyle",
+          "resolvedType": "\"dashboard\" | \"settings\"",
+          "attribute": "nav-style",
+          "default": "'dashboard'",
+          "required": false,
+          "mutable": false,
+          "description": "Chrome style propagated to slotted `ds-panel-nav` and `ds-bar-nav`."
+        },
+        "shortcutsEnabled": {
+          "type": "boolean",
+          "resolvedType": "boolean",
+          "attribute": "shortcuts-enabled",
+          "default": "true",
+          "required": false,
+          "mutable": false,
+          "description": "When `true` (default), registers global shell keyboard shortcuts. `[` toggles panel nav; `]` closes tools; K, A, S, M, N, and / toggle tool drawers. Modifiers are ignored so browser chords like ⌘N stay native."
+        }
+      },
+      "events": [],
+      "methods": [],
+      "slots": []
+    },
+    "props": {
+      "gradientPreset": {
+        "type": "ShellGradientPreset",
+        "resolvedType": "\"cool\" | \"fresh\" | \"neutral\" | \"none\" | \"warm\"",
+        "attribute": "gradient-preset",
+        "default": "'neutral'",
+        "required": false,
+        "mutable": false,
+        "description": "Shell chrome wash preset. `none` renders solid chrome; the remaining\npresets use token-based washes that adapt to the active color theme."
+      },
+      "navStyle": {
+        "type": "NavChromeStyle",
+        "resolvedType": "\"dashboard\" | \"settings\"",
+        "attribute": "nav-style",
+        "default": "'dashboard'",
+        "required": false,
+        "mutable": false,
+        "description": "Chrome style propagated to slotted `ds-panel-nav` and `ds-bar-nav`."
+      },
+      "shortcutsEnabled": {
+        "type": "boolean",
+        "resolvedType": "boolean",
+        "attribute": "shortcuts-enabled",
+        "default": "true",
+        "required": false,
+        "mutable": false,
+        "description": "When `true` (default), registers global shell keyboard shortcuts. `[` toggles panel nav; `]` closes tools; K, A, S, M, N, and / toggle tool drawers. Modifiers are ignored so browser chords like ⌘N stay native."
+      }
+    },
+    "events": [],
+    "methods": [],
+    "slots": [],
+    "exports": {
+      "customElement": "ds-shell-app",
+      "react": "DsShellApp",
+      "angular": "DsShellApp"
+    },
+    "consumption": {
+      "install": "npm install @ds-mo/ui @ds-mo/tokens @ds-mo/icons",
+      "cssSetup": "import '@ds-mo/tokens';\nimport '@ds-mo/tokens/reset';\nimport '@ds-mo/tokens/globals';",
+      "customElements": {
+        "import": "import '@ds-mo/ui/dist/components/ds-shell-app.js';",
+        "example": "<ds-shell-app></ds-shell-app>"
+      },
+      "react": {
+        "import": "import { DsShellApp } from '@ds-mo/ui/react';",
+        "example": "<DsShellApp />"
+      },
+      "angular": {
+        "import": "import { DsShellApp } from '@ds-mo/ui/angular/ds-shell-app';",
+        "example": "<ds-shell-app></ds-shell-app>"
+      },
+      "peerDependencies": {
+        "required": [
+          "@ds-mo/tokens ^3.1.1",
+          "@ds-mo/icons ^6.4.0"
+        ],
+        "frameworks": "Custom Elements; React 18/19 wrappers; Angular 19-22 standalone adapters."
+      }
+    }
+  },
+  "dependencies": [
+    "@ds-mo/ui",
+    "@ds-mo/tokens"
+  ],
+  "registryDependencies": [],
+  "files": [
+    {
+      "path": "src/wc/components/ShellApp/ShellApp.css",
+      "content": ":host {\n  display: block;\n  height: 100%;\n  min-height: 0;\n  box-sizing: border-box;\n  overflow: hidden;\n  overscroll-behavior: none;\n  --ds-shell-panel-tools-width: var(--dimension-panel-width-xs);\n}\n\n.shell-app {\n  display: flex;\n  flex-direction: column;\n  height: 100%;\n  min-height: 0;\n  box-sizing: border-box;\n  overflow: hidden;\n  overscroll-behavior: none;\n  font-family: var(--typography-font-family, system-ui);\n}\n\n:host {\n  --_shell-chrome-bg: var(--color-background-secondary);\n}\n\n.shell-app__row {\n  display: flex;\n  flex: 1 1 auto;\n  min-height: 0;\n  height: 100%;\n  position: relative;\n}\n\n/*\n * One chrome layer behind the shell row. Wash uses background-attachment: fixed\n * so the pattern is locked to the viewport — panel/tools collapse only changes the\n * transparent window, not the pattern phase. JS sets wash background-size from\n * readShellViewportDimensions(), not the shell element box.\n */\n.shell-app__chrome {\n  position: absolute;\n  inset: 0;\n  pointer-events: none;\n  z-index: 0;\n  background-color: var(--_shell-chrome-bg);\n}\n\n:host(.shell-app--gradient) .shell-app__chrome::before {\n  content: '';\n  position: absolute;\n  inset: 0;\n  pointer-events: none;\n  background-position: 0 0;\n  background-attachment: fixed;\n  z-index: 1;\n  opacity: var(--ds-shell-gradient-opacity, 1);\n  background-image: var(--ds-shell-gradient-image, none);\n  background-size: var(--ds-shell-gradient-size, auto);\n  background-repeat: no-repeat;\n}\n\n.shell-app__panel {\n  flex: 0 0 auto;\n  min-height: 0;\n  height: 100%;\n  position: relative;\n  /* Above main so resize handle line can paint over the workspace edge */\n  z-index: 2;\n}\n\n.shell-app__panel ::slotted(ds-panel-nav) {\n  display: block;\n  height: 100%;\n}\n\n.shell-app__main {\n  flex: 1 1 auto;\n  min-width: 0;\n  min-height: 0;\n  display: grid;\n  grid-template-columns: minmax(0, 1fr) auto;\n  grid-template-rows: auto minmax(0, 1fr);\n  grid-template-areas:\n    'bar tools'\n    'content tools';\n  position: relative;\n  z-index: 1;\n}\n\n.shell-app__bar {\n  grid-area: bar;\n  flex: 0 0 auto;\n  min-width: 0;\n}\n\n.shell-app__bar ::slotted(ds-bar-nav) {\n  display: block;\n}\n\n.shell-app__content {\n  grid-area: content;\n  flex: 1 1 auto;\n  min-width: 0;\n  min-height: 0;\n  overflow: auto;\n  overscroll-behavior: none;\n  /* Limit reflow to the page column — not on __main (breaks tools flex shrink). */\n  contain: layout;\n}\n\n/* Opaque page surface — masks the fixed chrome layer in the content column. */\n.shell-app__content {\n  position: relative;\n  z-index: 1;\n  background-color: var(--color-background-primary);\n}\n\n.shell-app__tools {\n  grid-area: tools;\n  flex: 0 0 auto;\n  min-width: 0;\n  min-height: 0;\n  height: 100%;\n  display: flex;\n  position: relative;\n  z-index: 0;\n  overflow: hidden;\n}\n\n.shell-app__tools ::slotted(ds-panel-tools) {\n  display: block;\n  height: 100%;\n  min-height: 0;\n}\n\n:host(.shell-app--tools-fullscreen) .shell-app__panel,\n:host(.shell-app--tools-fullscreen) .shell-app__bar,\n:host(.shell-app--tools-fullscreen) .shell-app__content {\n  visibility: hidden;\n}\n",
+      "type": "registry:ui"
+    },
+    {
+      "path": "src/wc/components/ShellApp/ShellApp.tsx",
+      "content": "import { Component, Prop, Element, State, Watch, Listen, h, Host } from '@stencil/core';\nimport type { NavChromeStyle } from '../../shell/nav-chrome';\nimport {\n  isEditableShortcutTarget,\n  resolveShellShortcut,\n} from '../../shell/shell-shortcuts';\nimport type { PanelToolsToolId } from '../PanelTools/panel-tools-types';\nimport {\n  DEFAULT_SHELL_GRADIENT_PRESET,\n  normalizeShellGradientPreset,\n  type ShellGradientPreset,\n} from '../../shell/shell-gradient-presets';\nimport {\n  CHROME_TRANSITION_END,\n  CHROME_TRANSITION_START,\n  ChromeTransitionDepth,\n  createRafCoalescer,\n  readChromeTransitionSource,\n} from '../../shell/chrome-transition';\nimport {\n  isPanelNavCollapsed,\n  panelWidthPxFromTokens,\n  readPanelNavWidthTokens,\n  type PanelNavWidthTokens,\n} from '../../shell/shell-chrome-metrics';\nimport {\n  SHELL_GRADIENT_IMAGE_VAR,\n  SHELL_GRADIENT_OPACITY_VAR,\n  SHELL_GRADIENT_POSITION_BAR_VAR,\n  SHELL_GRADIENT_POSITION_PANEL_VAR,\n  SHELL_GRADIENT_SIZE_VAR,\n  buildShellRadialGradient,\n  readShellViewportDimensions,\n  shellGradientPositionBar,\n  shellGradientPositionPanel,\n  shellGradientPresetOpacity,\n  shellGradientSize,\n} from '../../shell/shell-gradient';\n\n@Component({\n  tag: 'ds-shell-app',\n  styleUrl: 'ShellApp.css',\n  scoped: true,\n})\nexport class ShellApp {\n  /** Chrome style propagated to slotted `ds-panel-nav` and `ds-bar-nav`. */\n  @Prop({ attribute: 'nav-style', reflect: true }) navStyle: NavChromeStyle = 'dashboard';\n\n  /**\n   * Shell chrome wash preset. `none` renders solid chrome; the remaining\n   * presets use token-based washes that adapt to the active color theme.\n   */\n  @Prop({ attribute: 'gradient-preset', reflect: true }) gradientPreset: ShellGradientPreset =\n    DEFAULT_SHELL_GRADIENT_PRESET;\n\n  /** When `true` (default), registers global shell keyboard shortcuts. `[` toggles panel nav; `]` closes tools; K, A, S, M, N, and / toggle tool drawers. Modifiers are ignored so browser chords like ⌘N stay native. */\n  @Prop({ attribute: 'shortcuts-enabled' }) shortcutsEnabled: boolean = true;\n\n  @Element() el!: HTMLElement;\n  @State() private toolsFullscreen = false;\n\n  private resizeObserver: ResizeObserver | null = null;\n  private readonly panelNavTransition = new ChromeTransitionDepth();\n  private readonly chromeSyncCoalescer = createRafCoalescer(() => this.syncChrome());\n  private panelWidthTokens: PanelNavWidthTokens = { expandedPx: 0, collapsedPx: 0 };\n  private cachedViewportWidth = 0;\n  private cachedViewportHeight = 0;\n  private onWindowResize = () => {\n    if (this.panelNavTransition.isActive) return;\n    this.scheduleChromeSync();\n  };\n  private onVisualViewportChange = () => {\n    if (this.panelNavTransition.isActive) return;\n    this.scheduleChromeSync();\n  };\n\n  componentDidLoad() {\n    this.syncSlottedNavStyle();\n    this.connectMetricsObserver();\n    this.connectViewportListeners();\n    this.el.addEventListener(CHROME_TRANSITION_START, this.onChromeTransitionStart);\n    this.el.addEventListener(CHROME_TRANSITION_END, this.onChromeTransitionEnd);\n    requestAnimationFrame(() => {\n      this.cachePanelWidthTokens();\n      this.scheduleChromeSync();\n    });\n    const tools = this.el.querySelector('ds-panel-tools');\n    this.toolsFullscreen = tools?.getAttribute('presentation') === 'fullscreen';\n  }\n\n  @Listen('dsPresentationChange')\n  handleToolsPresentation(event: CustomEvent<{ presentation?: string }>) {\n    this.toolsFullscreen = event.detail?.presentation === 'fullscreen';\n  }\n\n  disconnectedCallback() {\n    this.resizeObserver?.disconnect();\n    this.resizeObserver = null;\n    this.disconnectViewportListeners();\n    this.chromeSyncCoalescer.cancel();\n    this.el.removeEventListener(CHROME_TRANSITION_START, this.onChromeTransitionStart);\n    this.el.removeEventListener(CHROME_TRANSITION_END, this.onChromeTransitionEnd);\n  }\n\n  @Watch('navStyle')\n  @Watch('gradientPreset')\n  onShellPropsChange() {\n    this.syncSlottedNavStyle();\n    this.scheduleChromeSync();\n  }\n\n  private onChromeTransitionStart = (event: Event) => {\n    if (readChromeTransitionSource(event) !== 'panel-nav') return;\n\n    this.panelNavTransition.enter();\n    const viewport = readShellViewportDimensions();\n    this.cachedViewportWidth = viewport.width;\n    this.cachedViewportHeight = viewport.height;\n    this.syncChrome();\n  };\n\n  private onChromeTransitionEnd = (event: Event) => {\n    if (readChromeTransitionSource(event) !== 'panel-nav') return;\n\n    this.panelNavTransition.exit();\n    if (!this.panelNavTransition.isActive) {\n      this.scheduleChromeSync();\n    }\n  };\n\n  /** Coalesce ResizeObserver bursts to one layout read per frame. */\n  private scheduleChromeSync() {\n    this.chromeSyncCoalescer.schedule();\n  }\n\n  private syncSlottedNavStyle() {\n    const panel = this.el.querySelector('ds-panel-nav') as (HTMLElement & { navStyle: NavChromeStyle }) | null;\n    const bar = this.el.querySelector('ds-bar-nav') as (HTMLElement & { navStyle: NavChromeStyle }) | null;\n    if (panel) {\n      panel.setAttribute('nav-style', this.navStyle);\n      panel.navStyle = this.navStyle;\n    }\n    if (bar) {\n      bar.setAttribute('nav-style', this.navStyle);\n      bar.navStyle = this.navStyle;\n    }\n  }\n\n  private connectMetricsObserver() {\n    this.resizeObserver = new ResizeObserver(() => {\n      if (this.panelNavTransition.isActive) return;\n      this.scheduleChromeSync();\n    });\n    this.resizeObserver.observe(this.el);\n    const panelWrap = this.el.querySelector('.shell-app__panel');\n    if (panelWrap) this.resizeObserver.observe(panelWrap);\n  }\n\n  private connectViewportListeners() {\n    if (typeof window === 'undefined') return;\n\n    window.addEventListener('resize', this.onWindowResize, { passive: true });\n\n    const visual = window.visualViewport;\n    if (visual) {\n      visual.addEventListener('resize', this.onVisualViewportChange, { passive: true });\n      visual.addEventListener('scroll', this.onVisualViewportChange, { passive: true });\n    }\n  }\n\n  private disconnectViewportListeners() {\n    if (typeof window === 'undefined') return;\n\n    window.removeEventListener('resize', this.onWindowResize);\n\n    const visual = window.visualViewport;\n    if (visual) {\n      visual.removeEventListener('resize', this.onVisualViewportChange);\n      visual.removeEventListener('scroll', this.onVisualViewportChange);\n    }\n  }\n\n  private cachePanelWidthTokens() {\n    const navRoot = this.el.querySelector('ds-panel-nav .panel-nav') as HTMLElement | null;\n    if (!navRoot) return;\n    this.panelWidthTokens = readPanelNavWidthTokens(navRoot);\n  }\n\n  private applyGradientVars(target: HTMLElement, vars: Record<string, string | null>) {\n    const style = target.style;\n    for (const [name, value] of Object.entries(vars)) {\n      if (value === null) style.removeProperty(name);\n      else style.setProperty(name, value);\n    }\n  }\n\n  private clearGradientPaintVars(targets: HTMLElement[]) {\n    const keys = [\n      SHELL_GRADIENT_IMAGE_VAR,\n      SHELL_GRADIENT_SIZE_VAR,\n      SHELL_GRADIENT_OPACITY_VAR,\n    ];\n    for (const target of targets) {\n      for (const key of keys) target.style.removeProperty(key);\n    }\n  }\n\n  /** Panel/bar wash offsets for scroll fades and badge rings. */\n  private syncChromeLayoutVars(\n    panel: HTMLElement | null,\n    bar: HTMLElement | null,\n    panelPosition: string,\n    barPosition: string,\n  ) {\n    if (panel) {\n      panel.style.setProperty(SHELL_GRADIENT_POSITION_PANEL_VAR, panelPosition);\n    }\n    if (bar) {\n      bar.style.setProperty(SHELL_GRADIENT_POSITION_BAR_VAR, barPosition);\n    }\n  }\n\n  private resolvePanelWidthPx(panelNav: HTMLElement | null): number {\n    const navRoot = panelNav?.querySelector('.panel-nav') as HTMLElement | null;\n\n    if (this.panelNavTransition.isActive && this.panelWidthTokens.expandedPx > 0) {\n      const collapsed = isPanelNavCollapsed(panelNav, navRoot);\n      return panelWidthPxFromTokens(this.panelWidthTokens, collapsed);\n    }\n\n    const panelWrap = this.el.querySelector('.shell-app__panel') as HTMLElement | null;\n    const measured = panelWrap?.getBoundingClientRect().width ?? 0;\n    if (measured > 0) return measured;\n\n    if (this.panelWidthTokens.expandedPx > 0) {\n      const collapsed = isPanelNavCollapsed(panelNav, navRoot);\n      return panelWidthPxFromTokens(this.panelWidthTokens, collapsed);\n    }\n\n    return 0;\n  }\n\n  /** Fixed-attachment wash/grid size — always the viewport, never the shell element box. */\n  private resolveViewportDimensions(): { width: number; height: number } {\n    if (this.panelNavTransition.isActive && this.cachedViewportWidth > 0) {\n      return {\n        width: this.cachedViewportWidth,\n        height: this.cachedViewportHeight,\n      };\n    }\n\n    return readShellViewportDimensions();\n  }\n\n  private chromeLayerActive(): boolean {\n    return normalizeShellGradientPreset(this.gradientPreset) !== 'none';\n  }\n\n  @Listen('keydown', { target: 'window', capture: true })\n  handleWindowKeyDown(e: KeyboardEvent) {\n    if (!this.shortcutsEnabled) return;\n    if (isEditableShortcutTarget(e.target)) return;\n\n    const action = resolveShellShortcut(e);\n    if (!action) return;\n\n    e.preventDefault();\n\n    const panel = this.el.querySelector('ds-panel-nav') as HTMLDsPanelNavElement | null;\n    const tools = this.el.querySelector('ds-panel-tools') as HTMLDsPanelToolsElement | null;\n\n    if (action === 'toggle-panel-nav') {\n      void panel?.toggleCollapsed();\n      return;\n    }\n\n    if (action === 'close-panel-tools') {\n      void tools?.closeDrawer();\n      return;\n    }\n\n    if (action.startsWith('open-tool:') && tools) {\n      const toolId = action.slice('open-tool:'.length) as PanelToolsToolId;\n      void tools.activateTool(toolId);\n    }\n  }\n\n  private syncChrome() {\n    const panelNav = this.el.querySelector('ds-panel-nav') as HTMLElement | null;\n    const bar = this.el.querySelector('ds-bar-nav') as HTMLElement | null;\n    const targets = [this.el, panelNav, bar].filter((el): el is HTMLElement => el !== null);\n\n    const clearLayoutVars = () => {\n      if (panelNav) panelNav.style.removeProperty(SHELL_GRADIENT_POSITION_PANEL_VAR);\n      if (bar) bar.style.removeProperty(SHELL_GRADIENT_POSITION_BAR_VAR);\n    };\n\n    const preset = normalizeShellGradientPreset(this.gradientPreset);\n    if (preset === 'none') {\n      this.clearGradientPaintVars(targets);\n      clearLayoutVars();\n      return;\n    }\n\n    const viewport = this.resolveViewportDimensions();\n    const panelWidth = this.resolvePanelWidthPx(panelNav);\n\n    const panelPosition = shellGradientPositionPanel();\n    const barPosition = shellGradientPositionBar(panelWidth);\n\n    this.syncChromeLayoutVars(panelNav, bar, panelPosition, barPosition);\n\n    const image = buildShellRadialGradient(preset);\n\n    const size = shellGradientSize({\n      width: viewport.width,\n      height: viewport.height,\n    });\n    const opacity = shellGradientPresetOpacity(preset);\n\n    for (const target of targets) {\n      if (target === this.el) {\n        this.applyGradientVars(target, {\n          [SHELL_GRADIENT_IMAGE_VAR]: image,\n          [SHELL_GRADIENT_SIZE_VAR]: size,\n          [SHELL_GRADIENT_POSITION_PANEL_VAR]: panelPosition,\n          [SHELL_GRADIENT_POSITION_BAR_VAR]: barPosition,\n          [SHELL_GRADIENT_OPACITY_VAR]: opacity,\n        });\n        continue;\n      }\n\n      const isBar = target.tagName.toLowerCase() === 'ds-bar-nav';\n      this.applyGradientVars(target, {\n        [SHELL_GRADIENT_IMAGE_VAR]: image,\n        [SHELL_GRADIENT_SIZE_VAR]: size,\n        [SHELL_GRADIENT_OPACITY_VAR]: opacity,\n        [SHELL_GRADIENT_POSITION_PANEL_VAR]: isBar ? null : panelPosition,\n        [SHELL_GRADIENT_POSITION_BAR_VAR]: isBar ? barPosition : null,\n      });\n    }\n  }\n\n  render() {\n    const chromeActive = this.chromeLayerActive();\n    const shellCls: Record<string, boolean> = {\n      'shell-app': true,\n      'shell-app--gradient': chromeActive,\n      [`shell-app--${this.navStyle}`]: true,\n      'shell-app--tools-fullscreen': this.toolsFullscreen,\n    };\n\n    return (\n      <Host class={shellCls}>\n        <div class=\"shell-app__row\">\n          <div class=\"shell-app__chrome\" aria-hidden=\"true\" />\n          <div class=\"shell-app__panel\" aria-hidden={this.toolsFullscreen ? 'true' : undefined} inert={this.toolsFullscreen ? true : undefined}>\n            <slot name=\"panel\" />\n          </div>\n          <div class=\"shell-app__main\">\n            <div class=\"shell-app__bar\" aria-hidden={this.toolsFullscreen ? 'true' : undefined} inert={this.toolsFullscreen ? true : undefined}>\n              <slot name=\"bar\" />\n            </div>\n            <div class=\"shell-app__tools\">\n              <slot name=\"tools\" />\n            </div>\n            <div class=\"shell-app__content\" aria-hidden={this.toolsFullscreen ? 'true' : undefined} inert={this.toolsFullscreen ? true : undefined}>\n              <slot />\n            </div>\n          </div>\n        </div>\n      </Host>\n    );\n  }\n}\n",
+      "type": "registry:ui"
+    }
+  ]
+}

package/dist/mcp-data/registry/shell-gradient-picker.json

@@ -2,7 +2,7 @@
   "$schema": "https://ui.shadcn.com/schema/registry-item.json",
   "name": "shell-gradient-picker",
   "title": "ShellGradientPicker",
-  "description": "Deprecated compatibility wrapper that maps the fixed AppShell wash presets into SwatchPicker.",
+  "description": "Deprecated compatibility wrapper that maps the fixed ShellApp wash presets into SwatchPicker.",
   "type": "registry:ui",
   "meta": {
     "library": "@ds-mo/ui",
@@ -15,10 +15,10 @@
       "status": "deprecated",
       "replacedBy": "component:ds-swatch-picker",
       "replacementReason": "SwatchPicker now owns the same accessible interaction with a generic option model that supports both flat colors and gradients.",
-      "summary": "Deprecated compatibility wrapper that maps the fixed AppShell wash presets into SwatchPicker.",
+      "summary": "Deprecated compatibility wrapper that maps the fixed ShellApp wash presets into SwatchPicker.",
       "useWhen": [
         "Adding the Appearance or Theme section to the application's user or account menu.",
-        "Users must choose the global AppShell chrome treatment from none, cool, neutral, warm, or fresh."
+        "Users must choose the global ShellApp chrome treatment from none, cool, neutral, warm, or fresh."
       ],
       "avoidWhen": [
         "Choosing semantic intent, page background, chart, content, or brand colors.",
@@ -34,7 +34,7 @@
         }
       ],
       "commonlyComposedWith": [
-        "component:ds-app-shell",
+        "component:ds-shell-app",
         "component:ds-menu"
       ],
       "patterns": [
@@ -48,7 +48,7 @@
       "states": [
         "Neutral is the default preset; none renders solid shell chrome without a wash.",
         "Cool, neutral, warm, and fresh use design tokens and automatically adapt to the active light or dark color theme.",
-        "Apply dsChange immediately to AppShell.gradientPreset and keep the containing account menu open.",
+        "Apply dsChange immediately to ShellApp.gradientPreset and keep the containing account menu open.",
         "The application owns local persistence, cross-tab synchronization, and server or account preference precedence; the picker owns only selection UI and events.",
         "Treat the fixed preset union as the only supported values and do not construct custom gradients."
       ],
@@ -58,7 +58,7 @@
       ],
       "frameworkCaveats": {
         "customElements": [
-          "Listen for dsChange, resolve application preference precedence, and assign the result to the single AppShell gradientPreset property."
+          "Listen for dsChange, resolve application preference precedence, and assign the result to the single ShellApp gradientPreset property."
         ],
         "react": [
           "Use the generated wrapper and handle onDsChange without closing the containing account menu."
@@ -73,8 +73,8 @@
           "path": "src/wc/components/SwatchPicker/SwatchPicker.stories.ts"
         },
         {
-          "label": "AppShell gradient contract",
-          "path": "src/wc/components/AppShell/AppShell.mdx"
+          "label": "ShellApp gradient contract",
+          "path": "src/wc/components/ShellApp/ShellApp.mdx"
         },
         {
           "label": "Application shell composition",
@@ -167,7 +167,7 @@
       "peerDependencies": {
         "required": [
           "@ds-mo/tokens ^3.1.1",
-          "@ds-mo/icons ^6.3.0"
+          "@ds-mo/icons ^6.4.0"
         ],
         "frameworks": "Custom Elements; React 18/19 wrappers; Angular 19-22 standalone adapters."
       }

package/dist/mcp-data/registry/shell-gradient-swatch.json

@@ -2,7 +2,7 @@
   "$schema": "https://ui.shadcn.com/schema/registry-item.json",
   "name": "shell-gradient-swatch",
   "title": "ShellGradientSwatch",
-  "description": "Deprecated internal compatibility component for one legacy AppShell gradient swatch.",
+  "description": "Deprecated internal compatibility component for one legacy ShellApp gradient swatch.",
   "type": "registry:ui",
   "meta": {
     "library": "@ds-mo/ui",
@@ -15,7 +15,7 @@
       "status": "deprecated",
       "replacedBy": "component:ds-swatch-picker",
       "replacementReason": "SwatchPicker renders its option buttons internally so an individually published radio swatch is no longer needed.",
-      "summary": "Deprecated internal compatibility component for one legacy AppShell gradient swatch.",
+      "summary": "Deprecated internal compatibility component for one legacy ShellApp gradient swatch.",
       "useWhen": [
         "Maintaining or extending ShellGradientPicker inside CompoMo."
       ],
@@ -184,7 +184,7 @@
       "peerDependencies": {
         "required": [
           "@ds-mo/tokens ^3.1.1",
-          "@ds-mo/icons ^6.3.0"
+          "@ds-mo/icons ^6.4.0"
         ],
         "frameworks": "Custom Elements; React 18/19 wrappers; Angular 19-22 standalone adapters."
       }

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

@@ -0,0 +1,200 @@
+{
+  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+  "name": "shell-page",
+  "title": "ShellPage",
+  "description": "The standard routed-page boundary inside ShellApp, owning sticky BarTitle placement, container-aware header variants, stable scroll compaction, and optional page-content inset without creating a nested scroll container.",
+  "type": "registry:ui",
+  "meta": {
+    "library": "@ds-mo/ui",
+    "distribution": "npm",
+    "storybook": "https://zainadeel.github.io/compomo/?path=/story/shell-page",
+    "source": "src/wc/components/ShellPage/ShellPage.tsx",
+    "intentStatus": "complete",
+    "intent": {
+      "audience": "general",
+      "status": "stable",
+      "summary": "The standard routed-page boundary inside ShellApp, owning sticky BarTitle placement, container-aware header variants, stable scroll compaction, and optional page-content inset without creating a nested scroll container.",
+      "useWhen": [
+        "Rendering a standard routed page inside ShellApp's default content region.",
+        "BarTitle should expand at a roomy page top, compact after scroll, or use constrained action layout when the page column narrows.",
+        "Pages need consistent content gutters with an explicit full-bleed option."
+      ],
+      "avoidWhen": [
+        "Building authentication, onboarding, public, modal, drawer, or intentionally focused fullscreen layouts outside the standard ShellApp page region.",
+        "Another ShellPage already owns the routed page; never nest ShellPages.",
+        "A bounded card or pane needs its own header rather than a page-level main landmark."
+      ],
+      "alternatives": [
+        {
+          "when": "The composition is a persistent application-wide workspace frame.",
+          "component": "component:ds-shell-app",
+          "reason": "ShellApp owns global navigation, tools, and the content scroll region; ShellPage belongs inside it."
+        },
+        {
+          "when": "Only static page title chrome is required without sticky or responsive orchestration.",
+          "component": "component:ds-bar-title",
+          "reason": "BarTitle can be used standalone with an explicit variant."
+        }
+      ],
+      "commonlyComposedWith": [
+        "component:ds-shell-app",
+        "component:ds-bar-title",
+        "component:ds-tab-group"
+      ],
+      "patterns": [
+        "pattern:shell-page"
+      ],
+      "accessibility": [
+        "ShellPage exposes the routed page as the main landmark; render exactly one active ShellPage inside ShellApp.",
+        "Provide exactly one BarTitle through the header slot so the page has one h1.",
+        "Keep loading, empty, validation, error, progress, success, and failure communication in the default product-content slot.",
+        "Responsive variant changes preserve the same heading, controls, accessible names, and keyboard focus targets."
+      ],
+      "states": [
+        "headerPresentation=auto selects expanded, compact, or constrained from ShellPage's own inline capacity and scroll position.",
+        "expanded, compact, and constrained are explicit overrides for exceptional layouts and deterministic examples.",
+        "contentInset=default supplies standard page gutters; none permits maps, canvases, and other full-bleed content.",
+        "The required header slot accepts one BarTitle. The default slot owns router output and all page product content."
+      ],
+      "responsiveBehavior": [
+        "ShellPage observes its own rendered width instead of viewport media queries or ShellApp desktop/tablet modes.",
+        "Roomy pages expand at the top and compact after scroll; medium-capacity pages start compact; narrow pages use the constrained header variant.",
+        "A newly navigated header resolves current page capacity before it is revealed, so persistent tool or navigation chrome cannot flash the expanded presentation first.",
+        "Token-based capacity bands use hysteresis so opening tools or resizing navigation cannot oscillate near a boundary.",
+        "Scroll compaction preserves the expanded page flow offset so content never jumps beneath the sticky header.",
+        "ShellPage relies on ShellApp's content scroller and never introduces nested scrolling."
+      ],
+      "frameworkCaveats": {
+        "customElements": [
+          "Import ShellPage and BarTitle, place one ds-bar-title in slot=header, and render route content as default children.",
+          "Do not set BarTitle.variant while ShellPage owns headerPresentation."
+        ],
+        "react": [
+          "Render DsBarTitle with slot=header inside DsShellPage and keep routed content as the remaining children.",
+          "Use contentInset none only for deliberately full-bleed page products."
+        ],
+        "angular": [
+          "Import the generated standalone DsShellPage and DsBarTitle adapters, preserve slot=header, and place router-outlet in the ShellPage default slot.",
+          "Do not add another overflow auto wrapper around the routed page."
+        ]
+      },
+      "references": [
+        {
+          "label": "Page-family and responsive examples",
+          "path": "src/wc/components/ShellPage/ShellPage.stories.ts"
+        },
+        {
+          "label": "Cross-browser geometry and interaction coverage",
+          "path": "tests/e2e/bar-title.spec.ts"
+        },
+        {
+          "label": "Reusable framework composition",
+          "path": "agent/patterns/shell-page/pattern.agent.json"
+        }
+      ]
+    },
+    "api": {
+      "props": {
+        "contentInset": {
+          "type": "ShellPageContentInset",
+          "resolvedType": "\"default\" | \"none\"",
+          "attribute": "content-inset",
+          "default": "'default'",
+          "required": false,
+          "mutable": false,
+          "description": "Standard page gutters, or no inset for full-bleed page content."
+        },
+        "headerPresentation": {
+          "type": "ShellPageHeaderPresentation",
+          "resolvedType": "\"auto\" | \"compact\" | \"constrained\" | \"expanded\"",
+          "attribute": "header-presentation",
+          "default": "'auto'",
+          "required": false,
+          "mutable": false,
+          "description": "Automatic container/scroll behavior, or an explicit header variant override."
+        }
+      },
+      "events": [],
+      "methods": [],
+      "slots": []
+    },
+    "props": {
+      "contentInset": {
+        "type": "ShellPageContentInset",
+        "resolvedType": "\"default\" | \"none\"",
+        "attribute": "content-inset",
+        "default": "'default'",
+        "required": false,
+        "mutable": false,
+        "description": "Standard page gutters, or no inset for full-bleed page content."
+      },
+      "headerPresentation": {
+        "type": "ShellPageHeaderPresentation",
+        "resolvedType": "\"auto\" | \"compact\" | \"constrained\" | \"expanded\"",
+        "attribute": "header-presentation",
+        "default": "'auto'",
+        "required": false,
+        "mutable": false,
+        "description": "Automatic container/scroll behavior, or an explicit header variant override."
+      }
+    },
+    "events": [],
+    "methods": [],
+    "slots": [],
+    "exports": {
+      "customElement": "ds-shell-page",
+      "react": "DsShellPage",
+      "angular": "DsShellPage"
+    },
+    "consumption": {
+      "install": "npm install @ds-mo/ui @ds-mo/tokens @ds-mo/icons",
+      "cssSetup": "import '@ds-mo/tokens';\nimport '@ds-mo/tokens/reset';\nimport '@ds-mo/tokens/globals';",
+      "customElements": {
+        "import": "import '@ds-mo/ui/dist/components/ds-shell-page.js';",
+        "example": "<ds-shell-page></ds-shell-page>"
+      },
+      "react": {
+        "import": "import { DsShellPage } from '@ds-mo/ui/react';",
+        "example": "<DsShellPage />"
+      },
+      "angular": {
+        "import": "import { DsShellPage } from '@ds-mo/ui/angular/ds-shell-page';",
+        "example": "<ds-shell-page></ds-shell-page>"
+      },
+      "peerDependencies": {
+        "required": [
+          "@ds-mo/tokens ^3.1.1",
+          "@ds-mo/icons ^6.4.0"
+        ],
+        "frameworks": "Custom Elements; React 18/19 wrappers; Angular 19-22 standalone adapters."
+      }
+    }
+  },
+  "dependencies": [
+    "@ds-mo/ui",
+    "@ds-mo/tokens"
+  ],
+  "registryDependencies": [],
+  "files": [
+    {
+      "path": "src/wc/components/ShellPage/ShellPage.css",
+      "content": ":host {\n  display: block;\n  position: relative;\n  min-width: 0;\n  min-height: 100%;\n  box-sizing: border-box;\n  background: var(--color-background-primary);\n}\n\n.shell-page__scroll-sentinel {\n  position: absolute;\n  inset-block-start: 0;\n  inset-inline-start: 0;\n  width: var(--dimension-stroke-width-012);\n  height: var(--dimension-stroke-width-012);\n  pointer-events: none;\n}\n\n.shell-page__sticky-header {\n  position: sticky;\n  inset-block-start: 0;\n  z-index: var(--dimension-z-index-raised);\n  min-width: 0;\n  background: var(--color-background-primary);\n  overflow: visible;\n  overflow-anchor: none;\n}\n\n.shell-page__sticky-header ::slotted(ds-bar-title) {\n  display: block;\n  min-width: 0;\n}\n\n.shell-page__flow-spacer {\n  height: var(--ds-shell-page-flow-spacer, 0);\n  background: var(--color-background-primary);\n}\n\n.shell-page__content {\n  min-width: 0;\n  box-sizing: border-box;\n  background: var(--color-background-primary);\n}\n\n:host(.shell-page-host--inset-default) .shell-page__content {\n  padding: var(--dimension-space-400) var(--dimension-space-400) var(--dimension-space-800);\n}\n\n:host(.shell-page-host--inset-none) .shell-page__content {\n  padding: 0;\n}\n",
+      "type": "registry:ui"
+    },
+    {
+      "path": "src/wc/components/ShellPage/ShellPage.tsx",
+      "content": "import { Component, Element, h, Host, Prop, State } from '@stencil/core';\nimport { createRafCoalescer } from '../../shell/chrome-transition';\nimport { resolveCssLengthPx } from '../../utils/resolve-css-length-px';\nimport type { BarTitleVariant } from '../BarTitle/bar-title-types';\nimport { resolveShellPageCapacity, resolveShellPageHeaderVariant } from './shell-page-responsive';\nimport type {\n  ShellPageCapacity,\n  ShellPageContentInset,\n  ShellPageHeaderPresentation,\n} from './shell-page-types';\n\ntype BarTitleElement = HTMLElement & { variant: BarTitleVariant };\n\n@Component({\n  tag: 'ds-shell-page',\n  styleUrl: 'ShellPage.css',\n  scoped: true,\n})\nexport class ShellPage {\n  private static readonly MAX_HEADER_REVEAL_FRAMES = 12;\n\n  @Element() el!: HTMLElement;\n\n  /** Automatic container/scroll behavior, or an explicit header variant override. */\n  @Prop() headerPresentation: ShellPageHeaderPresentation = 'auto';\n\n  /** Standard page gutters, or no inset for full-bleed page content. */\n  @Prop() contentInset: ShellPageContentInset = 'default';\n\n  @State() private capacity: ShellPageCapacity | null = null;\n  @State() private pageTopVisible = true;\n\n  private sentinelEl: HTMLElement | null = null;\n  private spacerEl: HTMLElement | null = null;\n  private headerEl: BarTitleElement | null = null;\n  private expandedHeaderHeight = 0;\n  private resizeObserver: ResizeObserver | null = null;\n  private headerResizeObserver: ResizeObserver | null = null;\n  private headerRevealFrame: number | null = null;\n  private scrollRoot: HTMLElement | Window | null = null;\n  private readonly layoutCoalescer = createRafCoalescer(() => this.syncCapacity());\n\n  componentDidLoad() {\n    // Resolve the already-laid-out page width before adopting a slotted header.\n    // Waiting for the first ResizeObserver/RAF lets BarTitle paint its default\n    // expanded variant for one frame when persistent shell chrome narrows a\n    // newly navigated page.\n    this.syncCapacity();\n    this.observeHeader(this.findHeader());\n    this.connectObservers();\n    this.connectScrollRoot();\n    this.layoutCoalescer.schedule();\n  }\n\n  componentDidRender() {\n    this.syncHeaderVariant();\n  }\n\n  disconnectedCallback() {\n    this.resizeObserver?.disconnect();\n    this.resizeObserver = null;\n    this.headerResizeObserver?.disconnect();\n    this.headerResizeObserver = null;\n    this.cancelHeaderReveal();\n    this.scrollRoot?.removeEventListener('scroll', this.handleScroll);\n    this.scrollRoot = null;\n    this.layoutCoalescer.cancel();\n  }\n\n  private get effectiveVariant(): BarTitleVariant {\n    return resolveShellPageHeaderVariant(\n      this.headerPresentation,\n      this.capacity ?? 'roomy',\n      this.pageTopVisible\n    );\n  }\n\n  private get isScrollCompacted(): boolean {\n    return this.headerPresentation === 'auto' && this.capacity === 'roomy' && !this.pageTopVisible;\n  }\n\n  private connectObservers() {\n    if (typeof ResizeObserver !== 'undefined') {\n      this.resizeObserver = new ResizeObserver(() => this.layoutCoalescer.schedule());\n      this.resizeObserver.observe(this.el);\n    }\n  }\n\n  private composedParent(element: Element): Element | null {\n    return (element as HTMLElement).assignedSlot?.parentElement ?? element.parentElement;\n  }\n\n  private findScrollRoot(): HTMLElement | Window {\n    let ancestor = this.composedParent(this.el);\n    while (ancestor && ancestor !== document.documentElement) {\n      const overflow = getComputedStyle(ancestor).overflowY;\n      if (overflow === 'auto' || overflow === 'scroll') return ancestor as HTMLElement;\n      ancestor = this.composedParent(ancestor);\n    }\n    return window;\n  }\n\n  private connectScrollRoot() {\n    this.scrollRoot?.removeEventListener('scroll', this.handleScroll);\n    this.scrollRoot = this.findScrollRoot();\n    this.scrollRoot.addEventListener('scroll', this.handleScroll, { passive: true });\n    this.handleScroll();\n  }\n\n  private handleScroll = () => {\n    if (!this.sentinelEl || !this.scrollRoot) return;\n    const rootTop =\n      this.scrollRoot === window ? 0 : (this.scrollRoot as HTMLElement).getBoundingClientRect().top;\n    this.pageTopVisible = this.sentinelEl.getBoundingClientRect().top >= rootTop;\n  };\n\n  private findHeader(): BarTitleElement | null {\n    return this.el.querySelector<BarTitleElement>('ds-bar-title');\n  }\n\n  private syncCapacity() {\n    const inlineSize = this.el.getBoundingClientRect().width;\n    if (inlineSize <= 0) return;\n\n    const compactAt = resolveCssLengthPx('--dimension-panel-width-2xl', 0);\n    const constrainedAt = resolveCssLengthPx('--dimension-panel-width-lg', 0);\n    const hysteresis = resolveCssLengthPx('--dimension-space-100', 0);\n    if (compactAt <= 0 || constrainedAt <= 0) return;\n\n    const next = resolveShellPageCapacity({\n      inlineSize,\n      compactAt,\n      constrainedAt,\n      hysteresis,\n      previous: this.capacity,\n    });\n    if (next !== this.capacity) this.capacity = next;\n    else this.syncHeaderVariant();\n  }\n\n  private get compactHeaderHeight(): number {\n    return resolveCssLengthPx('--dimension-size-600', 0);\n  }\n\n  private setSpacerHeight(height: number) {\n    if (!this.spacerEl) return;\n    this.spacerEl.style.setProperty('--ds-shell-page-flow-spacer', `${Math.max(0, height)}px`);\n  }\n\n  private variantClass(variant: BarTitleVariant): string {\n    return `bar-title-host--${variant}`;\n  }\n\n  private cancelHeaderReveal() {\n    if (this.headerRevealFrame !== null) cancelAnimationFrame(this.headerRevealFrame);\n    this.headerRevealFrame = null;\n    this.headerEl?.removeAttribute('data-shell-page-syncing');\n  }\n\n  private revealHeaderWhenSynced(header: BarTitleElement, variant: BarTitleVariant) {\n    // Stencil re-renders within a frame or two of a prop change, but this cap\n    // guarantees the header can never stay hidden indefinitely if that\n    // assumption ever breaks.\n    let framesRemaining = ShellPage.MAX_HEADER_REVEAL_FRAMES;\n    const reveal = () => {\n      if (this.headerEl !== header) {\n        header.removeAttribute('data-shell-page-syncing');\n        return;\n      }\n      framesRemaining -= 1;\n      if (framesRemaining <= 0 || header.classList.contains(this.variantClass(variant))) {\n        header.removeAttribute('data-shell-page-syncing');\n        this.headerRevealFrame = null;\n        return;\n      }\n      this.headerRevealFrame = requestAnimationFrame(reveal);\n    };\n    this.headerRevealFrame = requestAnimationFrame(reveal);\n  }\n\n  private syncHeaderVariant(concealUntilSynced = false) {\n    const header = this.headerEl;\n    if (!header) return;\n\n    const next = this.effectiveVariant;\n    if (header.variant === 'expanded') {\n      this.expandedHeaderHeight = header.getBoundingClientRect().height;\n    }\n\n    this.setSpacerHeight(\n      this.isScrollCompacted ? this.expandedHeaderHeight - this.compactHeaderHeight : 0\n    );\n\n    const renderedVariantIsStale = !header.classList.contains(this.variantClass(next));\n    if (concealUntilSynced && renderedVariantIsStale) {\n      header.setAttribute('data-shell-page-syncing', '');\n    }\n    if (header.variant !== next) header.variant = next;\n    if (concealUntilSynced && renderedVariantIsStale) {\n      this.revealHeaderWhenSynced(header, next);\n    }\n  }\n\n  private observeHeader(header: BarTitleElement | null) {\n    this.cancelHeaderReveal();\n    this.headerResizeObserver?.disconnect();\n    this.headerResizeObserver = null;\n    this.headerEl = header;\n    this.expandedHeaderHeight = 0;\n    this.setSpacerHeight(0);\n\n    if (!header) return;\n    if (typeof ResizeObserver !== 'undefined') {\n      this.headerResizeObserver = new ResizeObserver(() => {\n        if (header.variant === 'expanded') {\n          this.expandedHeaderHeight = header.getBoundingClientRect().height;\n        }\n      });\n      this.headerResizeObserver.observe(header);\n    }\n    this.syncHeaderVariant(true);\n  }\n\n  private handleHeaderSlotChange = (event: Event) => {\n    const slot = event.target as HTMLSlotElement;\n    const header = slot\n      .assignedElements({ flatten: true })\n      .find(element => element.tagName.toLowerCase() === 'ds-bar-title');\n    this.observeHeader((header as BarTitleElement | undefined) ?? null);\n  };\n\n  render() {\n    return (\n      <Host\n        role=\"main\"\n        class={{\n          'shell-page-host--inset-default': this.contentInset === 'default',\n          'shell-page-host--inset-none': this.contentInset === 'none',\n          [`shell-page-host--header-${this.effectiveVariant}`]: true,\n        }}\n      >\n        <div\n          ref={el => {\n            this.sentinelEl = el ?? null;\n          }}\n          class=\"shell-page__scroll-sentinel\"\n          aria-hidden=\"true\"\n        />\n        <div class=\"shell-page__sticky-header\">\n          <slot name=\"header\" onSlotchange={this.handleHeaderSlotChange} />\n        </div>\n        <div\n          ref={el => {\n            this.spacerEl = el ?? null;\n          }}\n          class=\"shell-page__flow-spacer\"\n          aria-hidden=\"true\"\n        />\n        <div class=\"shell-page__content\">\n          <slot />\n        </div>\n      </Host>\n    );\n  }\n}\n",
+      "type": "registry:ui"
+    },
+    {
+      "path": "src/wc/components/ShellPage/shell-page-responsive.ts",
+      "content": "import type { ShellPageCapacity, ShellPageHeaderPresentation } from './shell-page-types';\nimport type { BarTitleVariant } from '../BarTitle/bar-title-types';\n\nexport interface ShellPageCapacityOptions {\n  inlineSize: number;\n  compactAt: number;\n  constrainedAt: number;\n  hysteresis: number;\n  previous: ShellPageCapacity | null;\n}\n\nexport function resolveShellPageCapacity({\n  inlineSize,\n  compactAt,\n  constrainedAt,\n  hysteresis,\n  previous,\n}: ShellPageCapacityOptions): ShellPageCapacity {\n  if (previous === null) {\n    if (inlineSize <= constrainedAt) return 'constrained';\n    if (inlineSize <= compactAt) return 'compact';\n    return 'roomy';\n  }\n\n  if (previous === 'constrained') {\n    if (inlineSize <= constrainedAt + hysteresis) return 'constrained';\n    return inlineSize <= compactAt ? 'compact' : 'roomy';\n  }\n\n  if (inlineSize <= constrainedAt) return 'constrained';\n\n  if (previous === 'compact') {\n    return inlineSize <= compactAt + hysteresis ? 'compact' : 'roomy';\n  }\n\n  return inlineSize <= compactAt ? 'compact' : 'roomy';\n}\n\nexport function resolveShellPageHeaderVariant(\n  presentation: ShellPageHeaderPresentation,\n  capacity: ShellPageCapacity,\n  pageTopVisible: boolean\n): BarTitleVariant {\n  if (presentation !== 'auto') return presentation;\n  if (capacity === 'constrained') return 'constrained';\n  if (capacity === 'compact' || !pageTopVisible) return 'compact';\n  return 'expanded';\n}\n",
+      "type": "registry:ui"
+    },
+    {
+      "path": "src/wc/components/ShellPage/shell-page-types.ts",
+      "content": "import type { BarTitleVariant } from '../BarTitle/bar-title-types';\n\nexport type ShellPageHeaderPresentation = 'auto' | BarTitleVariant;\n\nexport type ShellPageContentInset = 'default' | 'none';\n\nexport type ShellPageCapacity = 'roomy' | 'compact' | 'constrained';\n",
+      "type": "registry:ui"
+    }
+  ]
+}

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

@@ -256,7 +256,7 @@
       "peerDependencies": {
         "required": [
           "@ds-mo/tokens ^3.1.1",
-          "@ds-mo/icons ^6.3.0"
+          "@ds-mo/icons ^6.4.0"
         ],
         "frameworks": "Custom Elements; React 18/19 wrappers; Angular 19-22 standalone adapters."
       }

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

@@ -629,7 +629,7 @@
       "peerDependencies": {
         "required": [
           "@ds-mo/tokens ^3.1.1",
-          "@ds-mo/icons ^6.3.0"
+          "@ds-mo/icons ^6.4.0"
         ],
         "frameworks": "Custom Elements; React 18/19 wrappers; Angular 19-22 standalone adapters."
       }