@marianmeres/stuic 3.151.0 → 3.153.0

package/dist/actions/spotlight/spotlight.svelte.js

@@ -3,6 +3,7 @@ import { twMerge } from "../../utils/tw-merge.js";
 import { addAnchorName, removeAnchorName } from "../../utils/anchor-name.js";
 import { buildPositionTryFallbacks, clampIntoViewport, } from "../../utils/anchor-position.js";
 import { BodyScroll } from "../../utils/body-scroll-locker.js";
+import { resolveContainerOption } from "../../utils/overlay-container.js";
 import SpotlightContent from "./SpotlightContent.svelte";
 //
 const TRANSITION = 200;
@@ -85,23 +86,35 @@ const _classAnnotation = `
 	border border-(--stuic-spotlight-annotation-border)
 	z-50
 `;
+const VIEWPORT_ORIGIN = () => ({
+    left: 0,
+    top: 0,
+    width: window.innerWidth,
+    height: window.innerHeight,
+    scaleX: 1,
+    scaleY: 1,
+});
 /**
- * Builds the clip-path value for the backdrop overlay with a rounded-rectangle hole.
+ * Builds the clip-path value for the backdrop overlay with a rounded-rectangle
+ * hole. `rect` is the target's viewport rect; `o` is the backdrop's own
+ * coordinate space (see {@link OverlayOrigin}) — clip-path coordinates are
+ * local to the backdrop element, so the hole is translated by the origin and
+ * the outer box is the backdrop's layout size.
  */
