@marianmeres/stuic 3.152.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/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/docs/RATIO_LOCKED_FRAME.md

@@ -0,0 +1,466 @@
+# Ratio-Locked Frame — Reference
+
+Recipes, the measured gotcha list, and stuic overlay interop for the `.stuic-frame` CSS preset
+(`src/lib/css/frame.css`).
+
+**Start with [CSS Presets](./domains/css-presets.md)** — it has the classes, the token contract and
+the decision tree. This document is the long-form companion: it is what you read when you are about
+to write the CSS, or when something looks right and measures wrong.
+
+---
+
+## Recipes
+
+### Recipe A — viewport letterbox (bars painted by a wrapper)
+
+The full-screen shape: a fixed wrapper paints the bars, the frame sits centred in it.
+
+```svelte
+<div class="fixed inset-0 grid overflow-hidden bg-neutral-800">
+	<div
+		class="stuic-frame bg-white dark:bg-neutral-900"
+		style="--stuic-frame-aspect-ratio: 0.5"
+	>
+		<!-- app -->
+	</div>
+</div>
+```
+
+`place-items: center` is unnecessary — `.stuic-frame`'s own `margin: auto` centres it on both axes
+in a grid parent.
+
+Bail out to full bleed on a real handset (**note the second condition — G6**):
+
+```css
+@media (max-width: 40rem) and (max-aspect-ratio: 3 / 5) {
+	:root {
+		--stuic-frame-width: 100vw;
+		--stuic-frame-height: 100dvh;
+	}
+}
+```
+
+If the frame needs to scroll, add `overflow-y-auto` to it — **and then read G4b before adding
+`contain-layout contain-paint`.**
+
+### Recipe B — no wrapper, `body` is the letterbox
+
+For a phone-proportioned column app clamped on tablet-and-up: there is exactly one element. `body`'s
+background _is_ the letterbox and `.stuic-frame`'s `margin: auto` does the centring (in normal flow
+the block-axis autos compute to `0`, so it behaves as `margin-inline: auto`).
+
+```html
+<body>
+	<div class="stuic-frame bg-[var(--stuic-color-background)]">…</div>
+</body>
+```
+
+```css
+:root {
+	--stuic-frame-aspect-ratio: 0.48;
+}
+
+body {
+	background: var(--stuic-color-surface-1); /* the letterbox */
+}
+
+/* Bail out to full bleed on a real handset (note the second condition — G6) */
+@media (max-width: 40rem) and (max-aspect-ratio: 3 / 5) {
+	:root {
+		--stuic-frame-width: 100vw;
+		--stuic-frame-height: 100dvh;
+	}
+}
+```
+
+**Two things to decide consciously here.**
+
+**A token cannot clear `aspect-ratio`.** The bail-out above works because
+`--stuic-frame-height: 100dvh` beats `aspect-ratio` (**G14**). If instead you want the _content_ to
+determine the height on a phone, you need the `aspect-auto` utility in the markup — and markup
+cannot be media-queried.
+
+**So if the frame only exists above a breakpoint, take the token and keep your own class.** That
+is a legitimate, supported use of this preset — the value is the named formula, not the class:
+
+```css
+@media (min-width: 700px) and (min-height: 600px) {
+	body {
+		background: var(--stuic-color-surface-1);
+	}
+
+	.app-frame {
+		width: var(
+			--stuic-frame-width,
+			min(100vw, calc(100dvh * (var(--stuic-frame-aspect-ratio))))
+		);
+		height: 100dvh;
+		margin-inline: auto;
+		overflow-y: auto;
+	}
+}
+```
+
+Applying `.stuic-frame` _unconditionally_ in a phone-first app, together with `overflow-y-auto` on
+the frame, makes the frame the scroll container on phones too. iOS then stops collapsing the address
+bar, and pull-to-refresh semantics change — on the one path that matters most. That is usually the
+reason to keep the class conditional.
+
+### Recipe C — nested under a header, container units
+
+For a 16:9 scene inside a flex column below a header. The frame must fit whatever box it is handed,
+not the screen.
+
+```svelte
+<header class="shrink-0">…</header>
+
+<!-- the letterbox: a size container, so cqh resolves -->
+<div class="@container-size grid min-h-0 grow overflow-hidden bg-neutral-900">
+	<!-- the frame: sized in cq units; declares its own size container so
+	     descendants scale with the FRAME, not the letterbox -->
+	<div
+		class="stuic-frame stuic-frame-cq @container-size relative bg-[var(--stuic-color-surface)]"
+		style="--stuic-frame-aspect-ratio: calc(16 / 9)"
+	>
+		<div class="text-[clamp(0.75rem,1.25cqw,1.0625rem)]">…</div>
+	</div>
+</div>
+```
+
+**`@container-size` on the ancestor is mandatory, and `@container` is not enough.** With only
+`container-type: inline-size`, `cqh` falls **through** to the next container — or silently to the
+small viewport — and you get a ratio-correct, wrongly-scaled frame that overflows its parent and
+tracks the window as you resize. See **G5** for the numbers.
+
+Also note `min-h-0` on the letterbox: without it, a flex item's automatic minimum size can push the
+whole thing off (**G13**, one level up).
+
+### Recipe D — the unit-free `max-*` variant (needs a positioned parent)
+
+There **is** a working `max-width`/`max-height` formulation, contrary to widespread belief. It needs
+`position: absolute; inset: 0; margin: auto` inside a positioned parent with a definite size:
+
+```html
+<div class="relative h-dvh w-full overflow-hidden bg-neutral-800">
+	<div
+		class="absolute inset-0 m-auto max-h-full max-w-full bg-white"
+		style="aspect-ratio: 0.5"
+	>
+		…
+	</div>
+</div>
+```
+
+Measured ratio-perfect and correctly centred in 4/4 parent × ratio combinations in both engines
+(bars 287.5 / 300 / 44.4px). It is unit-free, which is genuinely attractive — no `vw`, no `dvh`, no
+`cq`, no container declaration.
+
+**Leave both axes `auto`.** The whole thing works because an absolutely-positioned box with
+`inset: 0`, no stated axis and a non-`auto` `aspect-ratio` is sized like a replaced element — fit
+inside the containing block, ratio preserved — and `margin: auto` then centres the leftover.
+Adding `width: 100%` (or `w-full`) states an axis and destroys it: that is one of the only two
+measured **engine divergences** in this whole study — Chromium 800×400 vs WebKit 200×400 for the
+same markup (**G1**).
+
+Its cost: it needs a positioned parent with a definite size, so it cannot express the one-element,
+normal-flow shape of Recipe B, and it is the _only_ parent context where the max-pair works (**G1**).
+`.stuic-frame` is not this shape because it has to work in normal flow, grid, flex, absolute and
+container-unit parents. Use Recipe D when you already have the wrapper anyway.
+
+---
+
+## Gotchas
+
+**Engine provenance, stated once.** Every number below was measured with Playwright on
+**Chromium 151.0.7922.34** and **WebKit 26.5**, plus **Firefox 153** for the containment rows.
+Results are identical across engines unless a row says otherwise. This says **nothing about old
+Safari** — see G7. Four items (G6, G7, G8, G20) are explicitly _not_ browser measurements and are
+labelled as such.
+
+> **The one that will actually bite you — frame as containing block AND scroll container — is the
+> callout at the top of [CSS Presets](./domains/css-presets.md#gotchas), referenced below as G4b.**
+
+---
+
+**G1 — `max-width: 100%; max-height: 100%; aspect-ratio: R` — the popular formulation. The usual
+explanation of why it fails is wrong.**
+The ratio is _not_ what gives. **`max-*` never grows a box**, so with `width: auto` the frame
+shrink-wraps its content instead of filling the letterbox. Measured in a
+`display: grid; place-items: center` parent: **0×0** with an empty child (both engines, all 4
+parent/ratio combos), and **280.13×560.25 overflowing an 800×400 parent** with one line of text —
+ratio correct, size wrong. Flex behaves differently from grid: flex _does_ clamp (200×400 for the
+same markup; 800×400 once `width: 100%` is stated); grid does not, because `max-height: 100%` cannot
+resolve against an auto row.
+The rule that fits all 450 measured rows: **the axis you state explicitly wins, `aspect-ratio`
+derives the other, and `max-*` truncates the derived axis without shrinking the stated one back.**
+So `max-pair + width: 100%` is ratio-correct exactly when the letterboxing happens to fall on the
+axis you did not state — half the time. The only two real engine divergences in the whole study live
+here: block-level max-pair (Chromium 200×400 vs **WebKit 800×400**) and absolutely-positioned
+`max-pair + width: 100%` (Chromium 800×400 vs WebKit 200×400).
+There **is** a working `max-*` variant — see **Recipe D**. The `min()` formula in `.stuic-frame` was
+16/16 ratio-correct, then 12/12, then 6/6, in both engines, with zero overflow and zero degenerate
+cases.
+
+**G2 — `container-type` does NOT create a fixed containing block. Readers arrive believing the
+opposite.**
+Neither `container-type: inline-size` nor `container-type: size` makes an element a containing block
+for `position: fixed` (or `position: absolute`) descendants. Measured `0,0 1200x800` — untrapped —
+on Chromium 149, Chromium 151, WebKit 26.5 and Firefox 153, at 1200×800 / 400×900 / 900×400.
+Computed `contain` reads back `"none"`. The CSSWG removed layout containment from `container-type`
+in 2024 (csswg-drafts#10544) and every engine shipped the change.
+`src/lib/utils/containing-block.ts` already documents this and deliberately does not check
+`container-type`; `src/lib/css/frame.svelte.test.ts` locks it.
+**What _does_ trap, measured:** `contain: layout` alone is sufficient; `contain: paint` alone is
+also sufficient; so are `content`, `strict`, `transform`, `perspective`,
+`will-change: transform`, `backdrop-filter`, `content-visibility: auto`. `contain: size`,
+`contain: style`, `overflow: hidden` and `container-type: *` do **not**. Containment and container
+queries are orthogonal knobs — you opt into trapping explicitly.
+Version caveat that _does_ matter: `filter: blur(0px)` **does** form a fixed containing block in
+WebKit 26.5. `containing-block.ts` deliberately ignores `filter` on WebKit because older Safari did
+not, so quote engine versions whenever you rely on this.
+
+**G3 — the top layer escapes geometry, but NOT inheritance, and NOT container units.**
+Geometry: confirmed and total. A `<dialog>.showModal()` or `[popover]` that is a DOM child of the
+frame measures `0,0 1200x800` regardless of `contain: layout paint`, `contain: strict`,
+`container-type: size`, `transform`, `filter`, `overflow: hidden`, or page scroll. Hit-testing
+agrees. With the UA `max-width` left alone it measured `1162x762` at a 1200×800 viewport
+(`calc(100% - 6px - 2em)` against the **viewport**).
+**But custom properties inherit into the top layer normally.** Measured: a dialog that is a DOM child
+of the frame reads `--fw: "137px"` and sizes to 137px; the same dialog moved to `<body>` reads `""`
+and falls back. So the reason to hoist a var to `:root` is **portalling**, not the top layer.
+**And `cq` units in the top layer are not lost either.** `50cqw`/`50cqh` inside an open modal dialog
+that is a DOM descendant of a `container-type: size` frame measured **150×100** — resolved against
+the frame. Only after the dialog is moved to `document.body` does it fall back to the viewport
+(600×400).
+
+**G4a — `contain: paint` clips, and without it the overflow escapes onto the bars.**
+`paint`, `layout paint`, `content`, `strict` and plain `overflow: hidden` all clip and make the
+overflow unhittable; `contain: layout` alone does not clip. The sharper version of this gotcha:
+_without_ clipping, overflow doesn't disappear — it **escapes the letterbox and paints on the bars**,
+which is arguably worse. Measured with `contain: layout` alone: content at `y = 620` outside a frame
+that ends at `y = 260`, `scrollTop` pinned at 0, and **hittable** — it paints on the bars. Add
+`paint` (or `overflow: hidden`) and the same content becomes unreachable (`elementFromPoint` →
+`HTML`).
+Also measured, so nobody re-derives it: `contain: layout paint` does **not** block scroll
+reachability when the frame _is_ a scroll container — `scrollTop` reaches 400/400 and the bottom
+element is hittable. The problem with that combination is G4b, not scrolling.
+
+**G4b — see the callout above.** Frame as fixed containing block + frame as scroll container =
+every `position: fixed` descendant at `y = -scrollTop`.
+
+**G5 — `cq` units DO resolve on the element that declares `container-type`. They just resolve
+against something else — silently.**
+Readers commonly believe the single-element version "doesn't resolve". It resolves fine. An
+element's own `container-type` never applies to itself, so `cq` units on it query the nearest
+**ancestor** query container — and **fall back to the small viewport when there is none**, with a
+plausible number and no warning.
+Measured: `#frame { container-type: size; width: 50cqw; height: 25cqh }` with no ancestor container
+→ **600×200** at 1200×800, **200×225** at 400×900, **450×100** at 900×400 — i.e. it tracks the
+_window_. With an ancestor `container-type: size` sized 500×300 → **250×75 at every viewport**.
+The nested shape (frame consumes the parent's `cq` units _and_ declares its own `container-type`)
+measured **150×300, identical with or without the self-declaration**. The two-element split is
+required **for the descendants**, not because the frame's own `min()` breaks.
+**Axis eligibility, with a number:** ancestor `size` 500×300, frame `inline-size` 250 wide,
+descendant `50cqw`/`50cqh` → **125×150**. `cqw` came from the frame; `cqh` fell _through_ it to the
+ancestor. `container-type: inline-size` is safe only if nothing inside ever uses
+`cqh`/`cqb`/`cqmin`/`cqmax`. **Use `size` (`@container-size`), not `inline-size`.**
+
+**G6 — a width-only bail-out breakpoint is usually wrong. (Design guidance, NOT a browser
+measurement.)**
+A ratio-derived width collapses on a landscape phone, and a short-but-narrow desktop window is not a
+handset. Both known viewport call sites needed a second condition — a `min-height: 600px`, or a
+`max-aspect-ratio: 3 / 5`. This is a content fact about your layout, not something a probe can
+measure.
+
+**G7 — prefer classic `max-width:` / `max-aspect-ratio:` over media-query range syntax. (NOT
+measured here.)**
+Media-query range syntax (`(width <= 40rem)`) landed in Safari 16.4. On an older engine the query
+fails to parse and is dropped **whole**, silently restoring the desktop layout on a phone. The
+WebKit build used for this study was 26.5, so no pre-16.4 datapoint exists. Treat this as a
+deployment-target rule, not a measurement.
+
+**G8 — `dvh` vs `vh`: a real trade-off, with no measured mobile-chrome magnitude.**
+Headless Chromium and WebKit report `100vh == 100dvh == 100svh == 100lvh`, so the mobile browser
+chrome behaviour **was not exercised**. What _was_ measured: `100dvh` is live — resizing
+1200×800 → 1200×400 moved the frame width from 400px to 200px.
+Mechanically, therefore: on a browser where `dvh` shrinks as chrome expands, a height-derived width
+shrinks by the same factor, so the frame's **horizontal** edges move during a vertical scroll.
+`svh` pins them, at the cost of being wrong in the other chrome state. `.stuic-frame` uses `dvh`;
+swapping it is a one-token change (`--stuic-frame-width: min(100vw, calc(100svh * (…)))`). Do not
+quote a Safari magnitude — nobody measured one.
+
+**G9 — `--stuic-frame-aspect-ratio: 16 / 9` plus an unparenthesised division is 81× too small.**
+`calc(100vw / var(--r))` becomes `calc(100vw / 16 / 9)` = viewport ÷ 144. Measured **8.33px instead
+of 675px** at 1200×800, **2.77px instead of 225px** at 400×900, and **8.33 / 2.77 / 6.25 instead of
+675 / 225 / 506.25** in container-unit space. No parse error, no console warning.
+Multiplication is coincidentally correct (`calc(100dvh * 16 / 9)` = 1422.22 = the right answer),
+which is exactly what teaches the wrong habit. **Parenthesise every `var()` in every `calc()`, for
+both operators.** `frame.css` does; your code must too. If the ratio arrives from config or YAML,
+wrap it at the injection site: `style="--stuic-frame-aspect-ratio: calc({aspect})"` is valid for
+both `"16 / 9"` and `"0.48"`.
+
+**G10 — `@property`-registering the ratio converts a loud failure into a quiet one.**
+`syntax: "<number>"` rejects `16 / 9` outright (both engines) and substitutes the initial/inherited
+value — indistinguishable from a typo, with the page rendering plausibly at the library's default
+ratio. It also collapses `calc(16 / 9)` to a rounded number at computed-value time (675 → 674.98).
+stuic does not register it, deliberately.
+
+**G11 — deriving the width at `:root` makes scoped ratio overrides a silent no-op.**
+With `:root { --w: min(100vw, calc(100dvh * var(--r))) }`, `getComputedStyle(:root)['--w']` is
+already the string `"min(100vw, calc(100dvh * 0.5))"` — the ratio is substituted **eagerly**, the
+math is not evaluated, and descendants inherit that frozen string. Measured: overriding `--r` on the
+frame element **or on any ancestor** → **400px, unchanged, no error**. Only a `:root` or
+media-query override works.
+This is the repo's documented anti-pattern (see the Fallback Pattern in
+[conventions.md](./conventions.md)). Shipping **both** a `:root` declaration _and_ a usage-site
+fallback is the worst of the three options: the fallback becomes dead code and the scoped override
+still does nothing.
+
+**G12 — `var(--stuic-frame-width)` without the repeated fallback goes full-bleed.**
+Because nothing declares the token, a bare read is invalid-at-computed-value-time → the whole
+declaration falls back to `unset` → `width: auto`. Measured **1200px instead of 400px**.
+Repeat the entire expression at every read site — `.stuic-frame-col` in `frame.css` does exactly
+that, on purpose — or alias it once at `:root` using the recipe in the token-contract section above.
+
+**G13 — a grid/flex item's automatic minimum size overrides `aspect-ratio`.**
+A 3000px-tall child stretches an otherwise-correct frame to **350×3000, ratio 0.117**, in both
+engines. `min-height: 0` fixes it; `overflow: hidden` fixes it; `.stuic-frame` sets **both**, so a
+consumer's `overflow-visible` stays survivable. A future "cleanup" that deletes `min-height: 0`
+reintroduces this — `frame.svelte.test.ts` locks it.
+
+**G14 — any specified `height`, `min-height` or biting `max-height` beats `aspect-ratio` outright.**
+Measured: `aspect-ratio: .5; width: 300px; height: 100px` → 300×100 (r = 3.0);
+`aspect-ratio: .5; width: 300px; min-height: 900px` → 300×900 (r = 0.333);
+`aspect-ratio: .5; width: 100%; height: 100cqh` in a 300×800 container → 300×800 (r = 0.375).
+`aspect-ratio` only ever supplies an `auto` axis. This is _why_ `--stuic-frame-height: 100dvh` needs
+no `!important` and no specificity trick.
+
+**G15 — `height: 100dvh` is not ratio-locking.**
+Whenever `100vw < 100dvh × R`, the frame degenerates to **exactly the viewport**, with bars of 0 on
+both axes, taking the viewport's own ratio. That happened in **6 of 12** measured viewport × ratio
+combinations — including **every ratio at 390×844** (390×844, r = 0.462, where 0.48 / 0.5 / 1.778
+were asked for) and 16/9 at 1200×800, 1440×900 and 900×1400.
+It looks perfect on a 1440×900 desktop and is wrong on the target handset. That is why
+`.stuic-frame` defaults to `height: auto`, and why `--stuic-frame-height: 100dvh` is a deliberate,
+documented opt-out rather than the default.
+
+**G16 — `container-type: size` zeroes intrinsic block size.**
+Measured **500×0** on an auto-height element carrying 150px of content — the same as `contain: size`
+and `contain: strict`. `inline-size` gives the correct 500×150.
+`@container-size` is safe on `.stuic-frame` **only because the frame's height is always determined**.
+Slap `@container-size` on an auto-height box and you get a 0-tall element.
+
+**G17 — `position: fixed` + `overflow: hidden` on the letterbox traps and clips nothing.**
+Measured: `#lb { position: fixed; left: 100; top: 60; 300×200; overflow: hidden }` with a
+`position: fixed; inset: 0` **child** → child at `0,0 1200x800`, and still hittable at (700, 500).
+Being fixed-positioned and clipping does not make an element a containing block; only
+`contain: paint` / `contain: layout` (or a transform) does.
+Consequence: an overlay dropped **beside** the frame — a sibling of the frame, i.e. a child of the
+letterbox — escapes to the viewport. Only descendants of a `contain:`-ed **frame** are captured.
+
+**G18 — stuic's own components measure in viewport units that know nothing about your frame.**
+`src/lib/components/Backdrop/index.css` is `position: fixed; inset: 0; height: 100dvh`. Inside a
+frame shorter than the viewport, `inset` binds to the frame but the explicit `height` wins: measured
+a 300px-tall contained host rendering an 800px-tall fixed child, overflowing by 500px.
+Same family: `Modal.svelte` (`md:max-w-[calc(100vw-2rem)]`, `md:max-h-[80dvh]`), `Drawer.svelte`
+(`sm:w-[75vw]`), `AlertConfirmPrompt` (`max-h-[62vh]`), `Float/index.css` (`max-width: 100vw`,
+`--stuic-float-body-max-height: 70vh`), `popover.svelte.ts` and `spotlight.svelte.ts`
+(`max-width: calc(100vw - 1rem)`).
+**Budget for per-call-site tweaks.** "Toasts stay inside the frame with zero component changes" is
+not true of stuic's `Notifications` — see the interop section.
+
+**G19 — the overlay _actions_ still portal to `<body>` by default.**
+`popover`, `spotlight` and `dimBehind` all default their container to `document.body`
+(`popover` first checks for an enclosing `dialog[open]`). A popover anchored inside the frame is
+therefore portalled _out_ of it, and `fixedContainingBlockRect()` then measures the viewport — the
+3.152.0 containing-block awareness never fires, because by then there is no CB ancestor left.
+Pass `container: frameEl`. See the interop section.
+
+**G20 — print. (Not measured; stated as a known consequence.)**
+`fixed inset-0` + `overflow: hidden` + `100dvh` prints one page and clips everything else. stuic
+ships no `@media print` rules for the frame. If print matters, write your own query that unsets the
+frame's sizing.
+
+**G21 — safe-area insets are unavailable in exactly the deployment that needs them.**
+`.stuic-safe-area-*` and the `--stuic-safe-area-*` variables are gated behind
+`@media (display-mode: standalone), (display-mode: fullscreen)` and hard-zero in a Capacitor
+WKWebView — i.e. unusable in the packaged-app case where a letterboxed layout most wants them.
+Cross-reference, do not try to solve it inside the frame preset. See the safe-area section below.
+
+**G22 — `.stuic-frame` silently loses its ratio as a flex-column item.**
+Measured at 1200×800 in a `flex-col` shell with a 60px header: **400×740, ratio 0.5405**, where the
+same frame in a grid parent measures **400×800, ratio 0.5000** — both engines. The ratio-derived
+800px becomes the flex base size, and `min-height: 0` — the declaration **G13** calls load-bearing —
+removes the automatic minimum that would otherwise stop the shrink.
+Nothing stuic ships is affected: every recipe, README example and demo uses a grid, block or
+absolutely-positioned parent. But `<div class="flex flex-col h-dvh"><header/><div class="stuic-frame">`
+is a natural app shell, and it fails with no error and a plausible-looking box.
+`flex-shrink: 0` on the frame restores 400×800 — in markup, add `shrink-0`.
+
+**G23 — an _invalid_ `--stuic-frame-aspect-ratio` fails silently and full-bleed.**
+Measured at 1200×800 with content: a valid `0.48` gives **384×800 @ x = 408**, while `16 9`, `red`,
+`1px`, `50%` **and a declared-but-empty value** all give **1200×48 @ x = 0** in normal flow — a
+declared-but-empty value does _not_ fall back to the `var()` default of 1. `width` and
+`aspect-ratio` go invalid-at-computed-value-time together, so the result is indistinguishable from
+"the stylesheet didn't load", with no console warning. In a centred grid parent the same failure
+shrink-wraps instead: **267.73×48**.
+Contrast `--stuic-frame-height: banana`, which degrades gracefully back to 400×800. This is distinct
+from **G10**, which is about `@property` rejecting the `16 / 9` pair form.
+
+**Also fine, stated so nobody re-derives it:** RTL is clean. `margin-inline` is a logical
+property and `place-items` is writing-mode-relative; `inset` is the shorthand for the _physical_
+`top`/`right`/`bottom`/`left` (the logical forms are `inset-block`/`inset-inline`) and does not
+appear in `frame.css` at all. Nothing in `frame.css` is direction-sensitive.
+
+---
+
+## Working with stuic's overlays
+
+See the trapped / escaping / portalled table in
+[CSS Presets](./domains/css-presets.md#interop-with-the-rest-of-stuic) first.
+
+**Portalled actions — pass `container`.** `popover`, `spotlight` and `dimBehind` all accept
+`container?: HTMLElement | (() => HTMLElement | null)`, resolved through
+`resolveContainerOption()` in `src/lib/utils/overlay-container.ts`. A factory is useful when the
+frame element does not exist yet at action-setup time; returning `null` means "use the default".
+
+```svelte
+<script lang="ts">
+	let frameEl = $state<HTMLElement>();
+</script>
+
+<div bind:this={frameEl} class="stuic-frame contain-layout contain-paint">
+	<button use:popover={() => ({ content: "…", container: () => frameEl ?? null })}>
+		…
+	</button>
+</div>
+```
+
+Note that `dimBehind` keeps **one ref-counted backdrop per container**, so mixing framed and
+body-level call sites gives you two independent backdrops — usually what you want.
+
+**Top-layer escapees — reconcile with `.stuic-frame-col`.** A modal `<dialog>` and the
+`Notifications` popover are in viewport space no matter what you do to their ancestors. Put
+`.stuic-frame-col` on their **content wrapper** — not on the `<dialog>` itself, where the UA's
+`max-width: calc(100% - 38px)` (**G3**) leaves the column 38px narrow: measured frame 1200 / col
+1162 @ x = 19 at ratio 3, and frame 400 / col 362 @ x = 19 at 400×800 — still centred, but
+detuned, and precisely on the handset/bail-out path. Prefer a full-bleed dialog with the class on
+an inner wrapper, which re-aligns it onto the frame's column exactly. It reads the
+same `--stuic-frame-width` contract, with the fallback expression repeated so it works even when
+nothing declares the token (**G12**).
+
+**`BodyScroll` — know what it locks.** `src/lib/utils/body-scroll-locker.ts` pins `document.body`
+(`position: fixed; top: -scrollY`) and ref-counts nested locks. `ModalDialog` calls it on open
+unless `noScrollLock` is set; `Backdrop` takes the same `noScrollLock`, and `Drawer` forwards it as
+`noBackdropScrollLock`. **If your frame is
+the scroll container, this does nothing useful** — the body has no scroll to lock. Either lock the
+frame yourself, or do not make the frame the scroll container (**G4b**).
+
+**Containment detection is already correct.** `src/lib/utils/containing-block.ts` implements the
+G2-correct rule set (`contain: layout|paint|strict|content`, transforms, `perspective`,
+`will-change`, `content-visibility: auto`; **not** `container-type`; `filter`/`backdrop-filter`
+ignored on WebKit). It stops at top-layer elements (`:modal`, `:popover-open`, `:fullscreen`) since
+the top layer escapes every ancestor CB. `frame.svelte.test.ts` asserts both halves of that rule
+against the preset, so a regression in either file fails the suite.
+
+---

package/docs/architecture.md

@@ -55,6 +55,9 @@ src/lib/
 │
 ├── icons/                # Icon re-exports from @marianmeres/icons-fns
 │
+├── css/                  # CSS-only presets (classes + tokens, no JS)
+│   └── frame.css             # Ratio-locked frame (letterbox)
+│
 ├── index.css             # CENTRALIZED CSS imports
 └── index.ts              # Main barrel export
 ```
@@ -76,6 +79,9 @@ src/lib/
 @import "./components/Modal/index.css";
 @import "./components/Input/index.css";
 /* ... all component CSS ... */
+
+/* Layout preset CSS (classes only, no component) */
+@import "./css/frame.css";
 ```
 
 **DO NOT** use `import './index.css'` inside component `.svelte` files.

package/docs/domains/css-presets.md

@@ -0,0 +1,304 @@
+# CSS Presets Domain
+
+## Overview
+
+`src/lib/css/` holds **CSS presets**: a class plus a custom-property contract, with no JS and
+no Svelte component. A preset is used by putting a class on **your own** element and (optionally)
+setting a token on it or an ancestor.
+
+Today there is exactly one: the **ratio-locked frame** (`src/lib/css/frame.css`). This document
+also covers the two remaining global class surfaces that live directly in `src/lib/index.css`
+— `.scrollbar-thin` and `.stuic-safe-area-*` — because they have no other home.
+
+> **`G<n>` references** point at the measured gotcha list in
+> [Ratio-Locked Frame Reference](../RATIO_LOCKED_FRAME.md#gotchas) — every entry there carries
+> the number it was measured at, and in which engines.
+
+**Two rules govern everything below.**
+
+1. **Presets are in `@layer components`, so utilities always win.** Tailwind emits
+   `@layer theme, base, components, utilities`. `class="stuic-frame h-dvh overflow-y-auto bg-white"`
+   overrides every declaration in the preset. That is the escape hatch, by design. (Contrast:
+   `.scrollbar-thin` and `.stuic-safe-area-*` are deliberately **unlayered**, so they beat a
+   consumer's `utilities` layer — see their sections.)
+2. **stuic declares none of the preset's tokens anywhere.** Defaults exist only as `var()`
+   fallbacks at usage sites, per the Fallback Pattern in [conventions.md](../conventions.md).
+   This is what makes a scoped override (`style="--stuic-frame-aspect-ratio: 0.25"` on the element,
+   or on any ancestor) actually work. See **G11** for the measured cost of getting this wrong.
+
+---
+
+## 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.
+
+### The pattern in one line
+
+```
+parent:  centre + clip
+child:   width = min(available-width, available-height × ratio)
+```
+
+The child's height then comes from `aspect-ratio`. Deriving the width from the height and letting
+`aspect-ratio` derive the height back is **not** circular: `width` resolves first, and
+`aspect-ratio` only ever fills an `auto` axis (**G14**).
+
+### Classes
+
+| Class              | Does                                                                                                                                                | Use when                                                                                             |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `.stuic-frame`     | The ratio-locked box, sized in `vw`/`dvh`, centred via `margin: auto`                                                                               | The frame is anchored to the viewport                                                                |
+| `.stuic-frame-cq`  | Same width formula in `cqw`/`cqh`. **Combine with** `.stuic-frame`                                                                                  | The frame is nested (under a header, inside a flex column)                                           |
+| `.stuic-frame-col` | `width: min(100%, <frame width>)` + `margin-inline: auto`. Nothing else — no ratio. Viewport-space only — it cannot track a `.stuic-frame-cq` frame | Re-align a viewport-space element (top-layer dialog, body-portalled overlay) onto the frame's column |
+
+`.stuic-frame` also sets `min-height: 0` and `overflow: hidden`. Both are **load-bearing for the
+ratio**, not cosmetics — see **G13**. Do not "simplify" them away.
+
+`.stuic-frame-cq` must stay **after** `.stuic-frame` in source order (equal specificity, same
+layer). It is, in `frame.css`; do not reorder.
+
+### Token contract
+
+All three are consumer **inputs**. stuic declares none of them.
+
+| Token                        | Default (as a `var()` fallback)                                                | Meaning                                                                                                                                                                        |
+| ---------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `--stuic-frame-aspect-ratio` | `1`                                                                            | width ÷ height. Any value valid in `aspect-ratio:`                                                                                                                             |
+| `--stuic-frame-width`        | `min(100vw, calc(100dvh * (ratio)))`, or the `cq` form under `.stuic-frame-cq` | Wholesale width override. Bail-out value: `100vw` — **pair with `--stuic-frame-height: 100dvh`**; alone, `aspect-ratio` still supplies the height and you get a `100vw` square |
+| `--stuic-frame-height`       | `auto` ⇒ ratio-locked                                                          | Wholesale height override. `100dvh` ⇒ fill the height, derive the width                                                                                                        |
+
+The default ratio is **`1`**, not a plausible app ratio: a square is unmistakably "you forgot to set
+the ratio", where a plausible default would ship a plausible-looking wrong layout.
+
+**Ratio form.** Anything `aspect-ratio` accepts. Prefer `calc(16 / 9)` or a bare number. `16 / 9`
+works too — `frame.css` parenthesises every `var()` inside every `calc()`, so the library is safe
+with all three forms. **Your** `calc()`s are not: see **G9**.
+
+**The four override scenarios**, each measured:
+
+```css
+/* 1. GLOBAL — measured 450x900 at ratio 0.5 on a 1440x900 viewport;
+   384px wide at 1200x800 with the 0.48 below */
+:root {
+	--stuic-frame-aspect-ratio: 0.48;
+}
+```
+
+```html
+<!-- 2. SCOPED (per element, per ancestor; two frames, two ratios, one page) —
+     measured 225x900 at r=0.25 next to 1440x810 at r=1.7778 -->
+<div class="stuic-frame" style="--stuic-frame-aspect-ratio: 0.25"></div>
+```
+
+```css
+/* 3. MEDIA-QUERY WHOLESALE (the bail-out) — measured 320x568 full bleed;
+   without it, 284x568 with 18px bars */
+@media (max-width: 40rem) and (max-aspect-ratio: 3 / 5) {
+	:root {
+		--stuic-frame-width: 100vw;
+		--stuic-frame-height: 100dvh;
+	}
+}
+```
+
+```html
+<!-- 4. TOP-LAYER READ — a dialog that is a DOM descendant of the frame measures 225px,
+     tracking the scoped ratio (custom properties inherit into the top layer; geometry
+     does not). The same dialog portalled to <body> measures 450px, the :root ratio. -->
+<dialog class="m-0 h-dvh w-screen max-w-none border-0 p-0">
+	<div class="stuic-frame-col">…</div>
+</dialog>
+```
+
+**Aliasing the width** for call sites outside the frame (e.g. a dropdown that must not exceed the
+column). Measured working, both engines:
+
+```css
+:root {
+	--stuic-frame-aspect-ratio: 0.48;
+	--app-width: var(
+		--stuic-frame-width,
+		min(100vw, calc(100dvh * (var(--stuic-frame-aspect-ratio))))
+	);
+}
+```
+
+The alias freezes the ratio at its `:root` value — a scoped `--stuic-frame-aspect-ratio` override
+will not move it (**G11**), so use it only where the ratio is global.
+
+### What this preset deliberately does NOT ship
+
+Everything else in a letterbox layout is already a Tailwind v4 utility. All of these were compiled
+against this repo's own `tailwindcss@4.3.3`:
+
+| Job                                    | Tailwind v4 utility                       | Compiles to                   |
+| -------------------------------------- | ----------------------------------------- | ----------------------------- |
+| The letterbox bars                     | `fixed inset-0 grid overflow-hidden bg-*` | —                             |
+| Trap `position: fixed` descendants     | `contain-layout contain-paint`            | `contain: layout paint`       |
+| Frame is the scroll container          | `overflow-y-auto`                         | `overflow-y: auto`            |
+| `cq` units resolve here                | `@container-size`                         | `container-type: size`        |
+| (inline-size only — avoid, see **G5**) | `@container`                              | `container-type: inline-size` |
+| Clear the ratio entirely               | `aspect-auto`                             | `aspect-ratio: auto`          |
+
+Only the sizing formula is stuic's, because it is the only part Tailwind cannot express. The preset
+ships **no background** either — three known call sites paint three different ways, one of them on
+`body`.
+
+---
+
+## Decision tree
+
+**1. Locked box, or derived-width column?**
+
+- The whole composition scales proportionally, bars on one axis → `.stuic-frame` (leave
+  `--stuic-frame-height: auto`).
+- You want to fill the height and only clamp the width (a column that scrolls) →
+  `--stuic-frame-height: 100dvh`. **This is no longer ratio-locked** — read **G15** before choosing it.
+
+**2. Do fixed-positioned descendants belong to the frame, or to the screen?**
+
+- **To the frame** → add `contain-layout contain-paint` to the frame element. Everything
+  `position: fixed` inside now resolves against the frame, with zero component changes.
+  **Then do not also make the frame the scroll container — G4b.**
+- **To the screen** → add no containment. Top-layer dialogs and viewport-space overlays stay in
+  viewport space, and you reconcile them onto the column with `.stuic-frame-col`. This is the safer
+  default and the one that survives `Drawer`, `Backdrop` and scrolled routes.
+
+**3. `vw`/`dvh`, or `cq`?**
+
+- Frame anchored to the viewport (fixed wrapper, or `body`) → `.stuic-frame` alone.
+- Frame nested inside a box of unknown size → `.stuic-frame .stuic-frame-cq` **plus**
+  `@container-size` on an ancestor. `@container` (inline-size) is a silent trap (**G5**).
+
+**4. Where does the bail-out query go?**
+
+- On `:root` (or any ancestor), as tokens: `--stuic-frame-width: 100vw` and
+  `--stuic-frame-height: 100dvh`. Not as a class override on `.stuic-frame` — a token override
+  needs no `!important` and no specificity game, and it works without touching the markup.
+- Give it a **second condition** — a `min-height`, or a `max-aspect-ratio`. A width-only breakpoint
+  is almost always wrong (**G6**).
+
+---
+
+## Gotchas
+
+**Engine provenance, stated once.** Every measured number in **both** this document and the
+reference manual was taken with Playwright on **Chromium 151.0.7922.34** and **WebKit 26.5**, plus
+**Firefox 153** for the containment rows; results are identical across engines unless a row says
+otherwise, and none of it says anything about **old Safari**. The full list lives in
+[Ratio-Locked Frame Reference](../RATIO_LOCKED_FRAME.md#gotchas), where the items that are _not_
+browser measurements are labelled as such.
+
+> ### G4b — THE ONE THAT WILL ACTUALLY BITE YOU
+>
+> **Do not make the frame BOTH the fixed containing block AND the scroll container.**
+> `contain-layout contain-paint` + `overflow-y-auto` on the same element **breaks every
+> `position: fixed` descendant.**
+>
+> Measured, byte-identical in both engines: at `scrollTop: 600`, a `position: fixed; inset: 0`
+> child renders at **`y = -600`**, and a bottom-right FAB jumps from `y = 732` to `y = 132`. They
+> are not fixed any more; they are effectively `absolute` against the scroll origin.
+>
+> **Concrete stuic consequence:** open a `Drawer` on a route scrolled to 600 and the backdrop and
+> the drawer render at `y = -600`. The user taps, and nothing appears. `BodyScroll.lock()` does
+> **not** rescue this: `src/lib/utils/body-scroll-locker.ts` only pins `document.body`, which in
+> this layout has nothing to scroll (`window.scrollY === 0`), so the wheel keeps scrolling the
+> frame and the invisible drawer travels on to `y = -900`.
+>
+> Modal `<dialog>`s survive (top layer, and they block wheel chaining). `Drawer`, `Backdrop`,
+> `DropdownMenu` and the body-portalled actions do not.
+>
+> **Fix:** pick one. Either scroll an inner element and keep containment on the frame, or keep the
+> frame scrollable and accept viewport-space overlays, reconciling them with `.stuic-frame-col`.
+>
+> This is the trap most likely to be shipped by someone following the naive advice, because the
+> naive advice is internally consistent: _"`contain: paint` clips, so make the frame scroll."_
+
+**The full list — G1 through G21, each with its measurement — is in
+[Ratio-Locked Frame Reference](../RATIO_LOCKED_FRAME.md#gotchas).** The four most expensive, in
+short: the popular `max-width`/`max-height`/`aspect-ratio` formulation collapses to 0×0 in a centred
+grid/flex parent (G1); `container-type` does **not** create a fixed containing block (G2); `cq` units
+on the element that declares `container-type` resolve against an _ancestor_ container, or silently
+against the viewport (G5); and an explicit `height: 100dvh` is not ratio-locking (G15).
+
+---
+
+## Recipes
+
+Four worked recipes — viewport letterbox, `body`-as-letterbox, nested container-units, and the
+unit-free `max-*` variant — are in
+[Ratio-Locked Frame Reference](../RATIO_LOCKED_FRAME.md#recipes).
+
+---
+
+## Interop with the rest of stuic
+
+**The honest headline: adopting this preset does NOT make stuic's overlays frame-aware.** The
+preset names an ancestor; it does not teach anything to measure against it. Expect per-call-site
+tweaks.
+
+Three categories — trapped, escaping, portalled — each verified against the source:
+
+| Component / action                              | Rendering                                                                             | Behaviour under a `contain:`-ed frame                                                                                                                                                                                                                                                                                                                      |
+| ----------------------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Backdrop`                                      | `position: fixed; inset: 0; height: 100dvh`, in place                                 | **Trapped** by containment — but `height: 100dvh` overrides the inset-derived height, so it overflows a short frame (**G18**)                                                                                                                                                                                                                              |
+| `Drawer`                                        | wraps `Backdrop`, `position: fixed`, in place                                         | **Trapped** — and the primary victim of **G4b**                                                                                                                                                                                                                                                                                                            |
+| `DropdownMenu`, `Float`, `HoverExpandableWidth` | `position: fixed`, in place                                                           | **Trapped**, and already **CB-aware**: they measure via `fixedContainingBlockRect()` (3.152.0)                                                                                                                                                                                                                                                             |
+| `ModalDialog`, and `Modal` through it           | `<dialog>` + **always** `.showModal()`, **no portal**                                 | **Escapes** — top layer, viewport geometry. But it is still a DOM descendant, so custom properties inherit (**G3**): size its content from the inherited `--stuic-frame-aspect-ratio`, or use `.stuic-frame-col`, which repeats the fallback (**G12**). `Modal`'s own box is `md:max-w-[calc(100vw-2rem)]` / `md:max-h-[80dvh]` — viewport units (**G18**) |
+| `Notifications`                                 | `popover="manual"` + `showPopover()`, `position: fixed; inset: 0; width/height: 100%` | **Escapes** — top layer, viewport-sized. Toasts render on the bars, not in the frame                                                                                                                                                                                                                                                                       |
+| `popover`, `spotlight`, `dimBehind` actions     | **portalled to `document.body`** by default                                           | **Escape by portalling** (**G19**). Pass the `container` option added in 3.152.0                                                                                                                                                                                                                                                                           |
+
+**What to do about each** — passing `container` to the portalled actions, reconciling top-layer
+escapees with `.stuic-frame-col`, and what `BodyScroll` does and does not lock — is in
+[Ratio-Locked Frame Reference](../RATIO_LOCKED_FRAME.md#working-with-stuics-overlays).
+
+---
+
+## Safe-area insets (`.stuic-safe-area-*`)
+
+Global, **unlayered** so a deliberate `pt-*` in a consumer's `utilities` layer cannot silently win
+over a safe-area offset. Declared at the end of `src/lib/index.css`.
+
+Two surfaces:
+
+| Surface                                     | Semantics                                                                                                                                               |
+| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--stuic-safe-area-{top,right,bottom,left}` | `0px` always; the real `env()` inset only under standalone/fullscreen. **Compose** them: `padding-block-start: calc(1rem + var(--stuic-safe-area-top))` |
+| `.stuic-safe-area-{top,right,bottom,left}`  | **Set** the padding on that axis (they replace, not add). Only for elements that do not otherwise pad that side                                         |
+
+Both are gated behind `@media (display-mode: standalone), (display-mode: fullscreen)` and are
+therefore **inert in a normal browser tab** and **hard-zero in a Capacitor WKWebView** (**G21**).
+Non-zero values also require the consuming app to declare `viewport-fit=cover`.
+
+Full detail, including which components handle insets automatically and which do not, is in the
+**PWA safe-area insets** section of [README.md](../../README.md).
+
+---
+
+## `.scrollbar-thin`
+
+Global, unlayered, one declaration: `scrollbar-width: thin`. Declared in `src/lib/index.css`.
+
+Standard-property only — no `::-webkit-scrollbar` rules, no colour token. Apply it to any scroll
+container whose default scrollbar is too heavy. Because it is unlayered, a Tailwind utility will not
+override it; use an inline style or your own more-specific rule if you need to opt an element back
+out.
+
+---
+
+## Key files
+
+| File                                    | Purpose                                                                                                   |
+| --------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `src/lib/css/frame.css`                 | The preset. Three classes, nine declarations, and the reasoning inline                                    |
+| `src/lib/index.css`                     | `@import "./css/frame.css"`; also home to `.scrollbar-thin` and `.stuic-safe-area-*`                      |
+| `src/lib/css/frame.svelte.test.ts`      | Browser (Chromium) regression locks: the formula, plus G11–G15 and the G2 distinction                     |
+| `src/lib/css-wiring.test.ts`            | Asserts every stylesheet under `src/lib` is reachable from `index.css` — the failure nothing else can see |
+| `src/lib/utils/containing-block.ts`     | `isFixedContainingBlock()` / `fixedContainingBlockRect()` — the G2 rule set                               |
+| `src/lib/utils/overlay-container.ts`    | The `container` option shared by `popover` / `spotlight` / `dimBehind` (**G19**)                          |
+| `src/lib/utils/body-scroll-locker.ts`   | `BodyScroll.lock()` — locks `document.body` only (**G4b**)                                                |
+| `src/lib/components/Backdrop/index.css` | `position: fixed; inset: 0; height: 100dvh` (**G18**)                                                     |
+
+Related: [theming.md](./theming.md) for the token system, [components.md](./components.md) for the
+overlay components, [actions.md](./actions.md) for the portalled overlay actions.

package/docs/domains/theming.md

@@ -249,6 +249,8 @@ Override locally:
 <Button style="--stuic-button-radius: 0;">Square</Button>
 ```
 
+Some token sets belong to a CSS-only preset rather than to a component — e.g. `--stuic-frame-*` (ratio-locked frame / letterbox). Those are consumer **inputs** that stuic never declares; see [CSS presets](./css-presets.md).
+
 ---
 
 ## Key Files

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/stuic",
-	"version": "3.152.0",
+	"version": "3.153.0",
 	"packageManager": "pnpm@11.5.0",
 	"scripts": {
 		"dev": "vite dev",