@junoput01/junoui 0.5.0 → 0.7.0

package/docs/integration.md

@@ -1,6 +1,6 @@
 # Integrating junoui into an app
 
-junoui is **presentational**: tokens + a CSS component layer, zero JS. It dresses a UI
+junoui is **presentational**: tokens + a CSS component layer, no behavioural JS. It dresses a UI
 your app builds. This is the recipe for consuming it cleanly — and the rules for
 extending it without breaking the "one design across all apps" goal.
 
@@ -87,9 +87,55 @@ Do not remap junoui's roles to a brand hue — that erases the shared meaning ac
 Rule of thumb: extend **additively and namespaced**. If every app injects its own palette
 into junoui, the single-design guarantee dies.
 
-## 7. Stateful behavior stays in your app
+## 7. Guarding your class names
 
-junoui ships no JS. Focus traps, list virtualization, popover positioning, data — all
-yours (or a future sibling `junoui-<framework>` package). junoui gives you the stable,
-semantic DOM (real elements, BEM classes, ARIA hooks) to wire behavior + analytics onto;
-see [accessibility.md](./accessibility.md) for the per-component ARIA contract.
+A `juno-*` class name in your source is a string that has to match something in
+junoui's stylesheet, and nothing checks it. When it does not match, nothing
+fails: the file compiles, the tests pass, and the element renders as unstyled UA
+defaults. One consumer shipped eleven such names in a dialog; on a phone the
+result was a confirm button off the bottom of the screen with no way to reach it.
+
+junoui ships the check:
+
+```js
+import { assertJunoClasses } from 'junoui/testing';
+
+it('every juno class this app names exists', () => {
+  assertJunoClasses(['src/**/*.tsx'], {
+    // names YOUR stylesheet defines in the juno- namespace. Each one is a
+    // claim you are making — check it against your own sheet.
+    allowed: ['juno-icons-subset'],
+  });
+});
+```
+
+It reads `junoui/classes.json`, the manifest this build generates from its own
+selectors, so it cannot drift from what you installed. It throws — no framework
+needed — and it throws rather than passing when the globs match no files.
+
+**What it answers:** "junoui ships nothing by this name." **What it does not:**
+whether the class still does what your component assumes. A class that exists
+but was repurposed upstream passes.
+
+The manifest is readable directly (`junoui/classes.json`) for anything else you
+want to assert: `all`, `public` (the documented subset), `roles`, `components`
+grouped BEM-wise, plus the other namespaces junoui ships and a consumer writes
+as bare strings — `tokens`, `keyframes`, `icons`.
+
+```js
+import manifest from 'junoui/classes.json' with { type: 'json' };
+manifest.components.seg; // { block, elements: ['juno-seg__opt'], modifiers: [...] }
+```
+
+## 8. Stateful behavior stays in your app
+
+junoui ships no behavioural JS. Focus traps, scroll locking, gesture handling, list
+virtualization, runtime popover positioning, data — all yours (or a future sibling
+`junoui-<framework>` package). junoui gives you the stable, semantic DOM (real elements,
+BEM classes, ARIA hooks) to wire behavior + analytics onto; see
+[accessibility.md](./accessibility.md) for the per-component ARIA contract.
+
+The only JS in the package is the two icon-sprite helpers, `icons/inline` and
+`icons/install` — see [icon-subsetting.md](./icon-subsetting.md). The full
+does-not-do list for phones and Home-Screen web apps is in
+[ios-pwa.md](./ios-pwa.md).

package/docs/ios-conformance.md

@@ -7,6 +7,13 @@ 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). If you are about to
+integrate and want the bounded version first — what is free, what you supply,
+what junoui does not do — start at [ios-pwa.md](./ios-pwa.md) and come back
+here for the derivations.
+
 > **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 +164,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 +182,385 @@ 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.
