@marianmeres/stuic 3.151.0 → 3.153.0

package/AGENTS.md

@@ -28,6 +28,7 @@ src/lib/
 ├── attachments/    # Svelte attachments ({@attach} — preferred for new DOM helpers)
 ├── utils/          # 44 utility modules
 ├── icons/          # Icon re-exports from @marianmeres/icons-fns
+├── css/            # CSS-only presets (ratio-locked frame / letterbox)
 ├── index.css       # Centralized CSS imports
 └── index.ts        # Main exports
 ```
@@ -130,6 +131,7 @@ Global tokens that control cross-component visual properties. Defined in `src/li
 
 - [Components](./docs/domains/components.md) — 63 component directories, Props pattern, snippets
 - [Theming](./docs/domains/theming.md) — CSS tokens, dark mode, themes
+- [CSS presets](./docs/domains/css-presets.md) — ratio-locked frame (letterbox), safe-area, scrollbar
 - [Actions](./docs/domains/actions.md) — 15 Svelte directives
 - [Attachments](./docs/domains/attachments.md) — `{@attach}` DOM helpers (preferred for new ones)
 - [Utils](./docs/domains/utils.md) — 44 utility modules
@@ -138,6 +140,7 @@ Global tokens that control cross-component visual properties. Defined in `src/li
 
 - [Design Tokens Manual](./docs/DESIGN_TOKENS_MANUAL.md) — Token philosophy
 - [Tailwind v4 Variables](./docs/TAILWIND_V4_CSS_VARIABLES.md) — CSS variable reference
+- [Ratio-Locked Frame](./docs/RATIO_LOCKED_FRAME.md) — Letterbox recipes + the measured gotcha list
 
 ---
 

package/API.md

@@ -2193,6 +2193,7 @@ Each component defines customization tokens. Override globally in `:root {}` or
 | Cart               | `--stuic-cart-*`                | `gap`, `item-padding`, `item-radius`, `item-border-color`, `item-bg`, `thumbnail-size`, `quantity-border-color`, `remove-color`, `summary-border-color`, `compact-max-height`, `transition`                                   |
 | LoginForm          | `--stuic-login-form-*`          | `gap`, `gap-row`, `forgot-margin-y`, `forgot-margin-x`, `social-margin-top`, `social-gap`, `social-divider-color`, `social-divider-font-size`, `social-divider-margin-bottom`                                                 |
 | Checkout           | `--stuic-checkout-*`            | `input-border`, `input-bg`, `input-focus-ring`, `input-radius`, `card-border`, `card-bg`, `card-radius`, `step-gap`, `progress-*`, `summary-*`, `guest-*`, `login-*`, `address-*`, `delivery-*`, `review-*`, `confirmation-*` |
+| Frame (CSS preset) | `--stuic-frame-*`               | `aspect-ratio`, `width`, `height` — the ratio-locked frame / letterbox preset (see [CSS presets](docs/domains/css-presets.md))                                                                                                |
 
 ### CSS Variable Naming Convention
 

package/README.md

@@ -248,6 +248,78 @@ All three are no-ops in a browser tab and need no prop.
 
 **Not covered:** remaining fixed/edge-anchored components (e.g. `Float`, or a bare `ModalDialog` used directly) do not auto-handle insets — apply a `stuic-safe-area-*` class or the variables to their content as needed.
 
+## Ratio-locked frame (letterbox)
+
+Lock a box to an aspect ratio, size it to whichever axis binds first, centre it, and let the leftover space become letterboxing — a phone-proportioned column on a desktop, a portrait game board, a 16:9 scene nested under a header. The whole idea is one line:
+
+```
+width = min(available-width, available-height × ratio)   /* aspect-ratio supplies the height */
+```
+
+That formula (plus two guards nobody remembers) is all stuic ships, because it is the only part Tailwind cannot express. The letterbox parent itself is plain utilities: `grid`, `overflow-hidden`, `fixed inset-0`, `bg-*`, and — where you need them — `contain-layout contain-paint`, `overflow-y-auto`, `@container-size`.
+
+**Classes:**
+
+- `.stuic-frame` — the ratio-locked box. Sized against the viewport (`100vw` / `100dvh`), centred with `margin: auto`, `overflow: hidden`.
+- `.stuic-frame-cq` — the same box sized in container-query units, for a frame nested inside a layout rather than anchored to the window. Combine with `.stuic-frame`. **Requires** an ancestor with `container-type: size` (Tailwind `@container-size`); `inline-size` is not enough — `cqh` then falls through to the next container, or silently to the viewport, and you get a ratio-correct but wrongly-scaled frame that tracks the window as you resize.
+- `.stuic-frame-col` — re-align a viewport-space element (a top-layer `<dialog>`, or an overlay portalled to `<body>`) onto the frame's column.
+
+**Tokens** — all three are your inputs. stuic declares none of them anywhere; the defaults below live only as `var()` fallbacks at the usage sites, so a scoped override on the frame element or on any ancestor works:
+
+| Token                        | Default                             | Meaning                                                          |
+| ---------------------------- | ----------------------------------- | ---------------------------------------------------------------- |
+| `--stuic-frame-aspect-ratio` | `1`                                 | width ÷ height — anything `aspect-ratio:` accepts                |
+| `--stuic-frame-width`        | `min(100vw, 100dvh × aspect-ratio)` | wholesale width override (bail-out value: `100vw`)               |
+| `--stuic-frame-height`       | `auto` (⇒ ratio-locked)             | wholesale height override (`100dvh` ⇒ fill height, derive width) |
+
+**Viewport letterbox** — full screen, bars on exactly one axis:
+
+```svelte
+<div class="fixed inset-0 grid overflow-hidden bg-neutral-800">
+	<div
+		class="stuic-frame bg-[var(--stuic-color-surface)]"
+		style="--stuic-frame-aspect-ratio: 0.5"
+	>
+		…
+	</div>
+</div>
+```
+
+**Nested frame** — sized against its parent box instead of the window:
+
+```svelte
+<div class="flex h-dvh flex-col">
+	<header>…</header>
+	<div class="@container-size grid min-h-0 grow overflow-hidden bg-neutral-800">
+		<div
+			class="stuic-frame stuic-frame-cq bg-[var(--stuic-color-surface)]"
+			style="--stuic-frame-aspect-ratio: calc(16 / 9)"
+		>
+			…
+		</div>
+	</div>
+</div>
+```
+
+> ⚠️ **Don't reach for `max-width: 100%; max-height: 100%; aspect-ratio: R`** — the formulation everyone tries first. `max-*` never _grows_ a box, so in a centred grid/flex parent an empty frame measures **0×0**, and one with content shrink-wraps that content and overflows the parent. The ratio usually survives; the size is what's wrong.
+
+> ⚠️ **Never make the frame both the fixed containing block and the scroll container.** `contain-layout contain-paint` together with `overflow-y-auto` on the same element demotes every `position: fixed` descendant to `absolute` against the scroll origin: at `scrollTop: 600` a `Drawer` and its backdrop render at `y = -600`, so the user taps and nothing appears — and `BodyScroll` cannot rescue it, because `document.body` has nothing to scroll in that layout. Scroll an inner element instead, or keep overlays in viewport space and reconcile them with `.stuic-frame-col`.
+
+> ⚠️ **`--stuic-frame-height: 100dvh` is not ratio-locking.** An explicit height beats `aspect-ratio` unconditionally (which is exactly why the bail-out below needs no `!important`), so whenever `100vw < 100dvh × ratio` the frame degenerates to the raw viewport with zero bars on both axes. It looks perfect on a wide desktop and is wrong on the handset you were aiming at. Set it only inside a deliberate bail-out query, and gate that query on more than width:
+
+```css
+@media (max-width: 40rem) and (max-aspect-ratio: 3 / 5) {
+	:root {
+		--stuic-frame-width: 100vw;
+		--stuic-frame-height: 100dvh;
+	}
+}
+```
+
+See [CSS presets](docs/domains/css-presets.md) for the classes, the token contract and the decision tree, and [Ratio-Locked Frame](docs/RATIO_LOCKED_FRAME.md) for the full recipe set (including the unit-free `max-*` variant that _does_ work, given a positioned parent) and the measured gotcha list.
+
+> **This preset does not make stuic's own overlays frame-aware.** `Backdrop`, `Modal`, `Drawer` and `Notifications` measure in viewport units — and top-layer geometry (`showModal()`, `popover`) ignores the frame outright, even for a DOM descendant of it. The portalled actions (`popover`, `spotlight`, `dimBehind`) additionally default to `document.body`, so they leave the frame entirely. Either way they fill the window, not the frame. Pass their `container` option where one exists, apply `.stuic-frame-col`, or tweak the affected call sites.
+
 ## TypeScript
 
 All components export their Props types:

package/dist/actions/dim-behind/dim-behind.fixture.svelte

@@ -0,0 +1,54 @@
+<script lang="ts">
+	import { dimBehind } from "./dim-behind.svelte.js";
+
+	let {
+		aOpen = false,
+		bOpen = false,
+		useContainers = false,
+		sameContainer = false,
+	}: {
+		aOpen?: boolean;
+		bOpen?: boolean;
+		useContainers?: boolean;
+		sameContainer?: boolean;
+	} = $props();
+
+	let containerA = $state<HTMLDivElement>();
+	let containerB = $state<HTMLDivElement>();
+</script>
+
+<!-- Two independent shells, each a fixed containing block + stacking context
+(the framed-app case the `container` option exists for). -->
+<div
+	bind:this={containerA}
+	data-testid="container-a"
+	style="contain: layout paint; width: 200px; height: 120px;"
+>
+	<div
+		data-testid="target-a"
+		use:dimBehind={() => ({
+			open: aOpen,
+			container: useContainers ? () => containerA ?? null : undefined,
+		})}
+	>
+		A
+	</div>
+</div>
+
+<div
+	bind:this={containerB}
+	data-testid="container-b"
+	style="contain: layout paint; width: 200px; height: 120px;"
+>
+	<div
+		data-testid="target-b"
+		use:dimBehind={() => ({
+			open: bOpen,
+			container: useContainers
+				? () => (sameContainer ? (containerA ?? null) : (containerB ?? null))
+				: undefined,
+		})}
+	>
+		B
+	</div>
+</div>

package/dist/actions/dim-behind/dim-behind.fixture.svelte.d.ts

@@ -0,0 +1,9 @@
+type $$ComponentProps = {
+    aOpen?: boolean;
+    bOpen?: boolean;
+    useContainers?: boolean;
+    sameContainer?: boolean;
+};
+declare const DimBehind: import("svelte").Component<$$ComponentProps, {}, "">;
+type DimBehind = ReturnType<typeof DimBehind>;
+export default DimBehind;

package/dist/actions/dim-behind/dim-behind.svelte.d.ts

@@ -48,6 +48,16 @@ export interface DimBehindOptions {
     onHide?: () => void;
     /** Debug mode */
     debug?: boolean;
+    /**
+     * Where to append the backdrop. Defaults to the current behavior:
+     * `document.body`. Pass a bounded shell (framed app, embedded widget,
+     * dashboard pane) to keep the backdrop inside it — required when that shell
+     * is a stacking context, since the elevated target's z-index can then only
+     * compete with a backdrop living in the same context. Each distinct
+     * container gets its own ref-counted backdrop. A function returning `null`
+     * falls back to the default.
+     */
+    container?: HTMLElement | (() => HTMLElement | null);
 }
 /**
  * A Svelte action that dims everything behind a target element.

package/dist/actions/dim-behind/dim-behind.svelte.js

@@ -1,46 +1,60 @@
 import { BodyScroll } from "../../utils/body-scroll-locker.js";
-// --- Singleton Backdrop Manager ---
-let backdropEl = null;
-let activeCount = 0;
+import { resolveContainerOption } from "../../utils/overlay-container.js";
+// --- Shared Backdrop Manager (one ref-counted backdrop per container) ---
+const backdrops = new Map();
 const TRANSITION_SAFETY_MARGIN = 50;
-function getTransitionDuration() {
-    const raw = getComputedStyle(document.documentElement)
-        .getPropertyValue("--stuic-dim-behind-transition-duration")
-        .trim();
-    return parseFloat(raw) || 150;
+/**
+ * Actual transition duration of the backdrop element in ms — read from its
+ * computed style, which resolves the whole var chain
+ * (`--stuic-dim-behind-transition-duration`, `--stuic-transition`, …), unlike
+ * reading a single custom property off the root. Computed values serialize in
+ * seconds ("0.15s").
+ */
+function getTransitionDurationMs(el) {
+    const raw = getComputedStyle(el).transitionDuration;
+    const v = parseFloat(raw);
+    if (!Number.isFinite(v) || v < 0)
+        return 150;
+    return raw.trim().endsWith("ms") ? v : v * 1000;
 }
 function getElementZIndex() {
     return (getComputedStyle(document.documentElement)
         .getPropertyValue("--stuic-dim-behind-element-z-index")
         .trim() || "41");
 }
-function showBackdrop(classBackdrop) {
-    activeCount++;
-    if (activeCount === 1) {
-        backdropEl = document.createElement("div");
-        backdropEl.classList.add("stuic-dim-behind-backdrop");
+function showBackdrop(container, classBackdrop) {
+    let entry = backdrops.get(container);
+    if (!entry) {
+        const el = document.createElement("div");
+        el.classList.add("stuic-dim-behind-backdrop");
         if (classBackdrop) {
-            backdropEl.classList.add(...classBackdrop.split(/\s+/).filter(Boolean));
+            el.classList.add(...classBackdrop.split(/\s+/).filter(Boolean));
         }
-        document.body.appendChild(backdropEl);
+        container.appendChild(el);
         // Force reflow for transition
-        void backdropEl.offsetHeight;
-        backdropEl.classList.add("dim-visible");
+        void el.offsetHeight;
+        el.classList.add("dim-visible");
+        entry = { el, count: 0 };
+        backdrops.set(container, entry);
     }
+    entry.count++;
+    return entry.el;
 }
-function hideBackdrop() {
-    activeCount = Math.max(0, activeCount - 1);
-    if (activeCount === 0 && backdropEl) {
-        const el = backdropEl;
+function hideBackdrop(container) {
+    const entry = backdrops.get(container);
+    if (!entry)
+        return;
+    entry.count = Math.max(0, entry.count - 1);
+    if (entry.count === 0) {
+        // Drop the registry entry immediately so a show() during the fade-out
+        // creates a fresh backdrop instead of resurrecting the dying one.
+        backdrops.delete(container);
+        const el = entry.el;
         el.classList.remove("dim-visible");
-        const cleanup = () => {
-            el.remove();
-            if (backdropEl === el)
-                backdropEl = null;
-        };
+        const cleanup = () => el.remove();
         el.addEventListener("transitionend", cleanup, { once: true });
         // Safety fallback in case transitionend doesn't fire
-        setTimeout(cleanup, getTransitionDuration() + TRANSITION_SAFETY_MARGIN);
+        setTimeout(cleanup, getTransitionDurationMs(el) + TRANSITION_SAFETY_MARGIN);
     }
 }
 // --- Registry ---
@@ -115,6 +129,12 @@ export function dimBehind(node, fn) {
     let savedZIndex = "";
     let currentOptions = {};
     let do_debug = false;
+    // The container/backdrop/locks this instance acquired — captured at show()
+    // time so hide() releases exactly what was acquired even if options changed
+    // while visible.
+    let myContainer = null;
+    let myBackdropEl = null;
+    let myScrollLocked = false;
     const debug = (...args) => {
         if (do_debug)
             console.debug("[dimBehind]", ...args);
@@ -128,7 +148,7 @@ export function dimBehind(node, fn) {
         }
     }
     function onBackdropClick(e) {
-        if (e.target === backdropEl) {
+        if (e.target === myBackdropEl) {
             hide();
         }
     }
@@ -151,18 +171,20 @@ export function dimBehind(node, fn) {
             : getElementZIndex();
         node.style.position = "relative";
         node.style.zIndex = zIndex;
-        // Show singleton backdrop
-        showBackdrop(currentOptions.classBackdrop);
+        // Show the (per-container, ref-counted) shared backdrop
+        myContainer = resolveContainerOption(currentOptions.container) ?? document.body;
+        myBackdropEl = showBackdrop(myContainer, currentOptions.classBackdrop);
         // Optional scroll lock
         if (currentOptions.scrollLock) {
             BodyScroll.lock();
+            myScrollLocked = true;
         }
         // Event listeners
         if (currentOptions.closeOnEscape !== false) {
             document.addEventListener("keydown", onEscape);
         }
-        if (currentOptions.closeOnBackdropClick !== false && backdropEl) {
-            backdropEl.addEventListener("click", onBackdropClick);
+        if (currentOptions.closeOnBackdropClick !== false) {
+            myBackdropEl.addEventListener("click", onBackdropClick);
         }
         currentOptions.onShow?.();
     }
@@ -179,15 +201,18 @@ export function dimBehind(node, fn) {
         node.style.zIndex = savedZIndex;
         // Remove event listeners
         document.removeEventListener("keydown", onEscape);
-        if (backdropEl) {
-            backdropEl.removeEventListener("click", onBackdropClick);
-        }
-        // Optional scroll unlock
-        if (currentOptions.scrollLock) {
+        myBackdropEl?.removeEventListener("click", onBackdropClick);
+        // Release the scroll lock iff THIS instance acquired one (the option may
+        // have changed while visible)
+        if (myScrollLocked) {
             BodyScroll.unlock();
+            myScrollLocked = false;
         }
-        // Hide singleton backdrop
-        hideBackdrop();
+        // Release the shared backdrop
+        if (myContainer)
+            hideBackdrop(myContainer);
+        myContainer = null;
+        myBackdropEl = null;
         currentOptions.onHide?.();
     }
     // Reactive params effect
@@ -205,6 +230,7 @@ export function dimBehind(node, fn) {
             onShow: opts.onShow,
             onHide: opts.onHide,
             debug: opts.debug,
+            container: opts.container,
         };
         do_debug = !!opts.debug;
         // Register in global registry if id provided
@@ -229,10 +255,15 @@ export function dimBehind(node, fn) {
             if (isVisible) {
                 node.style.position = savedPosition;
                 node.style.zIndex = savedZIndex;
-                if (currentOptions.scrollLock) {
+                if (myScrollLocked) {
                     BodyScroll.unlock();
+                    myScrollLocked = false;
                 }
-                hideBackdrop();
+                myBackdropEl?.removeEventListener("click", onBackdropClick);
+                if (myContainer)
+                    hideBackdrop(myContainer);
+                myContainer = null;
+                myBackdropEl = null;
                 document.removeEventListener("keydown", onEscape);
             }
             // Unregister from registry

package/dist/actions/popover/README.md

@@ -4,23 +4,24 @@ A Svelte action that displays an anchored popover using CSS Anchor Positioning,
 
 ## Options
 
-| Option                | Type                 | Default     | Description                                           |
-| --------------------- | -------------------- | ----------- | ----------------------------------------------------- |
-| `enabled`             | `boolean`            | `true`      | Enable/disable popover                                |
-| `content`             | `THC \| null`        | -           | Popover content (string, HTML, component, or snippet) |
-| `position`            | `PopoverPosition`    | `"bottom"`  | Placement relative to anchor                          |
-| `trigger`             | `"click" \| "hover"` | `"click"`   | Trigger mode                                          |
-| `showDelay`           | `number`             | `100`       | Delay before showing (ms)                             |
-| `hideDelay`           | `number`             | `200`       | Delay before hiding (ms)                              |
-| `class`               | `string`             | -           | Custom CSS for popover container                      |
-| `offset`              | `string`             | `"0.25rem"` | Margin from anchor (CSS value)                        |
-| `closeOthers`         | `boolean`            | `false`     | Close other open popovers                             |
-| `closeOnClickOutside` | `boolean`            | `true`      | Close on outside click (click trigger)                |
-| `closeOnEscape`       | `boolean`            | `true`      | Close on Escape key                                   |
-| `showBackdrop`        | `boolean`            | `true`      | Show backdrop in fallback mode                        |
-| `forceFallback`       | `boolean`            | `false`     | Force centered modal mode                             |
-| `onShow`              | `() => void`         | -           | Callback when popover opens                           |
-| `onHide`              | `() => void`         | -           | Callback when popover closes                          |
+| Option                | Type                                         | Default                                       | Description                                                                                        |
+| --------------------- | -------------------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `enabled`             | `boolean`                                    | `true`                                        | Enable/disable popover                                                                             |
+| `content`             | `THC \| null`                                | -                                             | Popover content (string, HTML, component, or snippet)                                              |
+| `position`            | `PopoverPosition`                            | `"bottom"`                                    | Placement relative to anchor                                                                       |
+| `trigger`             | `"click" \| "hover"`                         | `"click"`                                     | Trigger mode                                                                                       |
+| `showDelay`           | `number`                                     | `100`                                         | Delay before showing (ms)                                                                          |
+| `hideDelay`           | `number`                                     | `200`                                         | Delay before hiding (ms)                                                                           |
+| `class`               | `string`                                     | -                                             | Custom CSS for popover container                                                                   |
+| `offset`              | `string`                                     | `"0.25rem"`                                   | Margin from anchor (CSS value)                                                                     |
+| `closeOthers`         | `boolean`                                    | `false`                                       | Close other open popovers                                                                          |
+| `closeOnClickOutside` | `boolean`                                    | `true`                                        | Close on outside click (click trigger)                                                             |
+| `closeOnEscape`       | `boolean`                                    | `true`                                        | Close on Escape key                                                                                |
+| `showBackdrop`        | `boolean`                                    | `true`                                        | Show backdrop in fallback mode                                                                     |
+| `forceFallback`       | `boolean`                                    | `false`                                       | Force centered modal mode                                                                          |
+| `onShow`              | `() => void`                                 | -                                             | Callback when popover opens                                                                        |
+| `onHide`              | `() => void`                                 | -                                             | Callback when popover closes                                                                       |
+| `container`           | `HTMLElement \| (() => HTMLElement \| null)` | closest open `<dialog>`, else `document.body` | Where to append the popover — pass a bounded shell to keep the overlay inside its stacking context |
 
 ## Positions
 
@@ -139,6 +140,25 @@ bottom-left   bottom    bottom-right
 </button>
 ```
 
