@junoput01/junoui 0.5.0 → 0.7.0

package/docs/accessibility.md

@@ -115,6 +115,12 @@ tokens land, and never removes a guarantee without a semver-major note.
   base layer raises `--juno-size-tap-min` to the comfortable 44px, so every
   control sized off the tap minimum grows on touch devices. A cascade override —
   the token values themselves don't change.
+- **One control grows on one axis only.** `.juno-pagination`'s items read the tap
+  minimum for `min-inline-size` but carry a fixed `block-size` of 32px, so on a
+  coarse pointer they are 44 × 32 — above the 24px AA floor, below the 44px
+  enhanced one. Tracked as ticket 20260815-040; the numeric coarse-pointer check
+  in `test/visual/tap-targets.spec.mjs` does not cover pagination yet, which is
+  why it went unnoticed.
 - Hover-revealed affordances get a touch fallback: table row actions stay
   visible under `@media (hover: none)`.
 

package/docs/browser-support.md

@@ -0,0 +1,176 @@
+# 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-pwa.md](./ios-pwa.md) — the five-minute version for a consumer about to
+  integrate: what these floors buy you, what you must ship yourself, and what
+  junoui does not do at all.
+- [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/components/button.md

@@ -14,6 +14,7 @@
 | `.juno-btn`        | Base. Primary (filled): background = role, text = `s0`. Default role = `active`. |
 | `.juno-btn--ghost` | Transparent, `data` text, `border` outline; hover → `s2`.                        |
 | `.juno-btn--sm`    | Dense-toolbar size: `font.size.11`, `space.4` × `space.10`, `radius.3`.          |
+| `.juno-btn--dense` | On `--sm` only: keeps the 24px height on touch as well. Opt out by name.         |
 | `.juno--<role>`    | Sets the primary fill color.                                                     |
 | `:disabled`        | `muted` fill, `label` text, not-allowed.                                         |
 
@@ -28,5 +29,13 @@
 - Primary action filled with `nominal` (confirm) or `active` (apply).
 - `warning` fill only for genuinely critical/destructive actions.
 - One primary per group; everything else is ghost.
-- `--sm` drops below the WCAG tap-minimum on purpose — it is for dense **desktop**
-  toolbars (40–46px chrome bars). Keep the default size anywhere touch is expected.
+- `--sm` is a **density**, not a semantic. It is for dense desktop toolbars
+  (40–46px chrome bars): 24px on a fine pointer, the WCAG 2.2 AA floor (2.5.8)
+  exactly. On a **coarse pointer it promotes to `size.tap.min`** — type and
+  padding still shrink, but the tap target does not. Reaching for `--sm` to mean
+  "secondary" is the common mistake; `--ghost` is the secondary modifier and
+  stands alone at full size.
+- `.juno-btn--dense` opts a `--sm` button back out of that promotion, for a
+  toolbar that is genuinely dense on touch (a scrubber, an editor rail). It does
+  nothing without `--sm`, on purpose: a dense touch target should be chosen by
+  name, never inherited from a size.

package/docs/components/dock.md

@@ -187,6 +187,40 @@ over scroll-event discretization — anything longer visibly lags the finger.
   plus the pill's padding and border), `--juno-dock-edge-gap` (what the
   floating margins take from `100%` — default `2 × space.12`).
 