+
+## Becoming a Home-Screen web app: the consumer `<head>` contract
+
+Everything in the next section is gated on `display-mode: standalone`. That mode
+is not something junoui can enter for you and not something your CSS decides —
+it is decided in the `<head>`, and now also by the user. So: what makes a page a
+Home-Screen web app at all.
+
+**Two ways in, and as of iOS 26 a third that nobody opts into.**
+
+| Declaration                                                | What it does                                                                         | Source                                                                                                                                                    |
+| ---------------------------------------------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Manifest `"display": "standalone"` (or `"fullscreen"`)     | The standards route: "create a manifest file … and serve it along with your website" | [WebKit — Web Push for Web Apps](https://webkit.org/blog/13878/web-push-for-web-apps-on-ios-and-ipados/)                                                  |
+| `<meta name="apple-mobile-web-app-capable" content="yes">` | Apple extension, iOS only: "Sets whether a web application runs in full-screen mode" | [Apple — Supported Meta Tags](https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariHTMLRef/Articles/MetaTags.html) |
+| **Nothing at all, on iOS/iPadOS 26**                       | "By default, every website added to the Home Screen opens as a web app"              | [WebKit features in Safari 26.0](https://webkit.org/blog/17333/webkit-features-in-safari-26-0/)                                                           |
+
+Ship one of the first two if you _want_ standalone. Ship neither and, from iOS
+26, you may get it anyway:
+
+> "Simply put, there are now zero requirements for 'installability' in Safari."
+> … "If the user prefers to add a bookmark for their browser, they can disable
+> 'Open as Web App' when adding to Home Screen."
+
+Read that second sentence carefully, because it is the part that changes how you
+test: **standalone is now a user choice made at add-to-Home-Screen time, not a
+property of your document.** The same build is both a tab and a web app
+depending on a toggle you never see. Every `display-mode: standalone` rule
+junoui ships — the letterbox unlock below is the whole list — therefore runs for
+consumers who never asked for it, on a device where nothing in their `<head>`
+said "web app".
+
+`window.navigator.standalone` (read-only Boolean, Apple extension) reports the
+answer at runtime; `matchMedia('(display-mode: standalone)')` is the standard
+test and the one junoui's CSS uses. Check both — see
+[the letterbox flag](#the-letterbox-flag-data-juno-letterboxed) for the exact
+predicate.
+
+### The status bar style, and what it is not for
+
+`<meta name="apple-mobile-web-app-status-bar-style" content="…">` takes exactly
+three values, and Apple states it "has no effect unless you first specify
+full-screen mode using `apple-mobile-web-app-capable`":
+
+| Value               | Status bar            | Web content                                             |
+| ------------------- | --------------------- | ------------------------------------------------------- |
+| `default`           | normal                | displayed **below** the status bar                      |
+| `black`             | black background      | displayed **below** the status bar                      |
+| `black-translucent` | black and translucent | **entire screen**, partially obscured by the status bar |
+
+`default` is the default. Only `black-translucent` puts your content under the
+status bar, which is the case where `env(safe-area-inset-top)` stops being
+decorative and starts being the thing keeping your top row readable.
+
+**It is not a letterbox remedy.** `black` and `black-translucent` were each
+tested with a fresh Home-Screen install on the device; both letterbox
+identically (see the next section). Pick the value for the status bar you want
+and nothing else.
+
+- Source: [Apple — Supported Meta Tags](https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariHTMLRef/Articles/MetaTags.html)
+  (archived; carries no deprecation banner, and no replacement page for these
+  two tags was found on the current developer site).
+
+### The `<head>` junoui actually needs
+
+Three lines, in one place, none of which a stylesheet can supply:
+
+```html
+<!-- 1. required always — safe areas are inert without viewport-fit=cover,
+        and 1 CSS px = 1 pt only with width=device-width -->
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+
+<!-- 2. only if you want standalone deliberately; from iOS 26 the user can
+        grant it without you -->
+<meta name="apple-mobile-web-app-capable" content="yes" />
+<!-- or a manifest with "display": "standalone" -->
+
+<!-- 3. if your shell paints before its CSS bundle: an inline copy of the
+        standalone unlock, because iOS samples the document at launch -->
+<style>
+  /* … see "Consumer obligations" below … */
+</style>
+```
+
+Line 1 is expanded, with the failure modes, in
+[getting-started.md](./getting-started.md). Line 3 is the first-parse obligation
+below, and it is the one that is silent both ways: miss it and the app
+letterboxes, ship it and nothing tells you it worked except a screenshot.
+
+## 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.
+
+### The letterbox flag: `data-juno-letterboxed`
+
+The unlock above _prevents_ the letterbox. Nothing above lets a page **react to
+it happening anyway**, and it does happen — to a page whose first-parse copy of
+the unlock is missing, whose `body::after` is taken, or which is not a junoui
+page at all. So junoui fixes the name of that fact, once, here.
+
+**The contract, in four lines:**
+
+|                 |                                                                                                      |
+| --------------- | ---------------------------------------------------------------------------------------------------- |
+| Attribute       | `data-juno-letterboxed`, boolean (present or absent — the value is never read)                       |
+| Element         | the root element, `<html>`                                                                           |
+| Who sets it     | **the app.** junoui ships no JS for this; see below                                                  |
+| What it asserts | this window is in standalone display mode **and** is shorter than the screen it is on. Nothing else. |
+
+**The predicate, so two consumers compute the same answer:**
+
+```js
+const SLACK_PX = 1;
+
+const standalone =
+  matchMedia('(display-mode: standalone)').matches || navigator.standalone === true;
+
+function isLetterboxed({ standalone, innerHeight, screenHeight }) {
+  if (!standalone) return false;
+  if (!screenHeight || !innerHeight) return false; // the browser is not telling us
+  return innerHeight < screenHeight - SLACK_PX;
+}
+```
+
+Each guard earns its place:
+
+- **Standalone is part of the question, not an optimisation.** In a browser tab
+  the window is legitimately shorter than the screen — that is where the
+  toolbars are — and `env(safe-area-inset-*)` reads `0` there anyway, so
+  flagging a tab would be both wrong and pointless.
+- **One pixel of slack**, because the comparison is between two integers from
+  different APIs describing the same screen; an exact test is brittle for no
+  benefit.
+- **A zero guard**, because `screen.height === 0` means the browser is not
+  answering, and "shorter than nothing" is not a verdict.
+
+**Watch it; do not sample it once.** The window corrects itself to the full
+height unprompted, between **6 seconds and 43 minutes** after navigation, and
+then holds for the life of that document. Re-evaluate on
+`visualViewport.resize` — the event that fired for all seven observed
+corrections — plus `window.resize` and `orientationchange`, because rotation
+changes both dimensions and only the latter is guaranteed to report it.
+
+**What CSS may key off it — one thing.** Inside the 812 px window
+`env(safe-area-inset-bottom)` still reports **34**, but the home indicator is at
+screen y 840–874, _outside_ the window. A layout that correctly honours the
+inset is reserving room for something that is not in the view, on an edge
+already 62 px clear of the glass. So the sanctioned use is to zero the bottom
+inset, and only the bottom inset:
+
+```css
+:root {
+  --app-safe-bottom: env(safe-area-inset-bottom, 0px);
+}
+html[data-juno-letterboxed] {
+  --app-safe-bottom: 0px;
+}
+```
+
+Do **not** key the top inset off it, and do not use it to disable the unlock.
+The 62 px top strip is genuinely reserved by the window manager; only the bottom
+inset is a phantom.
+
+**What junoui does with it today: nothing, and that is deliberate.** junoui's
+own clearances and the nine other `env(safe-area-inset-bottom)` call sites read
+the raw `env()` — eleven in all, across `base.css` (2), `dock.css` (3),
+`pillbar.css` (3), `modal.css`, `drawer.css` and `toast.css` — so a junoui app
+in a letterboxed window over-reserves at the bottom regardless of what the app
+sets: an `env()` inside a component's `calc()` is not overridable from app CSS.
+Fixing that means routing every bottom call site through a single
+`--juno-safe-bottom` indirection, which is a CSS change across six files with a
+visual-regression pass of its own. It is tracked as
+ticket 20260815-039, and doing it by halves is worse than not doing it: convert
+the clearance tokens but not `dock.css`'s margin and the bar moves while its
+clearance does not.
+
+**Why no junoui JS module.** junoui already ships two JS entry points
+(`icons/inline`, `icons/install`), so a third would not be unprecedented. It is
+still wrong here: the module is ~30 lines with no junoui-specific content — it
+reads two DOM globals and writes an attribute — and shipping it would put a
+workaround into the public API, with a semver commitment, a release, and a test,
+for a defect whose entire purpose is to be deleted when WebKit fixes the window.
+A **name** costs nothing and is free to delete. Re-open this decision if the
+flag ever gates junoui's own CSS (20260815-039): a rule junoui ships with no
+supported way to satisfy it would be worse than either half alone.
+
+**It is not an upstream-fix detector.** The test in the previous section needs a
+document that _cannot_ scroll; the unlock makes the document scroll, so a
+correctly integrated junoui app reads `false` while the bug is very much alive.
+The flag catches residual cases, not the platform.
+
+**Prior art, and why the name is fixed now rather than later.** nexora sets
+`data-nx-letterboxed` from `web/src/letterbox.ts` — that module's predicate is
+the one reproduced above, and it predates this contract. New consumers use
+`data-juno-letterboxed`. The cost of leaving it unnamed is that the next
+consumer invents a third spelling for the same fact and none of the three CSS
+rules can ever move into junoui.
+
+- 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 +579,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 +607,13 @@ 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. What that means for
+your `<head>` is
+[the consumer contract above](#becoming-a-home-screen-web-app-the-consumer-head-contract);
+the concrete consequence is measured 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