@junoput01/junoui 0.6.0 → 0.7.0

package/docs/conformance-kit.md

@@ -0,0 +1,243 @@
+# The conformance kit — design
+
+> **Status:** design, for review. Nothing here is implemented except where a
+> section says "already shipped".
+> **Ticket:** 20260826-036. **Owner:** iosdev.
+
+## The problem, stated from evidence
+
+junoui is consumed by an app that then has to re-derive junoui's own facts to
+use it safely. One week of auditing a single consumer (nexora) produced this
+list, and every item is a thing the consumer had to build because the library
+did not ship it:
+
+| What the consumer built                             | Because junoui did not ship                         |
+| --------------------------------------------------- | --------------------------------------------------- |
+| `junoClasses.ts` + a class-name test                | any statement of which class names exist            |
+| a cascade resolver (`cssCascade.ts`)                | a way to ask what a property resolves to            |
+| `toppill_fit_verify.py`, `measure_mobile_chrome.py` | a way to measure a layout claim on a device profile |
+| a three-bucket `env()` discipline, in prose         | a rule for who adds the safe-area inset             |
+| `--nx-dock-clear` and the 320px arithmetic          | a published item budget                             |
+| local tap floors on four controls                   | floors on the primitives those controls imitate     |
+
+Two things make this worse than duplication.
+
+**The consumer's copy drifts, silently and in the safe direction.** The dock
+arithmetic subtracted 12px of inline padding where the pill spends 8, so every
+per-item width was ~0.8px low for months. Nothing was visibly wrong. The number
+was simply not the library's number any more.
+
+**The library's own defects survive because nobody can see them from inside.**
+`.juno-seg__option` sat in a `touch-action` list for as long as it existed; the
+shipped class is `.juno-seg__opt`. `:where()` matched nothing, the rule parsed,
+every other member kept working. One character, invisible to lint, to the
+build, and to a screenshot. `.juno-list__item` was the same defect in the same
+two lists. Both were found this week by a test written for the first one.
+
+The kit's thesis: **mobile correctness is a library concern, and the library
+should be able to prove its own claims.**
+
+## Design principles
+
+1. **A fact is published once and derived everywhere else.** If a consumer can
+   compute a number from junoui's geometry, junoui computes it and exports it.
+   `--juno-dock-edge-offset` is the shape: one declaration feeding both the
+   margin that paints and the clearance that reserves.
+2. **A name is generated, never typed twice.** Every list of junoui class names
+   inside junoui — `:where()` sets, docs tables, the manifest — comes from one
+   source. The `__option`/`__opt` class of defect stops being expressible.
+3. **A guard measures the artifact it is about.** Against the built bundle,
+   through a layout engine where used values matter, with a control proving the
+   measurement can register the defect. Stated as a rule because this kit's own
+   first test failed it: see [Anti-goals](#anti-goals).
+4. **The library ships the instrument, not just the answer.** A consumer that
+   can only read junoui's numbers still cannot check its own composition. The
+   doctor (F) exists so the answer is reproducible outside this repo.
+
+## A. Class contract shipped
+
+**Ship** `dist/classes.json`, generated by `scripts/bundle-css.mjs` from the
+selectors it already parses:
+
+```json
+{
+  "version": "0.7.0",
+  "components": {
+    "seg": { "block": "juno-seg", "elements": ["juno-seg__opt"], "modifiers": ["juno-seg--sm"] }
+  },
+  "all": ["juno-seg", "juno-seg__opt", "..."]
+}
+```
+
+**Ship** `junoui/testing`, a framework-agnostic helper:
+
+```js
+import { assertJunoClasses } from 'junoui/testing';
+assertJunoClasses(['src/**/*.tsx']); // throws listing every juno-* class no rule defines
+```
+
+Generalizes nexora's `junoClasses.ts`, which caught 11 misspelled BEM names
+that compiled silently and broke actions on phones.
+
+**Shipped**, with two revisions the implementation forced. Both came from
+running the helper against a real consumer rather than from taste.
+
+**The helper checks `all` by default, not `public`.** Measured on the 0.7.0
+build: 310 classes have rules, 277 are named anywhere in `docs/`. The 33-name
+difference is not an internals list — it is `juno-sr-only`, `juno-bg-s0`,
+`juno-hide-below-lg`, `juno-eyebrow` and friends: public utilities nobody wrote
+up. Defaulting to `public` would have failed consumers for using shipped API.
+`public` stays available as a stricter surface, and the docs gap is junoui's to
+close, tracked separately.
+
+**The claim is "junoui ships nothing by this name", not "this is not a class".**
+A consumer writes `junoPx('juno-pillbar-gap')` and `` `#juno-i-${n}` ``, and no
+regex over source text distinguishes those from a class. First run against
+nexora reported 24 names; 8 were tokens, an icon-id template and a keyframe —
+all names junoui does ship. So the manifest carries `tokens`, `keyframes` and
+`icons` alongside the classes, and component-local custom properties are read
+from the **bundle**, not only `juno-tokens.css` (that alone accounted for three
+of the eight).
+
+Final state on nexora's 133 source files: the only reports are 13 in the fixture
+file that deliberately names wrong classes, and 3 consumer-owned names.
+
+## B. Tap floors owned by the library
+
+**Already shipped**, this week, and the evidence for the rest of the section:
+`.juno-seg__opt` had no floor at all and computed 25.39px (20260826-025);
+`.juno-btn--sm` shipped a 24px target that 40 consumer call sites used to mean
+"secondary" (20260826-026).
+
+**Remaining work:**
+
+1. **Audit every interactive primitive** for a coarse-pointer floor and record
+   the result in one table, in the repo, generated by the doctor rather than
+   written by hand. Anything that cannot hold 44 states why in that table.
+2. **Generate the `touch-action` and tap-highlight `:where()` lists from the
+   class manifest.** Today they are two hand-maintained lists that had drifted
+   from the classes _and from each other_ — the tap-highlight set is a strict
+   subset of the touch-action set, and nothing says whether that is deliberate.
+   Generated, the typo class of defect cannot exist and the divergence becomes
+   a visible decision.
+
+**Open question for review:** the two lists should probably become one set with
+a per-property opt-out, but "which primitives want `manipulation`" and "which
+want the highlight killed" may genuinely differ. Needs a decision, not a merge.
+
+## C. Pointer-first responsiveness
+
+**The defect:** a landscape iPhone is 844×390. It is wider than `md`, so a
+width-keyed rail serves it the desktop rail on every screen, on a device held
+in two hands. Width has never been the question.
+
+**Ship one blessed mechanism**, and use it in junoui's own CSS so it cannot be
+advisory:
+
+```css
+/* the coarse-pointer condition, stated once */
+@media (pointer: coarse) { ... }
+```
+
+CSS has no portable way to name a media query (`@custom-media` is a draft and
+junoui runs no PostCSS), so the honest form is: **junoui's CSS writes the
+literal, and the string is exported for JS**, with a test asserting the two
+agree.
+
+```js
+import { COARSE_POINTER, useCoarsePointer } from 'junoui/testing'; // name TBD
+```
+
+Key `rail--responsive`, the modal→sheet swap, and `density: auto` on it.
+
+**Open question for review:** whether the condition is `(pointer: coarse)` or
+`(pointer: coarse) and (max-height: …)`. A coarse-pointer 27" kiosk is a real
+device and wants the rail. Nexora already ships a JS-side coarse branch in
+Settings; that call site is the place to look before deciding.
+
+## D. Safe-area discipline in the library
+
+Adopt nexora's three-bucket `env()` doc verbatim — it is the clearest statement
+of this that exists in either repo, and junoui's own triage is missing its
+third bucket:
+
+| Bucket              | Rule               | Because                                                            |
+| ------------------- | ------------------ | ------------------------------------------------------------------ |
+| **edge padding**    | `max(base, env())` | content already inside the box; the inset replaces the gap         |
+| **clearance**       | `base + env()`     | the chrome's offset already contains the inset; reserve must match |
+| **floating chrome** | `base + env()`     | a floating element sits off the edge; gap and inset stack          |
+
+Then: **every floating-chrome primitive applies its own bucket** — `.juno-toast`,
+`.juno-pillbar`, `.juno-dock` — through a token the consumer can restate, which
+`--juno-dock-edge-offset` already demonstrates. Extends the xreqs filed as
+20260803-037 and 20260815-053.
+
+## E. Published budgets
+
+**Already shipped** for the dock (20260826-027): `--juno-dock-items`,
+`--juno-dock-item-inline`, `--juno-dock-fit-inline`, `--juno-dock-chrome-inline`,
+`--juno-dock-avail`, with the terms declared once and consumed by both the box
+and the sum.
+
+**Remaining:** the same treatment for `.juno-pillbar`, which publishes
+`--juno-pillbar-item/-gap/-pad` but no derived budget, so a consumer's capacity
+planner still does the division itself.
+
+**Recorded limit, so nobody re-opens it:** junoui cannot publish a _scale_
+floor. "What scale keeps a 44px target?" is `44px / item-width`, a ratio of two
+lengths, and CSS cannot divide by a length. The library publishes the two
+lengths; a consumer that must scale rather than drop compares them.
+
+## F. junoui doctor
+
+A runnable conformance probe a consumer executes against **its own** build:
+
+```sh
+npx junoui doctor --url http://localhost:5173 --profiles phone,phone-landscape
+```
+
+Checks, generalized from nexora's `toppill_fit_verify.py` and
+`measure_mobile_chrome.py`:
+
+- every element matching a `public` manifest class holds its tap floor
+- both orientations, because landscape is where the width assumption fails
+- no horizontal overflow at 320px
+- floating chrome clears the safe area, per bucket
+- a consumer class does not out-resolve a junoui declaration it did not mean to
+
+Reports as a table, exits non-zero, and prints what it did **not** cover.
+
+## Anti-goals
+
+**No advisory rules.** Anything in G that the doctor cannot check is a
+checklist item a reader will skip. Prefer fewer checks that run.
+
+**No guard that has not been shown to fail.** This kit's own first tap-target
+test passed with the fix deleted: it asserted against a showcase page, and
+something in that page already held the height, so it could not fail. Measured:
+24px off the bundle, 44px off `/showcase/buttons.html`, same markup, same
+emulation (20260826-030, cause still unidentified). Every check the doctor
+ships must be mutation-tested against a reintroduced defect before it counts.
+
+**No release gate that proves less than it claims.** `gate:consumer` reported
+GREEN twice against a consumer checkout 260 commits behind its own develop —
+the guard that would have failed did not exist on that branch (20260826-039).
+
+## Sequencing
+
+| Slice | Contents                                     | Depends on |
+| ----- | -------------------------------------------- | ---------- |
+| ~~1~~ | ~~A (manifest + helper)~~ — **shipped**      | —          |
+| 2     | B2 (generate the `:where()` lists)           | 1          |
+| 3     | C (one pointer-first mechanism)              | —          |
+| 4     | D (buckets + floating chrome owns its inset) | 3          |
+| 5     | E (pillbar budget)                           | —          |
+| 6     | F (doctor)                                   | 1, 3       |
+| 7     | G (checklist, reduced to what F checks)      | 6          |
+
+Slice 1, B1 and E-for-dock are done. 024–027 are absorbed and closed.
+
+**Review asks:** the three open questions above (A's public subset, B's two
+lists, C's condition), and whether slice 6 is worth its cost before slice 1
+lands — the doctor is the piece a consumer feels, and slices 1–5 are the pieces
+that stop the defects existing.

package/docs/getting-started.md

@@ -48,6 +48,16 @@ Two things depend on it, and both fail **silently**:
 
 Details and sources: [ios-conformance.md](./ios-conformance.md).
 
+### If the page can end up on a Home Screen
+
+From iOS/iPadOS 26 that is every page — "there are now zero requirements for
+'installability'", and the user decides with an **Open as Web App** toggle when
+they add it. So junoui's `display-mode: standalone` rules can run on a site that
+never opted in. What to declare (or knowingly not declare), which status-bar
+style does what, and the one stylesheet copy that must be inline in the `<head>`
+rather than in your bundle:
+[the consumer `<head>` contract](./ios-conformance.md#becoming-a-home-screen-web-app-the-consumer-head-contract).
+
 ## Browser support
 
 |                                             | Safari / iOS | Chrome / Edge | Firefox |
@@ -70,6 +80,10 @@ autoprefixer of its own; the field is there for your build tooling.
 understand without reporting anything. The full audit, per feature, with the
 degrade-vs-break verdict: [browser-support.md](./browser-support.md).
 
+Shipping to a phone or a Home Screen? [ios-pwa.md](./ios-pwa.md) is the
+five-minute version — what junoui gives you, the eight things you must supply,
+and what it does not do at all.
+
 ## The model
 
 - **Palette** — `standard` · `colorblind` · `soft`

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

@@ -9,7 +9,10 @@ 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).
+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 —
@@ -269,6 +272,93 @@ that has a scrollbar. Every call site above either caps well below `100vw`
 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
@@ -358,6 +448,111 @@ 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
@@ -412,8 +607,10 @@ 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. The concrete
-consequence is measured above 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.