-function buildClipPath(rect, padding, borderRadius) {
-    const vw = window.innerWidth;
-    const vh = window.innerHeight;
-    const x = rect.left - padding;
-    const y = rect.top - padding;
-    const w = rect.width + padding * 2;
-    const h = rect.height + padding * 2;
+function buildClipPath(rect, padding, borderRadius, o) {
+    const ow = o.width;
+    const oh = o.height;
+    const x = (rect.left - o.left) / o.scaleX - padding;
+    const y = (rect.top - o.top) / o.scaleY - padding;
+    const w = rect.width / o.scaleX + padding * 2;
+    const h = rect.height / o.scaleY + padding * 2;
     const r = Math.min(borderRadius, w / 2, h / 2);
     if (r <= 0) {
         // Simple rectangular hole (no rounding)
-        return `polygon(evenodd, 0 0, ${vw}px 0, ${vw}px ${vh}px, 0 ${vh}px, 0 0, ${x}px ${y}px, ${x}px ${y + h}px, ${x + w}px ${y + h}px, ${x + w}px ${y}px, ${x}px ${y}px)`;
+        return `polygon(evenodd, 0 0, ${ow}px 0, ${ow}px ${oh}px, 0 ${oh}px, 0 0, ${x}px ${y}px, ${x}px ${y + h}px, ${x + w}px ${y + h}px, ${x + w}px ${y}px, ${x}px ${y}px)`;
     }
     // Rounded rectangular hole using SVG path syntax
-    return `path(evenodd, "M 0 0 L ${vw} 0 L ${vw} ${vh} L 0 ${vh} Z M ${x + r} ${y} L ${x + w - r} ${y} A ${r} ${r} 0 0 1 ${x + w} ${y + r} L ${x + w} ${y + h - r} A ${r} ${r} 0 0 1 ${x + w - r} ${y + h} L ${x + r} ${y + h} A ${r} ${r} 0 0 1 ${x} ${y + h - r} L ${x} ${y + r} A ${r} ${r} 0 0 1 ${x + r} ${y} Z")`;
+    return `path(evenodd, "M 0 0 L ${ow} 0 L ${ow} ${oh} L 0 ${oh} Z M ${x + r} ${y} L ${x + w - r} ${y} A ${r} ${r} 0 0 1 ${x + w} ${y + r} L ${x + w} ${y + h - r} A ${r} ${r} 0 0 1 ${x + w - r} ${y + h} L ${x + r} ${y + h} A ${r} ${r} 0 0 1 ${x} ${y + h - r} L ${x} ${y + r} A ${r} ${r} 0 0 1 ${x + r} ${y} Z")`;
 }
 /**
  * Checks if content is simple (string/html) vs complex (component/snippet).
@@ -216,6 +229,35 @@ export function spotlight(targetEl, fn) {
             hide();
         }
     }
+    /**
+     * The coordinate space the overlay's fixed elements resolve against. The
+     * backdrop is `position: fixed; inset: 0`, so its own box IS that space —
+     * the containing block's padding box when a CB-forming ancestor exists
+     * (overlay portalled into a contained/transformed shell via `container`),
+     * the viewport otherwise. Measuring it handles both with no special-casing.
+     */
+    function overlayOrigin() {
+        if (!backdropEl)
+            return VIEWPORT_ORIGIN();
+        const r = backdropEl.getBoundingClientRect();
+        // offsetWidth/Height are layout-space; the rect is visual — the ratio is
+        // the accumulated ancestor scale. offset* are integer-rounded, so treat
+        // sub-pixel differences as "unscaled" to avoid noise on the default path.
+        const w = backdropEl.offsetWidth || r.width;
+        const h = backdropEl.offsetHeight || r.height;
+        const sx = w && Math.abs(r.width - w) > 1 ? r.width / w : 1;
+        const sy = h && Math.abs(r.height - h) > 1 ? r.height / h : 1;
+        return { left: r.left, top: r.top, width: w, height: h, scaleX: sx, scaleY: sy };
+    }
+    /** Place the invisible anchor element over the (padded) hole. */
+    function positionAnchor(rect, padding, o) {
+        if (!anchorEl)
+            return;
+        anchorEl.style.left = `${(rect.left - o.left) / o.scaleX - padding}px`;
+        anchorEl.style.top = `${(rect.top - o.top) / o.scaleY - padding}px`;
+        anchorEl.style.width = `${rect.width / o.scaleX + padding * 2}px`;
+        anchorEl.style.height = `${rect.height / o.scaleY + padding * 2}px`;
+    }
     /**
      * Update the clip-path hole position to match the current target rect.
      */
@@ -225,15 +267,11 @@ export function spotlight(targetEl, fn) {
         const rect = targetEl.getBoundingClientRect();
         const padding = currentOptions.padding ?? 8;
         const borderRadius = currentOptions.borderRadius ?? 8;
+        const o = overlayOrigin();
         debug("updateHolePosition()", rect);
-        backdropEl.style.clipPath = buildClipPath(rect, padding, borderRadius);
+        backdropEl.style.clipPath = buildClipPath(rect, padding, borderRadius, o);
         // Update the invisible anchor element position
-        if (anchorEl) {
-            anchorEl.style.left = `${rect.left - padding}px`;
-            anchorEl.style.top = `${rect.top - padding}px`;
-            anchorEl.style.width = `${rect.width + padding * 2}px`;
-            anchorEl.style.height = `${rect.height + padding * 2}px`;
-        }
+        positionAnchor(rect, padding, o);
         // Reposition / re-clamp the annotation. The fallback path recomputes its
         // base left/top here; the anchor path is re-placed by the browser. Either
         // way we re-clamp so an edge-anchored annotation stays on-screen as the
@@ -281,17 +319,21 @@ export function spotlight(targetEl, fn) {
         lastRect = null;
     }
     /**
-     * Position annotation without CSS Anchor Positioning (fallback).
+     * Position annotation without CSS Anchor Positioning (fallback). All values
+     * are expressed in the overlay's coordinate space (see {@link overlayOrigin})
+     * — for a fixed element, `left/top/right/bottom` resolve against the
+     * containing block, which is the viewport only in the un-portalled default.
      */
     function positionAnnotationFallback(rect, padding) {
         if (!annotationEl)
             return;
         const pos = currentOptions.position || "bottom";
         const offset = 8; // px fallback offset
-        const x = rect.left - padding;
-        const y = rect.top - padding;
-        const w = rect.width + padding * 2;
-        const h = rect.height + padding * 2;
+        const o = overlayOrigin();
+        const x = (rect.left - o.left) / o.scaleX - padding;
+        const y = (rect.top - o.top) / o.scaleY - padding;
+        const w = rect.width / o.scaleX + padding * 2;
+        const h = rect.height / o.scaleY + padding * 2;
         // Reset position
         annotationEl.style.left = "";
         annotationEl.style.top = "";
@@ -300,14 +342,14 @@ export function spotlight(targetEl, fn) {
         annotationEl.style.transform = "";
         if (pos.startsWith("top")) {
             annotationEl.style.left = `${x}px`;
-            annotationEl.style.bottom = `${window.innerHeight - y + offset}px`;
+            annotationEl.style.bottom = `${o.height - y + offset}px`;
         }
         else if (pos.startsWith("bottom")) {
             annotationEl.style.left = `${x}px`;
             annotationEl.style.top = `${y + h + offset}px`;
         }
         else if (pos === "left") {
-            annotationEl.style.right = `${window.innerWidth - x + offset}px`;
+            annotationEl.style.right = `${o.width - x + offset}px`;
             annotationEl.style.top = `${y}px`;
         }
         else if (pos === "right") {
@@ -328,7 +370,11 @@ export function spotlight(targetEl, fn) {
     function clampAnnotationIntoViewport() {
         if (!annotationEl || !annotationShown)
             return;
-        clampIntoViewport(annotationEl);
+        // Pass the empirically measured CB rect (the inset-0 backdrop's box) so
+        // the clamp uses the SAME coordinate space as the hole/anchor math even
+        // where the heuristic ancestor walk and the engine disagree (WebKit
+        // filter shells).
+        clampIntoViewport(annotationEl, undefined, backdropEl ? backdropEl.getBoundingClientRect() : undefined);
     }
     function renderContent() {
         if (!annotationEl || !currentOptions.content)
@@ -374,8 +420,12 @@ export function spotlight(targetEl, fn) {
         requestAnimationFrame(() => {
             if (!isVisible)
                 return; // may have been hidden in the meantime
+            const container = resolveContainerOption(currentOptions.container) ?? document.body;
             const rect = targetEl.getBoundingClientRect();
-            // 1. Create backdrop overlay
+            // 1. Create backdrop overlay. Append BEFORE building the clip-path:
+            // the hole coordinates are relative to the backdrop's own box, which
+            // is only measurable once it is in the DOM (same JS turn — nothing
+            // paints unclipped).
             backdropEl = document.createElement("div");
             backdropEl.style.cssText = `
 				position: fixed;
@@ -385,26 +435,29 @@ export function spotlight(targetEl, fn) {
 				transition-duration: ${TRANSITION}ms;
 			`;
             backdropEl.classList.add(...twMerge("stuic-spotlight-backdrop", currentOptions.classBackdrop).split(/\s/));
-            backdropEl.style.clipPath = buildClipPath(rect, padding, borderRadius);
-            document.body.appendChild(backdropEl);
+            container.appendChild(backdropEl);
+            const o = overlayOrigin();
+            backdropEl.style.clipPath = buildClipPath(rect, padding, borderRadius, o);
             // 2. Create invisible anchor element for CSS Anchor Positioning
             anchorEl = document.createElement("div");
             anchorEl.style.cssText = `
 				position: fixed;
-				left: ${rect.left - padding}px;
-				top: ${rect.top - padding}px;
-				width: ${rect.width + padding * 2}px;
-				height: ${rect.height + padding * 2}px;
 				pointer-events: none;
 				z-index: -1;
 			`;
+            positionAnchor(rect, padding, o);
             addAnchorName(anchorEl, anchorName);
-            document.body.appendChild(anchorEl);
+            container.appendChild(anchorEl);
             // 3. Create annotation element (if content provided)
             if (currentOptions.content) {
                 annotationEl = document.createElement("div");
                 annotationEl.setAttribute("role", "dialog");
                 if (isSupported) {
+                    // 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), so `%` would shrink the
+                    // annotation. Overflow is handled by position-try + the CB-aware
+                    // clamp.
                     annotationEl.style.cssText = `
 						position: fixed;
 						position-anchor: ${anchorName};
@@ -420,17 +473,18 @@ export function spotlight(targetEl, fn) {
                     annotationEl.classList.add(...twMerge("stuic-spotlight-annotation", _classAnnotation, currentOptions.class).split(/\s/));
                 }
                 else {
-                    // Fallback positioning
+                    // Fallback positioning. `90%` (not `90vw`): the left/top values
+                    // are containing-block-relative, so the size must be too.
                     annotationEl.style.cssText = `
 						position: fixed;
 						transition-duration: ${TRANSITION}ms;
 						z-index: 50;
-						max-width: 90vw;
+						max-width: 90%;
 					`;
                     annotationEl.classList.add(...twMerge("stuic-spotlight-annotation-fallback", _classAnnotation, currentOptions.class).split(/\s/));
                     positionAnnotationFallback(rect, padding);
                 }
-                document.body.appendChild(annotationEl);
+                container.appendChild(annotationEl);
                 renderContent();
             }
             // 4. Lock body scroll
@@ -457,9 +511,12 @@ export function spotlight(targetEl, fn) {
             if (currentOptions.closeOnBackdropClick !== false) {
                 backdropEl.addEventListener("click", onBackdropClick);
             }
-            // 7. Watch for target position changes
+            // 7. Watch for target position changes — and for the overlay's own
+            // coordinate space changing size (the backdrop tracks its container,
+            // which resize/scroll listeners and target-rect comparison won't see)
             resizeObserver = new ResizeObserver(updateHolePosition);
             resizeObserver.observe(targetEl);
+            resizeObserver.observe(backdropEl);
             window.addEventListener("resize", updateHolePosition);
             window.addEventListener("scroll", updateHolePosition, true);
             // 8. Per-frame compare-loop to catch layout shifts (sibling collapses,
@@ -527,6 +584,7 @@ export function spotlight(targetEl, 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/components/DropdownMenu/DropdownMenu.svelte

@@ -266,6 +266,7 @@
 	import Thc from "../Thc/Thc.svelte";
 	import ListItemButton from "../ListItemButton/ListItemButton.svelte";
 	import { BodyScroll } from "../../utils/body-scroll-locker.js";
+	import { fixedContainingBlockRect } from "../../utils/containing-block.js";
 	import { waitForTwoRepaints } from "../../utils/paint.js";
 	import {
 		extractSearchableItems,
@@ -542,15 +543,17 @@
 			await waitForTwoRepaints();
 			if (!dropdownEl || !isOpen) return;
 
+			// Measure against the dropdown's containing block, not the viewport —
+			// an ancestor with e.g. `transform` or `contain: layout|paint` is what
+			// the fixed dropdown actually resolves (and gets clipped) against.
 			const rect = dropdownEl.getBoundingClientRect();
-			const viewportWidth = window.innerWidth;
-			const viewportHeight = window.innerHeight;
+			const cb = fixedContainingBlockRect(dropdownEl);
 
 			if (
-				rect.left < 0 ||
-				rect.right > viewportWidth ||
-				rect.top < 0 ||
-				rect.bottom > viewportHeight
+				rect.left < cb.left ||
+				rect.right > cb.right ||
+				rect.top < cb.top ||
+				rect.bottom > cb.bottom
 			) {
 				switchingToFallback = true;
 				runtimeFallback = true;
@@ -707,12 +710,16 @@
 			const heightStyle = searchConfig
 				? `height: ${maxHeight};`
 				: `max-height: ${maxHeight};`;
+			// `90%` (not `90vw`): the top/left/transform centering is relative to
+			// the containing block, so the size must be too — `%` resolves against
+			// the CB (identical to `vw` when the CB is the viewport, correct when
+			// an ancestor with `transform`/`contain` establishes one).
 			return `
 				position: fixed;
 				top: 50%;
 				left: 50%;
 				transform: translate(-50%, -50%);
-				max-width: 90vw;
+				max-width: 90%;
 				${heightStyle}
 				${gutterStyle}
 				z-index: 50;

package/dist/components/DropdownMenu/README.md

@@ -361,6 +361,7 @@ Use `contentBefore` for leading content (icons) and `contentAfter` for trailing
 ## Features
 
 - **CSS Anchor Positioning**: Uses modern CSS anchor positioning with automatic fallback for unsupported browsers
+- **Containing-block aware**: Overflow detection and the fallback modal measure against the dropdown's actual containing block — inside a `transform`ed or `contain: layout|paint` shell they use the shell's box, not the viewport
 - **Full Keyboard Navigation**: Complete arrow key navigation with Home/End support
 - **Expandable Sections**: Collapsible groups with independent toggle state
 - **ARIA Compliant**: Proper menu roles and keyboard interaction

package/dist/components/Float/Float.svelte

@@ -67,6 +67,7 @@
 <script lang="ts">
 	import { untrack } from "svelte";
 	import { twMerge } from "../../utils/tw-merge.js";
+	import { fixedContainingBlockRect } from "../../utils/containing-block.js";
 	import { localStorageState } from "../../utils/persistent-state.svelte.js";
 	import { draggable as draggableAction } from "../../actions/draggable.svelte.js";
 	import { iconChevronDown, iconX } from "../../icons/index.js";
@@ -130,6 +131,26 @@
 
 	function viewport(): FloatSize {
 		if (typeof window === "undefined") return { width: 0, height: 0 };
+		// The panel is `position: fixed`, so its `left`/`top` (and therefore all
+		// placement/clamping math) resolve against its containing block — the
+		// viewport, unless an ancestor (`transform`, `contain: layout|paint`, …)
+		// establishes one. `x`/`y` are written as `left`/`top`, i.e. LAYOUT px,
+		// while the CB rect is visual — divide out the accumulated ancestor
+		// scale (measured on the panel itself; sub-pixel offset* rounding is
+		// treated as unscaled).
+		if (el) {
+			const cb = fixedContainingBlockRect(el);
+			const r = el.getBoundingClientRect();
+			const sx =
+				el.offsetWidth && Math.abs(r.width - el.offsetWidth) > 1
+					? r.width / el.offsetWidth
+					: 1;
+			const sy =
+				el.offsetHeight && Math.abs(r.height - el.offsetHeight) > 1
+					? r.height / el.offsetHeight
+					: 1;
+			return { width: cb.width / sx, height: cb.height / sy };
+		}
 		return { width: window.innerWidth, height: window.innerHeight };
 	}
 

package/dist/components/Float/README.md

@@ -5,7 +5,7 @@ dev/inspector tweak panel (dat.GUI / Tweakpane style). It has a header (optional
 icon, a `THC` title, an actions slot, and minimize/close buttons) and an arbitrary body.
 
 - **Positioned by params**: numeric `x`/`y` **or** a named `placement` preset (corners / edges / center).
-- **`position: fixed`** relative to the viewport, with drag **clamped** so it never leaves the screen.
+- **`position: fixed`** relative to the viewport — or to the nearest containing-block ancestor (`transform`, `contain: layout|paint`, …) when one exists — with drag **clamped** so it never leaves that box.
 - **Draggable** by the whole header (buttons excepted).
 - **Minimizable** to just the title bar (header button, double-click header, or methods).
 - **Imperative control** via a `bind:this` ref (mirrors `Modal`/`ModalDialog`).

package/dist/components/HoverExpandableWidth/HoverExpandableWidth.svelte

@@ -24,7 +24,10 @@
 </script>
 
 <script lang="ts">
-	import { innerHeight, innerWidth } from "svelte/reactivity/window";
+	import {
+		fixedContainingBlockAncestor,
+		fixedContainingBlockRect,
+	} from "../../utils/containing-block.js";
 	import { DevicePointer } from "../../utils/device-pointer.svelte.js";
 	import { waitForNextRepaint, waitForTransitionEnd } from "../../utils/paint.js";
 	import { prefersReducedMotion } from "../../utils/prefers-reduced-motion.svelte.js";
@@ -82,12 +85,34 @@
 		isExpanded = true;
 		isExpanding = true;
 
+		// Pin the element in place: the inset values below resolve against the
+		// containing block once `position: fixed` is applied — the viewport,
+		// unless an ancestor (`transform`, `contain: layout|paint`, …)
+		// establishes one. Insets are LAYOUT px in the CB's content space, while
+		// rects are visual: divide out the accumulated ancestor scale, add the
+		// CB's scroll offsets (a fixed element whose CB is a scroll container
+		// behaves like an absolute one — it scrolls with the content), and
+		// derive bottom/right from the CB size so the top+height+bottom
+		// constraint stays exact. With no CB ancestor this reduces to the plain
+		// viewport-edge distances.
 		box = el.getBoundingClientRect();
+		const cbEl = fixedContainingBlockAncestor(el);
+		const cb = fixedContainingBlockRect(el);
+		const sx =
+			el.offsetWidth && Math.abs(box.width - el.offsetWidth) > 1
+				? box.width / el.offsetWidth
+				: 1;
+		const sy =
+			el.offsetHeight && Math.abs(box.height - el.offsetHeight) > 1
+				? box.height / el.offsetHeight
+				: 1;
+		const top = (box.top - cb.top) / sy + (cbEl?.scrollTop ?? 0);
+		const left = (box.left - cb.left) / sx + (cbEl?.scrollLeft ?? 0);
 		const pos = {
-			top: box.top,
-			bottom: (innerHeight.current ?? 0) - box.bottom,
-			left: box.left,
-			right: (innerWidth.current ?? 0) - box.right,
+			top,
+			left,
+			bottom: cb.height / sy - top - box.height / sy,
+			right: cb.width / sx - left - box.width / sx,
 		};
 
 		// <offset-x>, <offset-y>, <blur-radius>, <spread-radius>

package/dist/css/frame.css

@@ -0,0 +1,109 @@
+/* ============================================================================
+   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.
+
+   See docs/domains/css-presets.md for the classes, the token contract and the
+   decision tree, and docs/RATIO_LOCKED_FRAME.md for the recipes and the measured
+   gotcha list — the CSS here is nine declarations; the knowledge is the deliverable.
+
+   LAYERED (unlike the `.scrollbar-thin` / `.stuic-safe-area-*` utilities at the
+   end of index.css) because these are opt-in layout presets a consumer puts on
+   their OWN element and WILL tweak: Tailwind emits
+   `@layer theme, base, components, utilities`, so a utility always wins —
+   `class="stuic-frame h-dvh overflow-y-auto bg-white"` overrides everything
+   below. That is the escape hatch, by design.
+
+   This preset deliberately ships NO background, NO containment, NO scroll
+   container and NO letterbox-bars class: `grid`, `overflow-hidden`,
+   `fixed inset-0`, `bg-*`, `contain-layout`, `contain-paint`, `@container-size`
+   and `overflow-y-auto` are all Tailwind v4 utilities (stuic already requires
+   Tailwind v4). Only the sizing formula is ours, because it is the only part
+   Tailwind cannot express.
+   ============================================================================ */
+
+@layer components {
+	/* The ratio-locked box. Centres itself in a block, grid or flex parent
+	   (`margin: auto` centres both axes in grid/flex; in normal flow the block-
+	   axis autos compute to 0 and it behaves as `margin-inline: auto`).
+
+	   One parent shape is NOT safe: a flex COLUMN. The ratio-derived height becomes
+	   the flex base size and `min-height: 0` below removes the floor that would stop
+	   it shrinking, so the frame silently goes off-ratio (measured 400x740, r=0.5405,
+	   where a grid parent gives 400x800, r=0.5). Add `shrink-0`. See G22.
+
+	   Why min() and not `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 0x0, and one with content
+	   shrink-wraps that content and overflows the parent. The ratio usually
+	   survives; the SIZE is what's wrong. (There is a working `max-*` variant —
+	   it needs a positioned parent — see Recipe D in the docs.)
+
+	   `aspect-ratio` supplies the height, so the frame is ratio-locked at every
+	   viewport, with bars on exactly one axis. Deriving the width from the
+	   height and then letting `aspect-ratio` derive the height back is not
+	   circular: `width` is resolved first, `aspect-ratio` only ever fills an
+	   `auto` axis.
+
+	   `min-height: 0` and `overflow: hidden` are load-bearing for the ratio, not
+	   cosmetics: a grid/flex item's automatic minimum size overrides
+	   `aspect-ratio` outright, so a tall child stretches an otherwise correct
+	   frame off-ratio. Either one alone fixes it; both are set so a consumer's
+	   `overflow-visible` stays survivable. */
+	.stuic-frame {
+		width: var(
+			--stuic-frame-width,
+			min(100vw, calc(100dvh * (var(--stuic-frame-aspect-ratio, 1))))
+		);
+
+		/* `auto` = ratio-locked (the default). Any explicit length here WINS over
+		   `aspect-ratio` unconditionally — that is the supported way to opt into
+		   "fill the height, derive the width" inside a bail-out media query, with
+		   no `!important` and no specificity game. */
+		height: var(--stuic-frame-height, auto);
+
+		aspect-ratio: var(--stuic-frame-aspect-ratio, 1);
+		min-height: 0;
+		margin: auto;
+		overflow: hidden;
+	}
+
+	/* Opt-in: size against the nearest ANCESTOR query container instead of the
+	   viewport — the nested case (a frame under a header, inside a flex column).
+	   Combine with `.stuic-frame`; this rule must stay AFTER it in source order,
+	   since both declare `width` at equal specificity.
+
+	   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 small viewport, and you get a
+	   ratio-correct but wrongly-scaled frame that overflows its parent and
+	   tracks the window as you resize. Same failure with no container ancestor
+	   at all. Size containment is safe here precisely because this frame's own
+	   height is always determined. */
+	.stuic-frame-cq {
+		width: var(
+			--stuic-frame-width,
+			min(100cqw, calc(100cqh * (var(--stuic-frame-aspect-ratio, 1))))
+		);
+	}
+
+	/* Re-align a VIEWPORT-space element onto the frame's column: a top-layer
+	   `<dialog>`, or an overlay portalled to `<body>` (stuic's popover /
+	   spotlight / dimBehind default to `document.body` — pass their `container`
+	   option instead where you can).
+
+	   The whole fallback expression is repeated on purpose. Nothing declares
+	   `--stuic-frame-width`, so a bare `var(--stuic-frame-width)` would be
+	   invalid-at-computed-value-time -> `width: auto` -> silently full-bleed. */
+	.stuic-frame-col {
+		width: min(
+			100%,
+			var(
+				--stuic-frame-width,
+				min(100vw, calc(100dvh * (var(--stuic-frame-aspect-ratio, 1))))
+			)
+		);
+		margin-inline: auto;
+	}
+}

package/dist/index.css

@@ -118,6 +118,9 @@ In practice:
 @import "./actions/spotlight/index.css";
 @import "./actions/tooltip/index.css";
 
+/* Layout preset CSS (classes only, no component) */
+@import "./css/frame.css";
+
 /* Base styles for STUIC components */
 @layer base {
 	button:not(:disabled),

package/dist/utils/anchor-position.d.ts

@@ -19,7 +19,11 @@
  */
 export declare function buildPositionTryFallbacks(position: string): string;
 /**
- * Pull an element fully into the viewport with a corrective `transform`.
+ * Pull an element fully into its containing block with a corrective
+ * `transform`. For a fixed element that is the viewport — unless an ancestor
+ * (`transform`, `contain: layout|paint`, …) establishes a containing block, in
+ * which case the element is clamped into that ancestor's box instead (see
+ * {@link fixedContainingBlockRect}).
  *
  * This is the backstop for CSS Anchor Positioning: `position-try` can only swap
  * between discrete declared positions and cannot slide a centered annotation
@@ -36,6 +40,11 @@ export declare function buildPositionTryFallbacks(position: string): string;
  * correction applies instantly. The caller owns the element's `transform`.
  *
  * @param el - The (anchored, position:fixed) element to clamp
- * @param margin - Minimum gap from each viewport edge, in px (default 8)
+ * @param margin - Minimum gap from each containing-block edge, in px (default 8)
+ * @param cb - Optional explicit containing-block rect (viewport/visual
+ *   coordinates). Callers that can measure the CB empirically (e.g. spotlight,
+ *   via its own `inset: 0` backdrop) pass it to stay self-consistent even
+ *   where the heuristic walker and the engine disagree (WebKit filter cases);
+ *   defaults to {@link fixedContainingBlockRect}.
  */
-export declare function clampIntoViewport(el: HTMLElement, margin?: number): void;
+export declare function clampIntoViewport(el: HTMLElement, margin?: number, cb?: DOMRectReadOnly): void;

package/dist/utils/anchor-position.js

@@ -2,6 +2,7 @@
  * Shared helpers for CSS Anchor Positioning based actions (spotlight, popover,
  * tooltip).
  */
+import { fixedContainingBlockRect } from "./containing-block.js";
 /**
  * Builds the `position-try-fallbacks` value for an anchored element at a given
  * position.
@@ -28,7 +29,11 @@ export function buildPositionTryFallbacks(position) {
     return flips;
 }
 /**
- * Pull an element fully into the viewport with a corrective `transform`.
+ * Pull an element fully into its containing block with a corrective
+ * `transform`. For a fixed element that is the viewport — unless an ancestor
+ * (`transform`, `contain: layout|paint`, …) establishes a containing block, in
+ * which case the element is clamped into that ancestor's box instead (see
+ * {@link fixedContainingBlockRect}).
  *
  * This is the backstop for CSS Anchor Positioning: `position-try` can only swap
  * between discrete declared positions and cannot slide a centered annotation
@@ -45,25 +50,40 @@ export function buildPositionTryFallbacks(position) {
  * correction applies instantly. The caller owns the element's `transform`.
  *
  * @param el - The (anchored, position:fixed) element to clamp
- * @param margin - Minimum gap from each viewport edge, in px (default 8)
+ * @param margin - Minimum gap from each containing-block edge, in px (default 8)
+ * @param cb - Optional explicit containing-block rect (viewport/visual
+ *   coordinates). Callers that can measure the CB empirically (e.g. spotlight,
+ *   via its own `inset: 0` backdrop) pass it to stay self-consistent even
+ *   where the heuristic walker and the engine disagree (WebKit filter cases);
+ *   defaults to {@link fixedContainingBlockRect}.
  */
-export function clampIntoViewport(el, margin = 8) {
+export function clampIntoViewport(el, margin = 8, cb = fixedContainingBlockRect(el)) {
     // Remove any prior correction so we measure the natural (anchored or
     // left/top) position, then recompute from scratch.
     el.style.transform = "";
     const a = el.getBoundingClientRect();
-    const vw = window.innerWidth;
-    const vh = window.innerHeight;
     let dx = 0;
     let dy = 0;
-    if (a.left < margin)
-        dx = margin - a.left;
-    else if (a.right > vw - margin)
-        dx = vw - margin - a.right;
-    if (a.top < margin)
-        dy = margin - a.top;
-    else if (a.bottom > vh - margin)
-        dy = vh - margin - a.bottom;
-    if (dx || dy)
-        el.style.transform = `translate(${dx}px, ${dy}px)`;
+    if (a.left < cb.left + margin)
+        dx = cb.left + margin - a.left;
+    else if (a.right > cb.right - margin)
+        dx = cb.right - margin - a.right;
+    if (a.top < cb.top + margin)
+        dy = cb.top + margin - a.top;
+    else if (a.bottom > cb.bottom - margin)
+        dy = cb.bottom - margin - a.bottom;
+    if (dx || dy) {
+        // The deltas above are visual (rect) px, but the translate applies in the
+        // element's local space — inside a scaled ancestor (`transform: scale()`
+        // zoom/preview wrapper) they differ by the accumulated scale factor.
+        // offsetWidth is integer-rounded, so treat sub-pixel differences as
+        // "unscaled" (a ratio threshold would misfire on small elements).
+        const sx = el.offsetWidth && Math.abs(a.width - el.offsetWidth) > 1
+            ? a.width / el.offsetWidth
+            : 1;
+        const sy = el.offsetHeight && Math.abs(a.height - el.offsetHeight) > 1
+            ? a.height / el.offsetHeight
+            : 1;
+        el.style.transform = `translate(${dx / sx}px, ${dy / sy}px)`;
+    }
 }