+### Custom Container (Bounded Shells)
+
+When the app renders inside a bounded shell that is a stacking context and/or a
+fixed containing block (e.g. a centered frame with `contain: layout paint`, an
+embedded widget, a transformed wrapper), a body-level popover can only paint
+entirely above or below that shell. Pass `container` to keep the overlay inside
+it:
+
+```svelte
+<button
+	use:popover={() => ({
+		content: "Stays inside the frame",
+		container: () => document.querySelector(".app-frame"),
+	})}
+>
+	Framed
+</button>
+```
+
 ## Helper Function
 
 ```ts

package/dist/actions/popover/popover.container.fixture.svelte

@@ -0,0 +1,26 @@
+<script lang="ts">
+	import { popover } from "./popover.svelte.js";
+
+	let { open = false, useContainer = false }: { open?: boolean; useContainer?: boolean } =
+		$props();
+
+	let shell = $state<HTMLDivElement>();
+</script>
+
+<!-- A bounded shell that is a fixed containing block + stacking context. -->
+<div
+	bind:this={shell}
+	data-testid="shell"
+	style="contain: layout paint; width: 300px; height: 200px;"
+></div>
+
+<button
+	data-testid="trigger"
+	use:popover={() => ({
+		content: "Hello",
+		open,
+		container: useContainer ? () => shell ?? null : undefined,
+	})}
+>
+	trigger
+</button>

package/dist/actions/popover/popover.container.fixture.svelte.d.ts

@@ -0,0 +1,7 @@
+type $$ComponentProps = {
+    open?: boolean;
+    useContainer?: boolean;
+};
+declare const Popover: import("svelte").Component<$$ComponentProps, {}, "">;
+type Popover = ReturnType<typeof Popover>;
+export default Popover;

package/dist/actions/popover/popover.svelte.d.ts

@@ -101,6 +101,16 @@ export interface PopoverOptions {
     open?: boolean;
     /** Unique ID for registry-based programmatic control (use with openPopover/closePopover/togglePopover) */
     id?: string;
+    /**
+     * Where to append the popover (and its fallback backdrop/wrapper). Defaults
+     * to the current behavior: the closest open `<dialog>` ancestor, else
+     * `document.body`. Pass a bounded shell (framed app, embedded widget,
+     * dashboard pane) to keep the overlay inside it — required when that shell
+     * is a stacking context, since a body-level overlay can then only paint
+     * entirely above or entirely below it. A function returning `null` falls
+     * back to the default.
+     */
+    container?: HTMLElement | (() => HTMLElement | null);
 }
 /**
  * A Svelte action that displays a popover anchored to an element using CSS Anchor Positioning.

package/dist/actions/popover/popover.svelte.js

@@ -2,6 +2,8 @@ import { mount, unmount } from "svelte";
 import { twMerge } from "../../utils/tw-merge.js";
 import { addAnchorName, removeAnchorName } from "../../utils/anchor-name.js";
 import { clampIntoViewport } from "../../utils/anchor-position.js";
+import { fixedContainingBlockRect } from "../../utils/containing-block.js";
+import { resolveContainerOption } from "../../utils/overlay-container.js";
 import { iconX } from "../../icons/index.js";
 import { BodyScroll } from "../../utils/body-scroll-locker.js";
 import PopoverContent from "./PopoverContent.svelte";
@@ -342,14 +344,19 @@ export function popover(anchorEl, fn) {
         anchorEl.setAttribute("aria-expanded", "true");
         const offsetValue = currentOptions.offset || "0.25rem";
         const useAnchorPositioning = isSupported && !currentOptions.forceFallback;
-        // Get appropriate container (dialog if inside one, otherwise body)
-        // This ensures popover renders in same stacking context as modal dialogs
-        const container = getPopoverContainer(anchorEl);
+        // Get appropriate container (explicit option, else dialog if inside one,
+        // otherwise body). This ensures popover renders in the same stacking
+        // context as modal dialogs / the consumer's bounded shell.
+        const container = resolveContainerOption(currentOptions.container) ?? getPopoverContainer(anchorEl);
         if (useAnchorPositioning) {
             // CSS Anchor Positioning mode
             popoverEl = document.createElement("div");
             popoverEl.setAttribute("id", id);
             popoverEl.setAttribute("role", "dialog");
+            // NOTE: keep `vw`/`vh` here — this is the ANCHORED branch, where the
+            // element's containing block is the `position-area` region (a slice of
+            // the CB, often much smaller than it), so `%` would shrink the popover.
+            // Overflow is handled by @position-try + the CB-aware runtime check.
             popoverEl.style.cssText = `
 				position: fixed;
 				position-anchor: ${anchorName};
