@junoput01/junoui 0.4.0 → 0.6.0

package/docs/browser-support.md

@@ -0,0 +1,173 @@
+# Browser support
+
+What junoui requires, what it loses gracefully below that, and the short list of
+things that genuinely **break**. Stated because the failures are otherwise
+silent: an engine that does not understand a CSS at-rule, property or selector
+**drops it without reporting anything**. Nobody finds out from a console; they
+find out from a screenshot.
+
+Audited against `dist/css/juno.css` at v0.5.0 (2026-08-15).
+
+## The floor
+
+|                                                              | Safari / iOS | Chrome / Edge | Firefox                            |
+| ------------------------------------------------------------ | ------------ | ------------- | ---------------------------------- |
+| **Hard floor** — below this, things break                    | **17.0**     | **114**       | **125**                            |
+| **Supported floor** — everything works, minor polish missing | **17.5**     | 117           | 129                                |
+| **Full fidelity** — nothing missing                          | **26.0**     | 125           | — (anchor positioning not shipped) |
+
+**junoui's supported floor is Safari / iOS 17.5.** That is the version to put in
+a consumer's own support matrix.
+
+Read the three rows as three different questions:
+
+- Below **17.0** the Popover API is absent and junoui's overlay surfaces stop
+  being overlays. See [What breaks](#what-breaks) — this is not a polish
+  question, and one of the two failure modes is worse than "the menu does not
+  open".
+- Between **17.0 and 17.5** everything functions; entry animations are missing.
+- Between **17.5 and 26.0** everything functions and animates; anchored
+  surfaces (menu, popover, tooltip) land at their static position instead of
+  next to their trigger, because CSS anchor positioning is a Safari 26 feature.
+  This is a real visual defect, not a nicety — but the surface still opens,
+  still closes, still light-dismisses, and the app can pin it (see below).
+
+`package.json` carries a `browserslist` set to the **hard floor**, so tooling
+reads the line below which junoui is broken rather than the line below which it
+is imperfect. junoui itself runs no autoprefixer or transpiler — the field is a
+declaration for consumers' build tools, not something junoui acts on.
+
+## Feature audit
+
+Counts are occurrences in the built bundle.
+
+| Feature                                                                               | Uses | Safari / iOS | Below that                                                                                   |
+| ------------------------------------------------------------------------------------- | ---- | ------------ | -------------------------------------------------------------------------------------------- |
+| CSS anchor positioning (`position-area`, `position-try-fallbacks`, `position-anchor`) | 10   | **26.0**     | degrades — [misplaced surfaces](#anchored-surfaces-lose-their-anchor)                        |
+| `scrollbar-width`                                                                     | 4    | 18.2         | **guarded** — `::-webkit-scrollbar` fallback ships                                           |
+| `backdrop-filter` (unprefixed)                                                        | 14   | 18.0         | **guarded** — `-webkit-backdrop-filter` ships beside every use                               |
+| `@starting-style`                                                                     | 10   | 17.5         | degrades — no entry animation                                                                |
+| `transition-behavior` / `overlay` + `allow-discrete`                                  | 10   | 17.4         | degrades — surfaces pop instead of fading                                                    |
+| **Popover API** (`popover`, `popovertarget`, `:popover-open`)                         | 31   | **17.0**     | **breaks**                                                                                   |
+| `prefers-reduced-transparency`                                                        | 3    | 17.0         | degrades — blur stays on for users who asked it off                                          |
+| `@property`                                                                           | 1    | 16.4         | degrades — the gauge jumps to its value instead of sweeping                                  |
+| `color-mix()`                                                                         | 28   | 16.2         | degrades — role tints vanish (see the caveat below)                                          |
+| `@container`                                                                          | 2    | 16.0         | degrades — card and table stop reflowing at narrow widths                                    |
+| `:has()`                                                                              | 5    | 15.4         | degrades — the collapsible pillbar never collapses                                           |
+| `dvh` / `lvh`                                                                         | 10   | 15.4         | breaks layout — `block-size` falls back to `auto`, the app shell collapses to content height |
+| `oklch()`                                                                             | 190  | 15.4         | breaks colour — every token value is `oklch()`                                               |
+| `aspect-ratio`                                                                        | 7    | 15.0         | degrades — media tiles lose their ratio                                                      |
+| `@supports selector()`                                                                | 1    | 14.1         | the Popover guard below is inert (fails open to today's behaviour)                           |
+
+Two rows deserve a note.
+
+**`color-mix()` is listed as a degrade, and that is technically true and
+practically uncomfortable.** All 28 uses are tints, borders and shadows built
+from `var(--juno-role)`; when the function is unsupported the declaration is
+invalid and the property falls back to `transparent` or the previous cascade
+value. Text and icon colour, which take `var(--juno-role)` directly, survive. So
+nothing breaks — but role tinting is exactly the thing junoui exists to encode,
+and losing it erodes the contract even while the layout holds. It sits below the
+floor; it is listed so nobody discovers it by shipping to iOS 16.
+
+**`oklch()` and `dvh` are below every floor in this document** and are listed for
+completeness. If you are on iOS 15 you are not using junoui.
+
+## What breaks
+
+Exactly one thing, at exactly one version, and it has two failure modes.
+
+### Popover API, Safari / iOS < 17.0
+
+junoui's `.juno-menu`, `.juno-popover` and the top-layer `.juno-tooltip__bubble`
+are built on the native Popover API. The open/close, light-dismiss and ESC
+behaviour is the platform's; junoui ships only the surface. On an engine without
+it:
+
+1. **They never open.** `popovertarget` does nothing, so there is no way to
+   reveal the panel. The pillbar's overflow slot routes to `.juno-menu`, so the
+   overflow items are unreachable — which on a phone is where the secondary
+   navigation lives.
+2. **Worse: `.juno-menu` and `.juno-popover` become invisible click-eaters.**
+   The UA rule that hides a closed popover (`display: none` on any `[popover]`
+   that is not `:popover-open`) does not exist on an unsupporting engine, so the
+   panel participates in layout. junoui's own base rule sets `opacity: 0`, so it is
+   invisible, but both surfaces are `position: fixed` with no `pointer-events`
+   reset. The result is a 256–280 px invisible fixed panel sitting over the page
+   at its static position, swallowing taps on whatever it covers.
+
+   (`.juno-tooltip__bubble` escapes this: it inherits `pointer-events: none`
+   from the CSS-only tooltip rule it shares.)
+
+Failure mode 2 is the one that justifies a guard. A feature that is missing is
+an inconvenience; a feature that is missing and eats input is a bug report that
+looks like something else entirely. `base.css` therefore ships:
+
+```css
+@supports not selector(:popover-open) {
+  .juno-menu[popover],
+  .juno-popover[popover],
+  .juno-tooltip__bubble[popover] {
+    display: none;
+  }
+}
+```
+
+This makes failure mode 1 the _only_ failure mode: the panel is absent instead
+of invisibly present, the page underneath is fully usable, and the app can
+detect the same condition in one line
+(`CSS.supports('selector(:popover-open)')`) and render a non-popover fallback.
+
+`@supports selector()` itself needs Safari 14.1; below that the guard's
+condition is invalid, the block is skipped, and behaviour is exactly what it is
+today. Fail-open, and far below any floor here.
+
+### Anchored surfaces lose their anchor
+
+Not a break — recorded here because it is the largest visual regression between
+17.5 and 26.0 and it is easy to mistake for one.
+
+`.juno-menu`, `.juno-popover` and the top-layer tooltip position themselves with
+`position-area` / `position-try-fallbacks`, which is Safari **26.0**. Below it
+those declarations drop and the surfaces keep `position: fixed; inset: auto;
+margin: 0` — so they render at their static position rather than beside their
+trigger. They still open, close, light-dismiss and trap nothing.
+
+The documented remedy is the app's: pin `inset` on the element's `toggle` event.
+It is already noted in [popover.md](./components/popover.md) and is the reason
+the legacy `.juno-popover-anchor` wrapper is still exported.
+
+## Why this document exists
+
+Two silent failures of this exact class shipped and were found by looking at a
+phone, not by any tool:
+
+- **`backdrop-filter` unprefixed only.** Unsupported below Safari 18.0, so the
+  declaration was dropped and every glass surface — pillbar, dock, modal scrim —
+  rendered flat on iOS 17. Fixed 2026-08-05 by shipping
+  `-webkit-backdrop-filter` beside each use; both are in the bundle now, and the
+  audit table above tracks them as guarded.
+- **`scrollbar-width: none`.** Unsupported below Safari 18.2, so the scrollable
+  tab strip kept a visible scrollbar on iOS 17 and 18.0–18.1. Fixed the same day
+  with a `::-webkit-scrollbar { display: none }` companion.
+
+Neither produced an error. Both were "modern CSS, ships everywhere" right up
+until someone opened the page on the device. That is the argument for stating a
+floor and for auditing against the built bundle rather than against intent: the
+cost of a missing feature is paid by the consumer, silently, at a time and place
+junoui never sees.
+
+**When you add a feature below the floor, say so here.** A new at-rule,
+selector or property whose support is newer than Safari 17.5 belongs in the
+audit table with its degrade-or-break verdict, and if the verdict is _break_ it
+needs an `@supports` guard in the same change. Guards are for functional
+failures only — a missing animation does not get one, and wrapping cosmetic
+declarations in `@supports` costs bytes and buys nothing.
+
+## Related
+
+- [ios-conformance.md](./ios-conformance.md) — iOS metrics and behaviour: safe
+  areas, tap targets, the viewport-unit decision, and the Home-Screen standalone
+  letterbox.
+- [getting-started.md](./getting-started.md) — the required `viewport` meta,
+  which is a separate silent failure with the same shape.

package/docs/getting-started.md

@@ -48,6 +48,28 @@ Two things depend on it, and both fail **silently**:
 
 Details and sources: [ios-conformance.md](./ios-conformance.md).
 
+## Browser support
+
+|                                             | Safari / iOS | Chrome / Edge | Firefox |
+| ------------------------------------------- | ------------ | ------------- | ------- |
+| **Supported floor** — everything works      | **17.5**     | 117           | 129     |
+| **Hard floor** — below this, overlays break | 17.0         | 114           | 125     |
+
+The hard floor is the Popover API. Below it, `.juno-menu`, `.juno-popover`, the
+top-layer tooltip and the pillbar's overflow slot cannot open; junoui hides them
+with an `@supports` guard so they are absent rather than invisible-and-blocking,
+and your app can branch on `CSS.supports('selector(:popover-open)')`. Between
+the two floors the only loss is entry animations (`@starting-style`). Anchored
+placement for those surfaces is a Safari 26 feature — below it they open at
+their static position, and the app can pin `inset` on the `toggle` event.
+
+The hard floor is what `package.json`'s `browserslist` declares. junoui runs no
+autoprefixer of its own; the field is there for your build tooling.
+
+**Every one of these failures is silent** — an engine drops CSS it does not
+understand without reporting anything. The full audit, per feature, with the
+degrade-vs-break verdict: [browser-support.md](./browser-support.md).
+
 ## The model
 
 - **Palette** — `standard` · `colorblind` · `soft`

package/docs/icon-subsetting.md

@@ -0,0 +1,88 @@
+# Icon subsetting
+
+junoui's sprite carries **every** icon it ships. That is right for a `<use>`
+reference to an external file (the browser fetches it once, caches it, and
+unused symbols cost nothing to render) — but Safari intermittently drops
+external sprite refs, so apps inline the sprite instead
+([`junoui/icons/inline`](../scripts/build-icons.mjs)), and an inlined sprite
+puts every icon in the app's main bundle.
+
+`junoui/subset` is the build-time half: a pure, dependency-free Node module a
+consumer's build step runs over the shipped sprite.
+
+```js
+import { readFileSync } from 'node:fs';
+import { subsetSprite, spriteSymbolNames } from '@junoput01/junoui/subset';
+
+const sprite = readFileSync(new URL(import.meta.resolve('@junoput01/junoui/icons')), 'utf8');
+const svg = subsetSprite(sprite, ['gear', 'x', 'squares-four']);
+```
+
+| Export                        | Returns                                                              |
+| ----------------------------- | -------------------------------------------------------------------- |
+| `spriteSymbolNames(sprite)`   | every icon name the sprite defines, in document order.               |
+| `subsetSprite(sprite, names)` | the same sprite carrying only `names` — banner and wrapper verbatim. |
+
+- **Names are bare icon names** (`'gear'`), never the prefixed symbol id.
+- **An unknown name throws.** A silently dropped symbol renders as an empty
+  `<svg>` in the app, which nobody notices until a user reports a blank space —
+  so it fails the build instead.
+- **The output is stable**: symbol order follows the sprite, not the request,
+  so a reordered list produces a byte-identical file.
+- **The MIT Phosphor notice survives the trim** — carrying it is a
+  redistribution condition, so the banner is part of the contract, not
+  decoration.
+- Node-only tooling on purpose: subsetting at runtime would defeat the point.
+
+## Vite
+
+```js
+// vite.config.ts — a virtual module holding just this app's icons
+import { subsetSprite } from '@junoput01/junoui/subset';
+
+const ICONS = ['gear', 'x', 'squares-four']; // the app's manifest
+const VIRTUAL = 'virtual:juno-icons-subset';
+
+const iconSubset = {
+  name: 'juno-icon-subset',
+  resolveId: (id) => (id === VIRTUAL ? `\0${VIRTUAL}` : null),
+  load(id) {
+    if (id !== `\0${VIRTUAL}`) return null;
+    const sprite = readFileSync(new URL(import.meta.resolve('@junoput01/junoui/icons')), 'utf8');
+    return `export default ${JSON.stringify(subsetSprite(sprite, ICONS))}`;
+  },
+};
+```
+
+Keep the manifest where the app's own type for icon names is derived from it,
+so a name that is not in the manifest is a **compile** error rather than a
+blank space at runtime.
+
+## Injecting a subset
+
+Safari intermittently drops external sprite refs (`<use href="file.svg#id">`),
+so the reliable path is a **same-document** ref — which means the sprite has to
+live in the document. `junoui/icons/inline` does that for the full set and
+auto-installs on import; a consumer that subsets wants the injection without
+the 25 kB of symbols, so the mechanism ships separately:
+
+```js
+import { installSprite } from '@junoput01/junoui/icons/install';
+import sprite from 'virtual:my-icon-subset'; // your build's subset (see above)
+
+installSprite(sprite);
+```
+
+| Export                 | Carries                   | Use                                           |
+| ---------------------- | ------------------------- | --------------------------------------------- |
+| `junoui/icons/install` | ~1 kB, no icons           | You subset. Pass your own sprite.             |
+| `junoui/icons/inline`  | the full 66-symbol sprite | You don't subset. Import for the side effect. |
+
+- **Both are id-guarded on the same `juno-icon-sprite` holder**, so importing
+  the full module alongside a subset does not produce two hidden holders
+  shadowing each other — whichever installs first wins and the second call is a
+  no-op returning `false`.
+- `installSprite` returns `true` when it injected, `false` when a sprite was
+  already present or there is no document (server-side, pre-hydration).
+- Subsetting only pays off if the full module never enters the bundle: import
+  `icons/install`, not `icons/inline`.

package/docs/ios-conformance.md

@@ -7,6 +7,10 @@ Most numbers the design community attributes to Apple are not in Apple's text.
 This page exists so nobody re-derives folklore, and so nobody "fixes" a correct
 value into a wrong one later.
 
+This page is about **metrics and behaviour** on iOS. For _which iOS versions
+junoui runs on at all_ — the supported floor, what degrades below it, and what
+breaks — see [browser-support.md](./browser-support.md).
+
 > **Verifying anything here.** Apple's HIG is a JavaScript app: a plain `curl`
 > returns an empty shell. Check the backing DocC JSON instead —
 > `developer.apple.com/tutorials/data/design/human-interface-guidelines/<page>.json`.
@@ -157,11 +161,10 @@ to `lv*`** — that is the spec-level cause of the classic `100vh` overflow: a
 junoui uses **zero raw `vh`**. Full-height surfaces use `dvh`
 (`layout.css`, `drawer.css`) and `85dvh` caps the bottom sheet.
 
-Caveats worth knowing before changing any of that:
+Caveats that constrain the choice:
 
 - `dv*` is explicitly **not stable** and not guaranteed to update every frame,
-  so it can churn while the address bar collapses. `sv*` is the calm choice when
-  a surface must never overflow.
+  so it can churn while the address bar collapses. `sv*` never overflows.
 - iOS shipped viewport-unit bugs into the **iOS 26** era: Safari 26.0 fixed
   `lvh`/`vh` being sized against the _small_ viewport in `SFSafariViewController`.
   The underlying WebKit bug (255708, filed 2023) is **still open**, so Apple's
@@ -176,6 +179,193 @@ Caveats worth knowing before changing any of that:
   [Safari 26.0 release notes](https://developer.apple.com/documentation/safari-release-notes/safari-26-release-notes),
   [WebKit bug 255708](https://bugs.webkit.org/show_bug.cgi?id=255708).
 
+### The decision: `dvh` stays at both call sites
+
+Decided 2026-08-15 (ticket 20260803-033, step 1). `dvh` is kept for **both**
+`.juno-app-shell` and `.juno-drawer`, against the "`sv*` is the calm choice"
+instinct above. The reasoning below is the part to read: it generalises, the
+verdict does not.
+
+**First, price the two options at the only moment they differ** — when browser
+chrome retracts. There is no other moment. Before it and after it, whichever
+unit you picked is simply the current viewport.
+
+|       | what it costs when chrome retracts                                                                                                                                                                                                    |
+| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `dvh` | The surface **grows**, so it relayouts. `dv*` is not frame-guaranteed, so that growth can arrive late or in steps. If the surface contains a scroller, the scroll port changes height _during the scroll that caused the retraction_. |
+| `svh` | The surface **does not move** — and is now short by `lvh − svh`. That gap is permanent for the rest of the session, and it is at the bottom edge, where the page background shows through under whatever the surface pinned there.    |
+
+So this is not "stable vs twitchy". It is **one relayout** against **a permanent
+dead strip**. Pick by asking which of those the surface can afford.
+
+**`.juno-app-shell` — `block-size: 100dvh` (`layout.css`).** The shell's whole
+job is to hold the dock against the bottom edge. Under `svh` the dock detaches
+from that edge the first time the user scrolls and stays detached, floating
+`lvh − svh` px up with page background beneath it — a visible defect on every
+subsequent frame, under the primary navigation. The `dvh` relayout it avoids is
+cheap here by construction: the shell is `overflow: hidden` and the scrolling
+lives in `.juno-app-shell__main`, so growing the shell grows the scroll port and
+moves the dock. **No text reflows** — no line breaking, no measured content, no
+intrinsic sizing is touched. One cheap relayout beats a permanent gap.
+
+**`.juno-drawer` — `block-size: 100dvh; max-block-size: 100dvh`
+(`drawer.css`), and the same for the `--bottom` sheet's `60dvh`/`92dvh` and the
+modal's `85dvh` cap.** Here the `dv*` instability **cannot bite at all**, and
+that is the whole argument. The drawer is a `<dialog>` opened with
+`showModal()`: it is in the top layer and the document beneath it is inert. iOS
+Safari retracts and expands chrome in response to _document_ scroll — an inner
+overflow scroller does not drive it — so chrome cannot change state for the
+drawer's whole lifetime. `dvh` therefore never churns, and `svh` cannot prevent
+an overflow that cannot happen. What `svh` _would_ still do is leave the gap:
+open the drawer after scrolling (the ordinary case — you scroll, then reach for
+the menu) and chrome is already retracted, so a `svh` drawer stops
+`lvh − svh` px short of the bottom of a screen it is supposed to fill. `svh`
+here is a pure loss.
+
+> **The exception, and it is the app's to own.** A `<dialog>` opened with the
+> `open` **attribute** instead of `showModal()` is _not_ in the top layer and
+> does **not** block page scroll. Behind such a drawer the page scrolls, chrome
+> retracts, and the churn is live. junoui's CSS cannot tell the two open paths
+> apart. The drawer is documented as `showModal()`
+> ([drawer.md](./components/drawer.md)); open it non-modally and the churn is yours.
+
+### The rule, for a component that does not exist yet
+
+Ask one question — **can browser chrome change state while this surface is on
+screen?** — and then:
+
+1. **It can, and the surface is anchored to the bottom edge** (or contains
+   something that is: a dock, a pillbar, a sticky footer) → **`dvh`**. You are
+   buying edge-adherence and paying one relayout per chrome transition.
+2. **It can, and the surface must not resize once laid out** — content whose
+   height JS measures, a canvas, an animation mid-flight, anything where a
+   late reflow is worse than a gap → **`svh`**. You are buying stability and
+   paying up to `lvh − svh` of dead space, permanently.
+3. **It cannot** — top-layer surfaces (`showModal()` dialogs, `popover`), where
+   the page beneath is inert → **`dvh`**, always. `svh` there buys nothing and
+   still pays the gap on any surface opened while chrome is retracted.
+4. **Never `vh` / `lvh` for a height that must fit.** `vh == lvh` sizes as if
+   chrome were retracted, so on a page where it is _not_, the box overflows by
+   exactly the chrome's height. That is the classic `100vh` bug and it is a
+   spec consequence, not a browser bug. The one legitimate `lvh` in this
+   codebase is the standalone unlock's spacer (`base.css`), which is _supposed_
+   to overflow.
+
+**In `display-mode: standalone` this whole decision is moot** — there is no
+retractable chrome, so `svh == dvh`. Measured on the device: `100dvh`,
+`100svh` and `100%` all resolve to 812 while `100lvh` and `100vh` resolve to
+874, which is the letterbox defect below, not a chrome transition.
+
+### A note on raw `vw`
+
+"Zero raw `vh`" is about **`vh`**. junoui does use raw `vw` in five places
+(`layout.css:18`, `pillbar.css:231`, `popover.css:33`, `toast.css:26`,
+`drawer.css:116`) and that is deliberate: horizontal chrome does not retract,
+so `vw`/`lvw`/`svw`/`dvw` are the same number and the `vh` trap has no
+horizontal twin. The real `vw` hazard is different — `100vw` includes the
+classic scrollbar gutter, so a full-bleed `100vw` box overflows a desktop page
+that has a scrollbar. Every call site above either caps well below `100vw`
+(`min(…, 240px)`, `min(360px, …)`, `85vw`, `clamp()`) or subtracts more than a
+scrollbar's width (`calc(100vw - var(--juno-space-24))`). Keep it that way; a
+bare `inline-size: 100vw` is a bug.
+
+## Home-Screen standalone: the letterbox, and why `base.css` unlocks it
+
+**The fact, and it is the most expensive thing this codebase has learned about
+iOS: in `display-mode: standalone`, iOS sizes the window from the document's
+RESTING scrollability at launch, and letterboxes a document that cannot scroll
+by exactly `env(safe-area-inset-top)`.**
+
+Measured, not inferred. iPhone 16 Pro (402×874 pt), iOS 18.7 / Safari 26.6:
+
+|                                                |         |
+| ---------------------------------------------- | ------- |
+| `screen.height`                                | **874** |
+| `window.innerHeight` · `visualViewport.height` | **812** |
+| `100dvh` · `100svh` · `100%`                   | **812** |
+| `100lvh` · `100vh`                             | **874** |
+| `env(safe-area-inset-top)`                     | **62**  |
+| `env(safe-area-inset-bottom)`                  | 34      |
+| `window.screenY`                               | 0       |
+
+`874 − 812 = 62 = env(safe-area-inset-top)`, exactly. WebKit sizes the
+standalone window as if a retractable toolbar existed, subtracts its height,
+pins the window to the **top**, and then never covers the strip it reserved — so
+the bottom 62 px of the display sits outside the web view and paints black on
+every screen. This is a spec violation on its face: in standalone there is no
+retractable browser UI, so the large and dynamic viewports **must** be equal
+(css-values-4 §6.1.2.1), and here they differ by 62.
+
+### It is the resting structure, and only the resting structure
+
+One install, four document structures, switched by a pill and **persisted across
+cold launches** (`localStorage`), verdict taken per launch:
+
+| document structure at rest                                                              | window                |
+| --------------------------------------------------------------------------------------- | --------------------- |
+| document scrolls normally                                                               | **874** — full screen |
+| fixed shell, an inner scroller, document cannot scroll                                  | 812 — letterboxed     |
+| fixed shell, nothing scrollable anywhere                                                | 812 — letterboxed     |
+| fixed shell **+ the document left scrollable behind it** by an invisible in-flow spacer | **874** — full screen |
+
+**Transient scrollability is not enough.** Seven in-page interventions across
+five controlled runs — with a placebo pinned to the first slot, rotation of the
+rest, and `prior`/`during`/`afterUndo` sampling — all measured 812. Every one of
+them varied scrollability for ~300 ms mid-session and undid itself. iOS samples
+the structure at launch; the axis that decides the window was never varied.
+
+Two device-proven negatives, recorded so nobody spends another round on them:
+
+- **`apple-mobile-web-app-status-bar-style` makes no difference.** `black` and
+  `black-translucent` were each tested with a fresh Home-Screen install. Both
+  letterbox identically.
+- **Nothing applied after first paint reaches it** — see the seven interventions
+  above. The window does correct itself to 874 spontaneously, between 6 seconds
+  and 43 minutes after navigation, and then holds for the life of that document;
+  a reload starts a new document, which starts letterboxed again.
+
+### What junoui does about it
+
+`base.css` carries the **iOS standalone letterbox unlock**: keep the document
+scrollable behind the app, using an invisible `body::after` spacer taller than
+the large viewport, so the document always overflows whatever window iOS grants.
+`overscroll-behavior: none` stops the ghost scroller rubber-banding; apps put
+`overscroll-behavior: contain` on their real scrollers so an inner fling never
+chains into it.
+
+The gate is three conditions, all required — `display-mode: standalone` (only
+installed apps letterbox), `pointer: coarse` (keeps macOS Dock apps out), and
+`@supports (-webkit-touch-callout: none)` (iOS/iPadOS WebKit only). Selectors
+carry `html:root` (specificity 0,1,2) deliberately: app resets commonly declare
+`body { overflow: hidden }` at (0,0,1) _after_ this sheet, and the unlock has to
+win the cascade without `!important`.
+
+Consumer obligations, both silent if missed:
+
+- **Ship the unlock at first parse.** iOS samples at launch, and a bundled
+  stylesheet arrives after it. An app whose shell paints before its CSS bundle
+  must inline a copy of the unlock in the document head — junoui's copy in
+  `juno.css` is too late on its own.
+- **Do not override `body::after`.** The spacer is `body::after`; a consumer
+  that needs that pseudo-element for itself must reproduce the spacer at the
+  same gate. None of junoui's own components use it.
+
+### How to know it is fixed upstream
+
+In standalone, `window.innerHeight === screen.height` **and
+`100lvh === 100dvh`**, for a document that **cannot** scroll — that is the case
+that still misbehaves. When that holds, the unlock is dead weight and can be
+removed. Until then it is harmless where it does not apply, because the gate
+excludes every non-iOS and non-installed context.
+
+- Sources: nexora `CLAUDE.md` §15, entry dated 2026-08-13; the four-mode testbed
+  `web/public/expansion-demo.html` (kept as a standing rig); 201 device readings
+  collected by `scripts/viewport_probe_collect.py`. Tracked upstream as ticket
+  20260812-006, drafted for WebKit Bugzilla / Feedback Assistant and awaiting
+  filing. Related Apple Developer Forums threads: 800798, 798014 (iOS 26
+  safe-area insets wrong until a background/resume — the "corrects itself later"
+  shape matches exactly), 797124.
+
 ## Typography
 
 iOS: **17 pt default body size, 11 pt minimum**; Dynamic Type must accommodate
@@ -194,6 +384,14 @@ iOS Safari is widely observed to zoom the page onto a focused field under 16px.
 behavior, not published spec. The mitigation is harmless, so it stays — but do
 not cite it as documented, and re-verify it on iOS 26.
 
+The floor is now a checked claim, not an asserted one:
+`test/visual/tap-targets.spec.mjs` reads the computed `font-size` of a
+`.juno-input` under the coarse-pointer Playwright project and asserts `>= 16`.
+That check is also what found the floor had never worked — the rule sat in
+`base.css`'s `@media (pointer: coarse)` block, where a media query adds no
+specificity, so `components/input.css`'s own `.juno-input` font-size beat it on
+source order. It now lives in `input.css`. Keep it there.
+
 ## Things a stylesheet controls that Apple says nothing about
 
 No primary Apple source was found for any of: `touch-action`,
@@ -214,7 +412,11 @@ One confirmed change raises the stakes: as of iOS/iPadOS 26, **every website
 added to the Home Screen opens as a web app by default** — "there are now zero
 requirements for 'installability'". junoui's CSS may therefore run in a
 standalone context, where `viewport-fit` and `env()` govern home-indicator and
-Dynamic Island clearance, for sites that never opted in.
+Dynamic Island clearance, for sites that never opted in. The concrete
+consequence is measured above in
+[Home-Screen standalone: the letterbox](#home-screen-standalone-the-letterbox-and-why-basecss-unlocks-it) —
+a site that never asked to be a web app now inherits both the letterbox and the
+unlock.
 
 Unconfirmed leads, tracked in ticket 20260803-034: `vh` reportedly pinning to
 `window.outerHeight`; three new tab modes yielding different `innerHeight`; a

package/docs/layout.md

@@ -269,3 +269,38 @@ You opt in per region; nothing forces a markup shape.
 These are all CSS. Behavior that needs state (resize observers feeding app state,
 virtualization, drag-resizable panels) belongs in your app or a sibling
 `junoui-<framework>` package — not the design system.
+
+## Floating-nav clearance
+
+A scroller that a fixed dock or pillbar floats over reserves room at its foot so
+the last row clears the overlay:
+
+```css
+.my-scroller {
+  padding-block-end: var(--juno-dock-clearance);
+}
+```
+
+The value is **derived from the control it clears**, not a constant:
+
+| Prop                          | Is                                                                                         |
+| ----------------------------- | ------------------------------------------------------------------------------------------ |
+| `--juno-dock-h`               | the floating pill's laid-out height — bubble + item padding + pill padding + border        |
+| `--juno-pillbar-h`            | the pillbar's, one size down (no bubble)                                                   |
+| `--juno-dock-clearance-scale` | multiplier on that height, default `1` — see below                                         |
+| `--juno-dock-clearance`       | `height × scale + space-16 (the bar's own margin) + space-8 + env(safe-area-inset-bottom)` |
+
+**Why derived matters.** Set `--juno-size-tap-comfortable` at `:root` — which
+junoui invites, and which is the whole point of a token — and the pill grows;
+the clearance grows with it. The previous constant did not, and past a 58px
+bubble it reserved less than the pill's own height plus its margin, so content
+hid under the dock with nothing reporting it.
+
+**The scale knob is for bars that shrink while scrolling.** Reserve at the SMALL
+size by setting `--juno-dock-clearance-scale` to your compact factor. Reserving
+at the live size means the reservation changes after the last scroll event, and
+content relayouts under a finger that has already stopped moving.
+
+**Custom properties resolve where they are declared.** Override
+`--juno-size-tap-comfortable` at `:root` (or override `--juno-dock-h` directly);
+overriding it on a subtree does not re-derive a token computed at `:root`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@junoput01/junoui",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "junoui — a token-driven design system. Color carries semantic meaning, never decoration: every hue has one assigned role (NOMINAL / ACTIVE / TARGET / CAUTION / WARNING). Ships multi-platform tokens (CSS, SCSS, JS/TS, JSON, Android, iOS, Flutter) plus a framework-agnostic CSS component layer.",
   "type": "module",
   "license": "MIT",
@@ -49,11 +49,14 @@
     "./ios": "./dist/ios/JunoTokens.swift",
     "./flutter": "./dist/flutter/juno_tokens.dart",
     "./icons": "./dist/icons/juno-icons.svg",
+    "./subset": "./tools/subset-sprite.mjs",
     "./icons/inline": "./dist/icons/inline.js",
+    "./icons/install": "./dist/icons/install.js",
     "./package.json": "./package.json"
   },
   "files": [
     "dist",
+    "tools",
     "src/css",
     "src/icons",
     "src/fonts",
@@ -78,6 +81,7 @@
     "showcase": "npm run build && node scripts/serve.mjs",
     "test:visual": "playwright test",
     "test:visual:update": "playwright test --update-snapshots",
+    "gate:consumer": "node scripts/consumer-gate.mjs",
     "changeset": "changeset",
     "version": "changeset version",
     "release": "npm run build && changeset publish"
@@ -92,5 +96,12 @@
   },
   "engines": {
     "node": ">=18"
-  }
+  },
+  "browserslist": [
+    "iOS >= 17.0",
+    "Safari >= 17.0",
+    "Chrome >= 114",
+    "Edge >= 114",
+    "Firefox >= 125"
+  ]
 }