+## How many items fit
+
+`.juno-dock__item` is `flex: 1 1 0`, so the bar divides its inner width by
+however many items are present. A consumer deciding **how many to render** — and
+whether they still hold a tap target — reads that budget from junoui rather than
+re-deriving it from the numbers in `dock.css`:
+
+| Custom property             | What it is                                                                                                            |
+| --------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `--juno-dock-items`         | The item budget. **You set it** to what you render; junoui does not enforce it, it derives from it.                   |
+| `--juno-dock-item-inline`   | The width one item gets. A prediction of what the flex layout produces — asserted against the measured box in CI.     |
+| `--juno-dock-fit-inline`    | The narrowest viewport at which every item still holds `--juno-size-tap-comfortable`. Below it, drop an item.         |
+| `--juno-dock-chrome-inline` | The bar's total inline chrome (margin + padding + border, both sides). `0` on the full-bleed bar, `34px` on the pill. |
+| `--juno-dock-avail`         | The width the budget divides. Defaults to `100vw`; override it when the bar is not viewport-wide.                     |
+
+```css
+/* five destinations need 254px; below that, render four */
+@media (max-width: 253px) {
+  .my-dock__item--secondary {
+    display: none;
+  }
+}
+```
+
+The margin, padding and border terms are declared **once** and consumed by both
+the variant's own box and the sum above, so the budget cannot disagree with the
+bar it describes — the same construction as `--juno-dock-edge-offset`.
+
+**There is deliberately no scale floor.** "What scale keeps a 44px target?" is
+`44px / --juno-dock-item-inline`, a ratio of two lengths, and CSS cannot divide
+by a length. A consumer that must scale rather than drop compares those two
+values itself. Prefer dropping an item: scaling a bar scales its hit areas with
+it, which is the problem the floor was being computed to avoid.
+
 ## Anatomy (any platform)
 
 - Full-width bar on `s1`, hairline seam on the block-start edge; items split the

package/docs/components/fold-slot.md

@@ -10,7 +10,7 @@ coming in, end-of-fade going out). Keep the element mounted; flip
 
 ```html
 <div class="juno-pillbar">
-  <button class="juno-fold" data-juno-in aria-label="Scroll to top">
+  <button class="juno-fold juno-pillbar__item" data-juno-in aria-label="Scroll to top">
     <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-arrow-up" /></svg>
   </button>
   …other members…
@@ -24,6 +24,31 @@ coming in, end-of-fade going out). Keep the element mounted; flip
 | `--juno-fold-size` | The slot's open width (default `size.tap.comfortable`) — must be definite, transitions cannot run to an intrinsic size.         |
 | `--juno-fold-gap`  | The row's flex/grid gap (default `0px`) — the folded slot swallows one gap with a negative margin so the row closes completely. |
 
+## Composing it with a component class
+
+The canonical use puts `.juno-fold` on an element that already carries a
+component class — `.juno-pillbar__item`, `.juno-btn`, `.juno-chip` — because that
+is where the capsule chrome (tap target, padding, hover, focus ring,
+`aria-pressed`) lives. The fold is built for that, and two things about it are
+worth knowing rather than rediscovering:
+
+**Which floors it releases.** A border-box inline size has exactly three inputs
+that can hold it above zero, and the folded state releases all three:
+`min-inline-size` (a component's tap floor), `padding-inline`, and
+`border-inline-width`. Each is in the fold's transition list too, so the content
+neither snaps sideways as the fold starts nor jumps to full width when the slot
+opens. Composed with `.juno-pillbar__item` and none of them released, the folded
+slot lays out at 44px — the tap target — and the row never closes.
+
+**It takes over the element's `transition`.** `transition` is a shorthand: two
+rules setting it do not merge, the winner replaces the loser's whole list. The
+fold's declarations are stated at attribute specificity so it wins that, and its
+list therefore also carries the chrome properties (`color`, `background-color`)
+the components animate — composing costs the capsule nothing. A component of your
+own that composes with `.juno-fold` and needs a third property transitioned
+should state it at higher specificity than `.juno-fold[data-juno-in]` (0,2,0),
+repeating the fold's own entries, or the fold's list wins and yours is dropped.
+
 - The row's own width follows the slot, so the whole row slides open/closed.
 - `prefers-reduced-motion`: handled by the base layer (states still apply,
   transition durations collapse).

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,42 @@ 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 |
+| ------------------------------------------- | ------------ | ------------- | ------- |
+| **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).
+
+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/icon-subsetting.md

@@ -57,3 +57,32 @@ const iconSubset = {
 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`.