symbiote-ui 0.3.0-alpha.39 → 0.3.0-alpha.40

package/custom-elements.json

@@ -3657,9 +3657,9 @@
             }
           ],
           "agent": {
-            "componentDescription": "Generic hierarchical graph overview/read renderer with force layout, semantic navigation, and selection events. Use this interactive visual graph surface when composing canvas UI. Capabilities: hierarchical-graph, overview-read-renderer, force-layout, semantic-clusters, focus-selection, layout-snapshot. Data ownership: host-owned model; component renders and emits intent events. WebMCP tools: canvas_graph_set_model, canvas_graph_focus_node, canvas_graph_focus_nodes, canvas_graph_set_path.",
+            "componentDescription": "Generic hierarchical graph overview/read renderer with force layout, semantic navigation, selection events, and optional device-orientation parallax. Use this interactive visual graph surface when composing canvas UI. Capabilities: hierarchical-graph, overview-read-renderer, force-layout, semantic-clusters, focus-selection, layout-snapshot, device-orientation-parallax. Data ownership: host-owned model; component renders and emits intent events. WebMCP tools: canvas_graph_set_model, canvas_graph_focus_node, canvas_graph_focus_nodes, canvas_graph_set_path.",
             "semanticRole": "interactive visual graph surface",
-            "usage": "Render or compose <canvas-graph> when the host needs generic hierarchical graph overview/read renderer with force layout, semantic navigation, and selection events.",
+            "usage": "Render or compose <canvas-graph> when the host needs generic hierarchical graph overview/read renderer with force layout, semantic navigation, selection events, and optional device-orientation parallax.",
             "dataOwnership": "host-owned model; component renders and emits intent events",
             "webmcp": {
               "mode": "explicit-descriptor",

package/manifest/component-registry.js

@@ -3259,7 +3259,7 @@ export let COMPONENTS = [
     className: 'CanvasGraph',
     module: 'canvas/CanvasGraph/CanvasGraph.js',
     category: 'canvas',
-    description: 'Generic hierarchical graph overview/read renderer with force layout, semantic navigation, and selection events.',
+    description: 'Generic hierarchical graph overview/read renderer with force layout, semantic navigation, selection events, and optional device-orientation parallax.',
     contract: {
       status: 'draft',
       schemaVersion: 'component-descriptor-v2',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "symbiote-ui",
-  "version": "0.3.0-alpha.39",
+  "version": "0.3.0-alpha.40",
   "type": "module",
   "description": "Symbiote provider UI, Web Components, themes, manifests, schemas, graph layout helpers, WebMCP metadata, and SSR-safe UI contracts.",
   "main": "index.js",

package/themes/CascadeThemeWidget/CascadeThemeWidget.css.js

@@ -7,189 +7,231 @@ export default css`
     align-items: center;
     color: var(--sn-text);
     font-family: var(--sn-font);
+  }
 
-    &[hidden] {
-      display: none !important;
-    }
+  cascade-theme-widget[hidden] {
+    display: none !important;
+  }
 
-    .ctw-trigger {
-      flex: 0 0 auto;
-    }
+  cascade-theme-widget .ctw-trigger {
+    flex: 0 0 auto;
+  }
 
-    .ctw-trigger .material-symbols-outlined,
-    .ctw-header-actions .material-symbols-outlined {
-      font-size: var(--sn-shell-menu-action-icon-size, var(--sn-layout-header-icon-size, 16px));
-    }
+  cascade-theme-widget .ctw-trigger .material-symbols-outlined,
+  cascade-theme-widget .ctw-header-actions .material-symbols-outlined,
+  .ctw-popover[data-overlay-portal] .ctw-header-actions .material-symbols-outlined {
+    font-size: var(--sn-shell-menu-action-icon-size, var(--sn-layout-header-icon-size, 16px));
+  }
 
-    .ctw-popover {
-      position: absolute;
-      top: calc(100% + var(--sn-theme-widget-offset, 8px));
-      right: 0;
-      z-index: var(--sn-theme-widget-z, 80);
-      display: grid;
-      grid-template-rows: auto auto auto;
-      gap: var(--sn-theme-widget-gap, calc(8px * var(--sn-theme-density, 1)));
-      width: min(92vw, var(--sn-theme-widget-width, 320px));
-      padding: var(--sn-theme-widget-padding, calc(10px * var(--sn-theme-density, 1)));
-      border: var(--sn-node-border-width, 1px) solid var(--sn-node-border);
-      border-radius: var(--sn-node-radius, 8px);
-      background: var(--sn-panel-bg);
-      box-shadow: var(--sn-panel-shadow, 0 16px 48px hsl(0 0% 0% / 0.28));
-      color: var(--sn-text);
-    }
+  cascade-theme-widget .ctw-popover,
+  .ctw-popover[data-overlay-portal] {
+    z-index: var(--sn-theme-widget-z, var(--sn-overlay-z-base, 20000));
+    display: grid;
+    grid-template-rows: auto auto auto;
+    gap: var(--sn-theme-widget-gap, calc(8px * var(--sn-theme-density, 1)));
+    width: min(92vw, var(--sn-theme-widget-width, 320px));
+    max-width: calc(100vw - 16px);
+    padding: var(--sn-theme-widget-padding, calc(10px * var(--sn-theme-density, 1)));
+    border: var(--sn-node-border-width, 1px) solid var(--sn-node-border);
+    border-radius: var(--sn-node-radius, 8px);
+    background: var(--sn-panel-bg);
+    box-shadow: var(--sn-panel-shadow, 0 16px 48px hsl(0 0% 0% / 0.28));
+    color: var(--sn-text);
+    font-family: var(--sn-font);
+  }
 
-    .ctw-popover[hidden] {
-      display: none;
-    }
+  cascade-theme-widget .ctw-popover {
+    position: absolute;
+    top: calc(100% + var(--sn-theme-widget-offset, 8px));
+    right: 0;
+  }
 
-    .ctw-header,
-    .ctw-header-actions,
-    .ctw-control,
-    .ctw-control-head,
-    .ctw-mode {
-      display: flex;
-      align-items: center;
-      min-width: 0;
-    }
+  .ctw-popover[data-overlay-portal] {
+    position: fixed;
+    top: 0;
+    left: 0;
+    right: auto;
+  }
 
-    .ctw-header {
-      justify-content: space-between;
-      gap: var(--sn-theme-widget-gap, 8px);
-    }
+  cascade-theme-widget .ctw-popover[hidden],
+  .ctw-popover[data-overlay-portal][hidden] {
+    display: none;
+  }
 
-    .ctw-header strong {
-      min-width: 0;
-      overflow: hidden;
-      font-size: var(--sn-theme-widget-title-size, var(--sn-app-title-size, 13px));
-      text-overflow: ellipsis;
-      white-space: nowrap;
-    }
+  cascade-theme-widget .ctw-header,
+  cascade-theme-widget .ctw-header-actions,
+  cascade-theme-widget .ctw-control,
+  cascade-theme-widget .ctw-control-head,
+  cascade-theme-widget .ctw-mode,
+  .ctw-popover[data-overlay-portal] .ctw-header,
+  .ctw-popover[data-overlay-portal] .ctw-header-actions,
+  .ctw-popover[data-overlay-portal] .ctw-control,
+  .ctw-popover[data-overlay-portal] .ctw-control-head,
+  .ctw-popover[data-overlay-portal] .ctw-mode {
+    display: flex;
+    align-items: center;
+    min-width: 0;
+  }
 
-    .ctw-header-actions {
-      gap: var(--sn-theme-widget-action-gap, 4px);
-    }
+  cascade-theme-widget .ctw-header,
+  .ctw-popover[data-overlay-portal] .ctw-header {
+    justify-content: space-between;
+    gap: var(--sn-theme-widget-gap, 8px);
+  }
 
-    .ctw-header-actions button,
-    .ctw-mode button {
-      display: inline-flex;
-      align-items: center;
-      justify-content: center;
-      border: 1px solid var(--sn-button-border, var(--sn-node-border));
-      border-radius: var(--sn-button-radius, 6px);
-      background: var(--sn-button-bg, var(--sn-node-bg));
-      color: var(--sn-button-color, var(--sn-text));
-      font: inherit;
-      cursor: pointer;
-    }
+  cascade-theme-widget .ctw-header strong,
+  .ctw-popover[data-overlay-portal] .ctw-header strong {
+    min-width: 0;
+    overflow: hidden;
+    font-size: var(--sn-theme-widget-title-size, var(--sn-app-title-size, 13px));
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
 
-    .ctw-header-actions button {
-      width: var(--sn-theme-widget-icon-button-size, var(--sn-theme-editor-icon-button-size, 28px));
-      min-width: var(--sn-theme-widget-icon-button-size, var(--sn-theme-editor-icon-button-size, 28px));
-      height: var(--sn-theme-widget-icon-button-size, var(--sn-theme-editor-icon-button-size, 28px));
-      padding: 0;
-    }
+  cascade-theme-widget .ctw-header-actions,
+  .ctw-popover[data-overlay-portal] .ctw-header-actions {
+    gap: var(--sn-theme-widget-action-gap, 4px);
+  }
 
-    .ctw-mode {
-      display: grid;
-      grid-template-columns: repeat(2, minmax(0, 1fr));
-      gap: var(--sn-theme-widget-mode-gap, 4px);
-      padding: var(--sn-theme-widget-mode-padding, 3px);
-      border: 1px solid var(--sn-node-border);
-      border-radius: var(--sn-node-radius, 8px);
-      background: var(--sn-bg);
-    }
+  cascade-theme-widget .ctw-header-actions button,
+  cascade-theme-widget .ctw-mode button,
+  .ctw-popover[data-overlay-portal] .ctw-header-actions button,
+  .ctw-popover[data-overlay-portal] .ctw-mode button {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    border: 1px solid var(--sn-button-border, var(--sn-node-border));
+    border-radius: var(--sn-button-radius, 6px);
+    background: var(--sn-button-bg, var(--sn-node-bg));
+    color: var(--sn-button-color, var(--sn-text));
+    font: inherit;
+    cursor: pointer;
+  }
 
-    .ctw-mode button {
-      min-width: 0;
-      min-height: var(--sn-theme-widget-mode-height, var(--sn-button-min-height, 28px));
-      padding: var(--sn-theme-widget-mode-button-padding, 5px 10px);
-      color: var(--sn-text-dim);
-      font-size: var(--sn-theme-widget-control-size, var(--sn-button-font-size, 12px));
-    }
+  cascade-theme-widget .ctw-header-actions button,
+  .ctw-popover[data-overlay-portal] .ctw-header-actions button {
+    width: var(--sn-theme-widget-icon-button-size, var(--sn-theme-editor-icon-button-size, 28px));
+    min-width: var(--sn-theme-widget-icon-button-size, var(--sn-theme-editor-icon-button-size, 28px));
+    height: var(--sn-theme-widget-icon-button-size, var(--sn-theme-editor-icon-button-size, 28px));
+    padding: 0;
+  }
 
-    .ctw-mode button[aria-pressed="true"] {
-      border-color: var(--sn-button-primary-border, var(--sn-node-selected));
-      background: var(--sn-button-primary-bg, var(--sn-node-selected));
-      color: var(--sn-button-primary-color, var(--sn-bg));
-    }
+  cascade-theme-widget .ctw-mode,
+  .ctw-popover[data-overlay-portal] .ctw-mode {
+    display: grid;
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    gap: var(--sn-theme-widget-mode-gap, 4px);
+    padding: var(--sn-theme-widget-mode-padding, 3px);
+    border: 1px solid var(--sn-node-border);
+    border-radius: var(--sn-node-radius, 8px);
+    background: var(--sn-bg);
+  }
 
-    .ctw-controls {
-      display: grid;
-      gap: var(--sn-theme-widget-control-gap, 7px);
-      min-width: 0;
-    }
+  cascade-theme-widget .ctw-mode button,
+  .ctw-popover[data-overlay-portal] .ctw-mode button {
+    min-width: 0;
+    min-height: var(--sn-theme-widget-mode-height, var(--sn-button-min-height, 28px));
+    padding: var(--sn-theme-widget-mode-button-padding, 5px 10px);
+    color: var(--sn-text-dim);
+    font-size: var(--sn-theme-widget-control-size, var(--sn-button-font-size, 12px));
+  }
 
-    .ctw-control {
-      display: grid;
-      grid-template-columns: minmax(82px, 0.52fr) minmax(96px, 1fr) minmax(34px, auto);
-      gap: var(--sn-theme-widget-control-gap, 7px);
-      color: var(--sn-text-dim);
-      font-size: var(--sn-theme-widget-control-size, var(--sn-theme-editor-control-size, 12px));
-    }
+  cascade-theme-widget .ctw-mode button[aria-pressed="true"],
+  .ctw-popover[data-overlay-portal] .ctw-mode button[aria-pressed="true"] {
+    border-color: var(--sn-button-primary-border, var(--sn-node-selected));
+    background: var(--sn-button-primary-bg, var(--sn-node-selected));
+    color: var(--sn-button-primary-color, var(--sn-bg));
+  }
 
-    .ctw-control-head {
-      gap: var(--sn-theme-widget-control-gap, 7px);
-    }
+  cascade-theme-widget .ctw-controls,
+  .ctw-popover[data-overlay-portal] .ctw-controls {
+    display: grid;
+    gap: var(--sn-theme-widget-control-gap, 7px);
+    min-width: 0;
+  }
 
-    .ctw-control-icon {
-      width: var(--sn-theme-widget-control-icon-box, calc(18px * var(--sn-theme-density, 1)));
-      color: var(--sn-node-selected);
-      font-size: var(--sn-theme-widget-control-icon-size, var(--sn-layout-header-icon-size, 16px));
-      line-height: 1;
-      text-align: center;
-    }
+  cascade-theme-widget .ctw-control,
+  .ctw-popover[data-overlay-portal] .ctw-control {
+    display: grid;
+    grid-template-columns: minmax(82px, 0.52fr) minmax(96px, 1fr) minmax(34px, auto);
+    gap: var(--sn-theme-widget-control-gap, 7px);
+    color: var(--sn-text-dim);
+    font-size: var(--sn-theme-widget-control-size, var(--sn-theme-editor-control-size, 12px));
+  }
 
-    .ctw-control label {
-      overflow: hidden;
-      text-overflow: ellipsis;
-      white-space: nowrap;
-    }
+  cascade-theme-widget .ctw-control-head,
+  .ctw-popover[data-overlay-portal] .ctw-control-head {
+    gap: var(--sn-theme-widget-control-gap, 7px);
+  }
 
-    .ctw-control input {
-      width: 100%;
-      min-width: 0;
-      height: var(--sn-theme-widget-range-hit-size, 34px);
-      accent-color: var(--sn-node-selected);
-    }
+  cascade-theme-widget .ctw-control-icon,
+  .ctw-popover[data-overlay-portal] .ctw-control-icon {
+    width: var(--sn-theme-widget-control-icon-box, calc(18px * var(--sn-theme-density, 1)));
+    color: var(--sn-node-selected);
+    font-size: var(--sn-theme-widget-control-icon-size, var(--sn-layout-header-icon-size, 16px));
+    line-height: 1;
+    text-align: center;
+  }
 
-    .ctw-control output {
-      color: var(--sn-text);
-      font-variant-numeric: tabular-nums;
-      text-align: right;
-    }
+  cascade-theme-widget .ctw-control label,
+  .ctw-popover[data-overlay-portal] .ctw-control label {
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
 
-    .ctw-header-actions button:hover,
-    .ctw-mode button:hover {
-      background: var(--sn-button-hover-bg, var(--sn-node-hover));
-    }
+  cascade-theme-widget .ctw-control input,
+  .ctw-popover[data-overlay-portal] .ctw-control input {
+    width: 100%;
+    min-width: 0;
+    height: var(--sn-theme-widget-range-hit-size, 34px);
+    accent-color: var(--sn-node-selected);
+  }
+
+  cascade-theme-widget .ctw-control output,
+  .ctw-popover[data-overlay-portal] .ctw-control output {
+    color: var(--sn-text);
+    font-variant-numeric: tabular-nums;
+    text-align: right;
+  }
+
+  cascade-theme-widget .ctw-header-actions button:hover,
+  cascade-theme-widget .ctw-mode button:hover,
+  .ctw-popover[data-overlay-portal] .ctw-header-actions button:hover,
+  .ctw-popover[data-overlay-portal] .ctw-mode button:hover {
+    background: var(--sn-button-hover-bg, var(--sn-node-hover));
+  }
 
-    .ctw-header-actions button:focus-visible,
-    .ctw-mode button:focus-visible,
-    .ctw-control input:focus-visible,
-    .ctw-trigger:focus-visible {
-      outline: var(--sn-effect-focus-ring, 2px solid var(--sn-node-selected));
-      outline-offset: 2px;
+  cascade-theme-widget .ctw-header-actions button:focus-visible,
+  cascade-theme-widget .ctw-mode button:focus-visible,
+  cascade-theme-widget .ctw-control input:focus-visible,
+  cascade-theme-widget .ctw-trigger:focus-visible,
+  .ctw-popover[data-overlay-portal] .ctw-header-actions button:focus-visible,
+  .ctw-popover[data-overlay-portal] .ctw-mode button:focus-visible,
+  .ctw-popover[data-overlay-portal] .ctw-control input:focus-visible {
+    outline: var(--sn-effect-focus-ring, 2px solid var(--sn-node-selected));
+    outline-offset: 2px;
+  }
+
+  @media (max-width: 820px) {
+    cascade-theme-widget .ctw-trigger-label {
+      display: none;
     }
 
-    @media (max-width: 820px) {
-      .ctw-trigger-label {
-        display: none;
-      }
-
-      .ctw-popover {
-        position: fixed;
-        top: var(--sn-theme-widget-mobile-top, calc(env(safe-area-inset-top) + 88px));
-        right: max(var(--sn-theme-widget-mobile-inset, 8px), env(safe-area-inset-right));
-        left: max(var(--sn-theme-widget-mobile-inset, 8px), env(safe-area-inset-left));
-        width: auto;
-        max-width: none;
-        max-height: calc(
-          100dvh - var(--sn-theme-widget-mobile-top, calc(env(safe-area-inset-top) + 88px)) -
-            max(var(--sn-theme-widget-mobile-inset, 8px), env(safe-area-inset-bottom))
-        );
-        overflow: auto;
-        transform: none;
-      }
+    cascade-theme-widget .ctw-popover,
+    .ctw-popover[data-overlay-portal] {
+      position: fixed;
+      top: var(--sn-theme-widget-mobile-top, calc(env(safe-area-inset-top) + 88px));
+      right: max(var(--sn-theme-widget-mobile-inset, 8px), env(safe-area-inset-right));
+      left: max(var(--sn-theme-widget-mobile-inset, 8px), env(safe-area-inset-left));
+      width: auto;
+      max-width: none;
+      max-height: calc(
+        100dvh - var(--sn-theme-widget-mobile-top, calc(env(safe-area-inset-top) + 88px)) -
+          max(var(--sn-theme-widget-mobile-inset, 8px), env(safe-area-inset-bottom))
+      );
+      overflow: auto;
+      transform: none;
     }
   }
 `;

package/themes/CascadeThemeWidget/CascadeThemeWidget.js

@@ -6,6 +6,12 @@ import {
   getCascadeThemeControls,
   normalizeCascadeThemeOptions,
 } from '../cascade-theme.js';
+import {
+  bringOverlayToFront,
+  mountOverlayToDocument,
+  restoreOverlayHome,
+} from '../../ui/overlay-stack.js';
+import { positionOverlay } from '../../ui/overlay-positioner.js';
 import css from './CascadeThemeWidget.css.js';
 import tpl from './CascadeThemeWidget.tpl.js';
 
@@ -47,13 +53,15 @@ export class CascadeThemeWidget extends Symbiote {
   #controls = getCascadeThemeControls().filter((control) => COMPACT_CONTROLS.includes(control.name));
   #state = normalizeCascadeThemeOptions(CASCADE_THEME_DEFAULTS);
   #ready = false;
+  #popoverBound = false;
+  #overlayListenersBound = false;
 
   init$ = {
     isOpen: false,
     triggerTitle: 'Theme quick controls',
 
     onToggle: () => {
-      this.$.isOpen = !this.$.isOpen;
+      this.#setOpen(!this.$.isOpen);
     },
   };
 
@@ -62,8 +70,8 @@ export class CascadeThemeWidget extends Symbiote {
     this.addEventListener('input', this.#onInput);
     this.addEventListener('click', this.#onClick);
     this._onDocumentPointerDown = (event) => {
-      if (!this.$.isOpen || this.contains(event.target)) return;
-      this.$.isOpen = false;
+      if (!this.$.isOpen || this.#eventTargetsWidget(event)) return;
+      this.#setOpen(false);
     };
     if (typeof document !== 'undefined') {
       document.addEventListener('pointerdown', this._onDocumentPointerDown);
@@ -73,6 +81,8 @@ export class CascadeThemeWidget extends Symbiote {
   disconnectedCallback() {
     this.removeEventListener('input', this.#onInput);
     this.removeEventListener('click', this.#onClick);
+    this.#unbindPopoverEvents();
+    this.#setOpen(false);
     if (typeof document !== 'undefined') {
       document.removeEventListener('pointerdown', this._onDocumentPointerDown);
     }
@@ -90,9 +100,11 @@ export class CascadeThemeWidget extends Symbiote {
   renderCallback() {
     if (this.#ready) return;
     this.#ready = true;
+    this.#bindPopoverEvents();
     this.#renderControls();
     this.#loadStoredState();
     this.#apply('init');
+    if (this.$.isOpen) this.#openPopover();
   }
 
   get state() {
@@ -137,7 +149,7 @@ export class CascadeThemeWidget extends Symbiote {
 
   #onInput = (event) => {
     let input = event.target.closest?.('[data-theme-control]');
-    if (!input || !this.contains(input)) return;
+    if (!input || !this.#elementTargetsWidget(input)) return;
     this.#state = normalizeCascadeThemeOptions({
       ...this.#state,
       [input.dataset.themeControl]: Number(input.value),
@@ -147,7 +159,7 @@ export class CascadeThemeWidget extends Symbiote {
 
   #onClick = (event) => {
     let modeButton = event.target.closest?.('[data-theme-mode]');
-    if (modeButton && this.contains(modeButton)) {
+    if (modeButton && this.#elementTargetsWidget(modeButton)) {
       this.#state = normalizeCascadeThemeOptions({
         ...this.#state,
         mode: modeButton.dataset.themeMode,
@@ -163,7 +175,7 @@ export class CascadeThemeWidget extends Symbiote {
     } else if (action === 'reset') {
       this.reset();
     } else if (action === 'open-full') {
-      this.$.isOpen = false;
+      this.#setOpen(false);
       this.dispatchEvent(new CustomEvent('cascade-theme-open-full', {
         bubbles: true,
         composed: true,
@@ -172,6 +184,108 @@ export class CascadeThemeWidget extends Symbiote {
     }
   };
 
+  #bindPopoverEvents() {
+    let popover = this.ref.popover;
+    if (!popover || this.#popoverBound) return;
+    popover.addEventListener('input', this.#onInput);
+    popover.addEventListener('click', this.#onClick);
+    this.#popoverBound = true;
+  }
+
+  #unbindPopoverEvents() {
+    let popover = this.ref.popover;
+    if (!popover || !this.#popoverBound) return;
+    popover.removeEventListener('input', this.#onInput);
+    popover.removeEventListener('click', this.#onClick);
+    this.#popoverBound = false;
+  }
+
+  #setOpen(open) {
+    let nextOpen = Boolean(open);
+    if (nextOpen === this.$.isOpen) {
+      if (nextOpen) this.#openPopover();
+      return;
+    }
+    this.$.isOpen = nextOpen;
+    if (nextOpen) {
+      this.#openPopover();
+    } else {
+      this.#closePopover();
+    }
+  }
+
+  #openPopover() {
+    let popover = this.ref.popover;
+    if (!popover) return;
+    this.#bindPopoverEvents();
+    popover.hidden = false;
+    mountOverlayToDocument(popover, this);
+    bringOverlayToFront(popover);
+    this.#positionPopover();
+    this.#bindOverlayListeners();
+    if (typeof requestAnimationFrame === 'function') {
+      requestAnimationFrame(() => {
+        if (this.$.isOpen) this.#positionPopover();
+      });
+    }
+  }
+
+  #closePopover() {
+    let popover = this.ref.popover;
+    this.#unbindOverlayListeners();
+    if (!popover) return;
+    popover.hidden = true;
+    popover.style.removeProperty('top');
+    popover.style.removeProperty('left');
+    restoreOverlayHome(popover);
+  }
+
+  #bindOverlayListeners() {
+    if (this.#overlayListenersBound || typeof window === 'undefined') return;
+    window.addEventListener('resize', this.#onOverlayReposition);
+    window.addEventListener('scroll', this.#onOverlayReposition, true);
+    this.#overlayListenersBound = true;
+  }
+
+  #unbindOverlayListeners() {
+    if (!this.#overlayListenersBound || typeof window === 'undefined') return;
+    window.removeEventListener('resize', this.#onOverlayReposition);
+    window.removeEventListener('scroll', this.#onOverlayReposition, true);
+    this.#overlayListenersBound = false;
+  }
+
+  #onOverlayReposition = () => {
+    if (this.$.isOpen) this.#positionPopover();
+  };
+
+  #positionPopover() {
+    let popover = this.ref.popover;
+    let trigger = this.ref.trigger || this.querySelector('.ctw-trigger');
+    if (!popover || !trigger || typeof window === 'undefined') return;
+    if (window.matchMedia?.('(max-width: 820px)')?.matches) {
+      popover.style.removeProperty('top');
+      popover.style.removeProperty('left');
+      return;
+    }
+    let offset = Number.parseFloat(
+      getComputedStyle(trigger).getPropertyValue('--sn-theme-widget-offset') || '8'
+    );
+    positionOverlay(trigger, popover, 'bottom-end', {
+      offset: Number.isFinite(offset) ? offset : 8,
+    });
+  }
+
+  #eventTargetsWidget(event) {
+    let path = event.composedPath?.() || [];
+    let popover = this.ref.popover;
+    return path.includes(this) || (popover && (path.includes(popover) || popover.contains(event.target)));
+  }
+
+  #elementTargetsWidget(element) {
+    let popover = this.ref.popover;
+    return this.contains(element) || Boolean(popover?.contains(element));
+  }
+
   #renderControls() {
     let controls = this.ref.controls;
     if (!controls) return;

package/themes/CascadeThemeWidget/CascadeThemeWidget.tpl.js

@@ -2,6 +2,7 @@ import { html } from '@symbiotejs/symbiote';
 
 export default html`
   <button
+    ref="trigger"
     class="ctw-trigger shell-action"
     type="button"
     aria-haspopup="dialog"
@@ -15,7 +16,13 @@ export default html`
     <span class="material-symbols-outlined" aria-hidden="true">palette</span>
     <span class="ctw-trigger-label">Theme</span>
   </button>
-  <section class="ctw-popover" role="dialog" aria-label="Theme quick controls" ${{ '@hidden': '!isOpen' }}>
+  <section
+    ref="popover"
+    class="ctw-popover"
+    role="dialog"
+    aria-label="Theme quick controls"
+    ${{ '@hidden': '!isOpen' }}
+  >
     <header class="ctw-header">
       <strong>Theme</strong>
       <div class="ctw-header-actions">