@@ -390,10 +397,13 @@ export function popover(anchorEl, fn) {
             popoverEl = document.createElement("div");
             popoverEl.setAttribute("id", id);
             popoverEl.setAttribute("role", "dialog");
+            // `90%` (not `90vw/90vh`): resolves against the inset-0 wrapper, which
+            // spans the containing block — identical to viewport units when the CB
+            // is the viewport, correct inside a contained/transformed shell.
             popoverEl.style.cssText = `
 				position: relative;
-				max-width: 90vw;
-				max-height: 90vh;
+				max-width: 90%;
+				max-height: 90%;
 				overflow: auto;
 				transition-duration: ${TRANSITION}ms;
 				pointer-events: auto;
@@ -440,11 +450,13 @@ export function popover(anchorEl, fn) {
                     // sub-pixel/vertical cases); clamping keeps small edge-anchored
                     // popovers anchored instead of switching them to a modal.
                     clampIntoViewport(popoverEl);
+                    // Compare against the containing block (the viewport, unless an
+                    // ancestor with `transform`/`contain` establishes one).
                     const rect = popoverEl.getBoundingClientRect();
-                    const viewportWidth = window.innerWidth;
+                    const cb = fixedContainingBlockRect(popoverEl);
                     // If it STILL overflows horizontally after clamping, the content
                     // is too wide to fit anchored — fall back to the centered modal.
-                    if (rect.left < 0 || rect.right > viewportWidth) {
+                    if (rect.left < cb.left || rect.right > cb.right) {
                         debug("overflow detected, switching to fallback mode");
                         switchingToFallback = true;
                         // Quick cleanup (skip transition)
@@ -556,6 +568,7 @@ export function popover(anchorEl, fn) {
             onHide: opts.onHide,
             debug: opts.debug,
             id: opts.id,
+            container: opts.container,
         };
         do_debug = !!opts.debug;
         // Register in global registry if id provided

package/dist/actions/spotlight/spotlight.container.fixture.svelte

@@ -0,0 +1,33 @@
+<script lang="ts">
+	import { spotlight } from "./spotlight.svelte.js";
+
+	let { open = false, useContainer = false }: { open?: boolean; useContainer?: boolean } =
+		$props();
+
+	let shell = $state<HTMLDivElement>();
+</script>
+
+<!-- A bounded shell that is a fixed containing block + stacking context. The
+target sits at a known offset inside it so the clip-path hole coordinates can
+be asserted container-locally. -->
+<div
+	bind:this={shell}
+	data-testid="shell"
+	style="contain: layout paint; width: 240px; height: 180px; position: relative;"
+>
+	<button
+		data-testid="target"
+		style="position: absolute; left: 40px; top: 30px; width: 60px; height: 20px;"
+		use:spotlight={() => ({
+			content: "hi",
+			open,
+			padding: 4,
+			borderRadius: 0,
+			scrollIntoView: false,
+			autoTrack: false,
+			container: useContainer ? () => shell ?? null : undefined,
+		})}
+	>
+		x
+	</button>
+</div>

package/dist/actions/spotlight/spotlight.container.fixture.svelte.d.ts

@@ -0,0 +1,7 @@
+type $$ComponentProps = {
+    open?: boolean;
+    useContainer?: boolean;
+};
+declare const Spotlight: import("svelte").Component<$$ComponentProps, {}, "">;
+type Spotlight = ReturnType<typeof Spotlight>;
+export default Spotlight;

package/dist/actions/spotlight/spotlight.svelte.d.ts

@@ -98,6 +98,15 @@ export interface SpotlightOptions {
     autoTrack?: boolean;
     /** Debug mode */
     debug?: boolean;
+    /**
+     * Where to append the overlay elements (backdrop, anchor, annotation).
+     * Defaults to the current behavior: `document.body`. Pass a bounded shell
+     * (framed app, embedded widget, dashboard pane) to keep the overlay inside
+     * it — required when that shell is a stacking context, since a body-level
+     * overlay can then only paint entirely above or entirely below it. A
+     * function returning `null` falls back to the default.
+     */
+    container?: HTMLElement | (() => HTMLElement | null);
 }
 /**
  * A Svelte action that highlights a target element with a spotlight effect.