npm - @junoput01/junoui - Versions diffs - 0.6.0 → 0.8.0 - Mend

@junoput01/junoui 0.6.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (42) hide show

package/CHANGELOG.md +209 -0
package/README.md +17 -16
package/dist/android/dimens.xml +2 -0
package/dist/classes.json +1774 -0
package/dist/css/juno-tokens.css +10 -0
package/dist/css/juno.css +1057 -56
package/dist/flutter/juno_tokens.dart +10 -0
package/dist/ios/JunoTokens.swift +10 -0
package/dist/js/tokens.js +16 -0
package/dist/json/tokens.json +51 -0
package/dist/rust/juno_tokens.rs +383 -0
package/dist/scss/_juno-tokens.scss +10 -0
package/docs/accessibility.md +6 -0
package/docs/browser-support.md +3 -0
package/docs/components/button.md +11 -2
package/docs/components/canvas-ink.md +71 -0
package/docs/components/dock.md +34 -0
package/docs/components/fold-slot.md +26 -1
package/docs/components/gizmo.md +114 -0
package/docs/components/swatch.md +95 -0
package/docs/components/tree.md +112 -0
package/docs/conformance-kit.md +255 -0
package/docs/getting-started.md +14 -0
package/docs/integration.md +52 -6
package/docs/ios-conformance.md +200 -3
package/docs/ios-pwa.md +273 -0
package/docs/native.md +38 -1
package/docs/tokens-reference.md +15 -0
package/package.json +8 -2
package/src/css/base.css +35 -43
package/src/css/components/button.css +42 -2
package/src/css/components/canvas-ink.css +97 -0
package/src/css/components/dock.css +65 -6
package/src/css/components/fold-slot.css +49 -3
package/src/css/components/gizmo.css +238 -0
package/src/css/components/segmented.css +15 -2
package/src/css/components/swatch.css +187 -0
package/src/css/components/tree.css +259 -0
package/src/css/touch-surfaces.mjs +95 -0
package/tools/gizmo.mjs +144 -0
package/tools/testing.mjs +177 -0
package/tools/tree.mjs +178 -0

package/docs/getting-started.md CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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.

package/docs/ios-pwa.md ADDED Viewed

@@ -0,0 +1,273 @@
+# junoui on iOS, and in a Home-Screen web app
+The bounded claim, in one page: **what you get for free, what you must supply,
+and what junoui explicitly does not do.** Read it before integrating; the pages
+it links carry the detail and the derivations.
+Every line here carries a number or a source. Where a claim has neither, it is
+not on this page.
+**What the numbers were measured against.** junoui **v0.5.0**; the CSS feature
+audit is against the built `dist/css/juno.css` on **2026-08-15**; the device
+readings are an **iPhone 16 Pro (402×874 pt), iOS 18.7 / Safari 26.6**; the
+touch-ergonomics assertions run in Playwright at **390×844** with `hasTouch` +
+`isMobile`. One device, one build. Nothing here is extrapolated to iPads or to
+Android.
+---
+## The floor
+|                                                       | Safari / iOS | What that line means                                |
+| ----------------------------------------------------- | ------------ | --------------------------------------------------- |
+| **Hard floor** — below this, things break             | **17.0**     | the Popover API. Overlays stop being overlays       |
+| **Supported floor** — put this in your support matrix | **17.5**     | everything works; entry animations missing below it |
+| **Full fidelity**                                     | **26.0**     | CSS anchor positioning                              |
+**The interesting gap is 17.5 → 26.0, not 16.x → 17.5.** Between 17.5 and 26.0
+menus, popovers and tooltips open, close and light-dismiss correctly — and land
+at their **static position** instead of beside their trigger, because
+`position-area` / `position-try-fallbacks` / `position-anchor` (**10 uses**) are
+Safari 26. The surface works; it is in the wrong place. That is a real visual
+defect and it is easy to mistake for a break.
+Below **17.0** the Popover API is absent and junoui **hides** `.juno-menu`,
+`.juno-popover` and the top-layer tooltip behind
+`@supports not selector(:popover-open)`. That is not a fix. Unguarded, the UA
+rule that hides a closed popover does not exist either, so a **256–280 px
+invisible fixed panel** sits at its static position swallowing taps on whatever
+it covers. junoui trades that for "the panel is absent" — absent beats
+invisibly-present — and your app branches on
+`CSS.supports('selector(:popover-open)')`.
+Full per-feature audit, with the degrade-or-break verdict for all 15 features:
+[browser-support.md](./browser-support.md).
+---
+## What you get for free
+### Touch ergonomics
+- **44 px tap targets on coarse pointers.** `--juno-size-tap-min` is **24 px**
+  (the WCAG 2.2 **2.5.8** AA floor) and flips to `--juno-size-tap-comfortable` =
+  **44 px** under `@media (pointer: coarse)`. Everything that sizes off it
+  inherits the promotion: `.juno-btn` (`min-height`), `.juno-input` and
+  `textarea` (`min-block-size`, the latter at 3×), `.juno-menu__item`,
+  `.juno-navbar__actions > *`, and `.juno-modal__close` on both axes.
+  **One exception, stated so you can size around it:** `.juno-pagination`'s
+  items take the promotion on the **inline** axis only — their `block-size` is a
+  fixed `--juno-space-32`, so they are 44 × 32 on touch. That clears the 24 px
+  AA floor and not the 44 px comfortable one (ticket 20260815-040).
+- **Verified numerically, not by screenshot.**
+  `test/visual/tap-targets.spec.mjs` asserts the computed `min-height` **and**
+  the rendered box under **both** Playwright projects — `44px` under
+  `chromium-coarse`, `24px` under `chromium`. Keying the expectation by project
+  is what makes it a check rather than a baseline: if the coarse project ever
+  stops emulating touch it starts producing desktop numbers and **fails**
+  instead of quietly re-recording them.
+- **A 16 px floor on text entry**, so iOS Safari does not zoom the page onto a
+  focused field: `.juno-input { font-size: max(16px, …) }`. Two caveats, both
+  load-bearing. **No primary WebKit or Apple source states the zoom behaviour** —
+  it is empirical, and the mitigation is kept because it is harmless, not
+  because it is documented. And it **never applied on any touch device until
+  2026-08-15**: the rule sat in `base.css`'s `@media (pointer: coarse)` block,
+  where a media query adds no specificity, so `input.css`'s own `.juno-input`
+  font-size beat it on source order. The numeric check above is what found it.
+- **The UA tap-highlight square is off** on `.juno-btn`, `.juno-dock__item`,
+  `.juno-pillbar__item`, `.juno-tabs__tab`, `.juno-list__item`,
+  `.juno-menu__item`. Community convention — **no Apple source** — so it is
+  listed as a default, not a conformance claim.
+### Safe areas
+`env(safe-area-inset-*)` is used **21 times across 8 files**, and the rule for
+which arithmetic applies is not one rule but **three buckets**:
+| Bucket                                         | Arithmetic                                       | Why                                                          |
+| ---------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------ |
+| Padding on a surface that reaches the edge     | `max(baseline, env(…))` — the inset **replaces** | the inset's job is to clear the cutout, not to stack         |
+| A floating element positioned **off** the edge | `calc(baseline + env(…))` — **additive**         | `max()` would park the pill flush against the home indicator |
+| The clearance tokens                           | `calc(height + … + env(…))` — **additive**       | content must clear the control's height _and_ the inset      |
+Get this wrong in either direction and nothing errors. The derivation, with the
+WebKit source: [ios-conformance.md](./ios-conformance.md#max-vs-addition--the-rule).
+**All of it is inert until you ship `viewport-fit=cover`** — WebKit reports
+every inset as `0` until then, and `contain` does not opt out. See
+[what you must supply](#what-you-must-supply).
+### Floating-nav clearance, derived rather than constant
+A page under a floating dock or pillbar reserves room at its foot with
+`padding-block-end: var(--juno-dock-clearance)`. Those tokens are **computed
+from the bar's own parts**, not hardcoded:
+```
+--juno-dock-h     = tap-comfortable + 4×space-4 + 2×border-1   = 62px at defaults
+--juno-pillbar-h  = tap-comfortable + 2×space-4 + 2×border-1   = 54px at defaults
+--juno-dock-clearance    = dock-h    × scale + 16 + 8 + env(safe-area-inset-bottom)
+--juno-pillbar-clearance = pillbar-h × scale + 16 + 8 + env(safe-area-inset-bottom)
+```
+— 86 px and 78 px plus the inset, at default tokens. **Why derived matters:**
+the old constants (`space-72 + space-20 + env()`) promised in a code comment to
+"stay correct when the dock geometry changes" and could not. junoui explicitly
+invites you to re-parameterise the bubble via `--juno-size-tap-comfortable`, and
+past a **58 px** bubble the constant reserved **less** than the pill's own
+height plus its margin — content hid under the dock, silently, on exactly the
+consumers who took the invitation (ticket 20260815-026).
+`--juno-dock-clearance-scale` (default `1`) is the knob for a bar that **shrinks
+while scrolling**: set it to the shrunken ratio so the reservation is made at
+the small size. Reserving against a live height means relayouting content under
+a finger that has already stopped moving.
+### The Home-Screen standalone unlock
+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 **874 − 812 = 62**, a
+black strip at the bottom of the glass on every screen. `base.css` keeps the
+document scrollable behind your fixed shell with an invisible `body::after`
+spacer, behind a **three-condition gate, all required**:
+```
+@media (display-mode: standalone)   only installed apps letterbox
+  and (pointer: coarse)             keeps macOS Dock apps out
+@supports (-webkit-touch-callout: none)   iOS/iPadOS WebKit only
+```
+**A bundled stylesheet cannot satisfy the obligation this creates** — see
+[what you must supply](#what-you-must-supply). The measurements, the
+four-structure A/B, and the 201 device readings behind it:
+[ios-conformance.md](./ios-conformance.md#home-screen-standalone-the-letterbox-and-why-basecss-unlocks-it).
+### Phone-shaped component behaviour
+| Behaviour                                                               | Triggered by                                                    |
+| ----------------------------------------------------------------------- | --------------------------------------------------------------- |
+| Modal becomes a bottom sheet — full width, bottom-anchored, `85dvh` cap | `@media (width <= 639.98px)`                                    |
+| Toast stack goes full width at the bottom edge and slides up            | `@media (width <= 639.98px)`                                    |
+| Table stacks into rows                                                  | `@container (max-width: 480px)`                                 |
+| Tab strip scrolls sideways instead of wrapping                          | `overflow: auto hidden` + `overscroll-behavior-inline: contain` |
+Note the third row is a **container** query, not a viewport one: it reflows by
+the space the table is in, not by the size of the phone. And the first is
+deliberately _not_ — a modal is always in the top layer, so the screen **is**
+its container.
+### Silent-failure guards already paid for
+Two defects of this class shipped and were found by looking at a phone, not by
+any tool — both fixed 2026-08-05, both now permanent:
+- `-webkit-backdrop-filter` ships beside **all 7** unprefixed
+  `backdrop-filter` declarations (unsupported below Safari 18.0 — every glass
+  surface rendered flat on iOS 17).
+- A `::-webkit-scrollbar { display: none }` companion ships beside **all 3**
+  `scrollbar-width` declarations (unsupported below Safari 18.2 — the
+  scrollable tab strip kept a visible scrollbar on iOS 17 through 18.1).
+> Both are 7 and 3 **declarations**, verified in `dist/css/juno.css`. The audit
+> table in [browser-support.md](./browser-support.md) reports 14 and 4 because
+> it counts string occurrences, and `-webkit-backdrop-filter` contains
+> `backdrop-filter` — so each guarded pair is counted twice. Same fact, two
+> units.
+And **zero raw `vh`** — grep the bundle and there are none. Full-height surfaces
+use `dvh` (**9 uses**) because `vh == lvh` normatively and a `100vh` box is
+sized as if the toolbar were retracted; the single `lvh` in the bundle is the
+standalone unlock's spacer, which is _supposed_ to overflow. The reasoning, and
+the rule for a component that does not exist yet:
+[ios-conformance.md](./ios-conformance.md#the-rule-for-a-component-that-does-not-exist-yet).
+---
+## What you must supply
+junoui is a stylesheet. Everything below is outside what CSS can reach.
+| #   | You ship                                                                                                                   | If you don't                                                                                                  |
+| --- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| 1   | `<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">`                                 | every safe-area guarantee becomes a no-op, silently; and 1 CSS px stops equalling 1 pt                        |
+| 2   | A standalone declaration — manifest `"display": "standalone"` or `apple-mobile-web-app-capable` — **or a decision not to** | from iOS 26 the **user** grants standalone at add-to-Home-Screen time and junoui's standalone CSS runs anyway |
+| 3   | **An inline copy of the letterbox unlock in `<head>`**, if your shell paints before its CSS bundle                         | iOS samples the document at launch; `juno.css` arrives after, so the app letterboxes with the unlock present  |
+| 4   | Leave `body::after` alone, or reproduce the spacer at the same gate                                                        | the unlock has no spacer and the window letterboxes                                                           |
+| 5   | `overscroll-behavior: contain` on your real scrollers                                                                      | an inner fling chains into the unlock's ghost scroller                                                        |
+| 6   | A popover fallback below Safari 17.0, branched on `CSS.supports('selector(:popover-open)')`                                | overflow navigation is unreachable — junoui hid the panel rather than leave it eating taps                    |
+| 7   | Pinning `inset` on the `toggle` event below Safari 26.0                                                                    | anchored surfaces open at their static position                                                               |
+| 8   | `data-juno-letterboxed` on `<html>`, if you want to react to a letterboxed window                                          | nothing; the flag is opt-in — but invent your own attribute name and your CSS can never move into junoui      |
+**#3 is the one that catches people**, because it is silent in both directions:
+miss it and the app letterboxes with a correct stylesheet installed, ship it and
+nothing confirms it worked except a screenshot of the device. Rows 2, 3 and 8
+are specified in full — declarations, status-bar-style semantics, the exact
+letterbox predicate — in
+[the consumer `<head>` contract](./ios-conformance.md#becoming-a-home-screen-web-app-the-consumer-head-contract).
+---
+## What junoui explicitly does not do
+This half is why the page exists. None of the following is planned, partial, or
+"coming to the roadmap" — it is out of scope by design.
+**No JS behaviour.** No focus traps, no scroll locking, no gesture or swipe
+handling, no runtime popover positioning, no list virtualization, no state. Every
+component renders with zero JS; what is stateful is the platform's (`<dialog>`,
+`popover`, `<details>`) or yours. junoui does ship two JS entry points —
+`icons/inline` and `icons/install` — and they are **icon-sprite helpers, nothing
+more**.
+**No service worker, no offline story, no cache.** No precaching, no purge, no
+versioning, no `skipWaiting` policy. [boot-shell.md](./boot-shell.md) documents
+the five-rung boot pattern including an app-shell service worker — that is a
+**recipe your app implements**, with a reference implementation in another
+repository. junoui ships none of that code.
+**No native chrome.** `dist/ios/JunoTokens.swift` is **token values only**. There
+are no UIKit or SwiftUI components. `.juno-dock` and `.juno-navbar` are CSS that
+_looks_ like a bar; they are not the system bar and do not inherit its
+behaviours.
+**Nothing about in-app browsers.** SFSafariViewController and WKWebView-based
+in-app browsers (Instagram, Facebook) are a **separate, unfixed path** and
+junoui has tested neither. The one datum on record: Safari 26.0's notes claim a
+fix for `lvh`/`vh` being sized against the small viewport in
+SFSafariViewController, but **WebKit bug 255708 (filed 2023) is still open**, so
+that "Fixed" is stronger than the tracker supports.
+**No app-shell assets.** No web app manifest, no Home-Screen icons, no splash
+screens, no install prompt. `src/icons/` is a **UI icon sprite** — the icons
+inside your interface, not the icon on the Home Screen.
+**No guarantee below Safari / iOS 17.0**, and the losses compound rather than
+arriving all at once: **16.2** drops `color-mix()` (**28 uses** — every role
+tint, border and shadow built from `var(--juno-role)`, which is the contract
+junoui exists to encode); **16.0** drops `@container`; **15.4** drops `oklch()`
+(**190 uses** — every token value) and `dvh`/`lvh` (**10 uses** — the app shell
+collapses to content height). There is no fallback layer for any of them, and
+none is planned. If you are on iOS 15 you are not using junoui.
+**No verified iOS 26 story.** The claim "iOS 26 changed nothing about safe
+areas, viewport-fit, touch behaviour or focus zoom" was **refuted** during
+verification, so junoui's iOS 26 behaviour is _unverified_, not
+_confirmed-safe_. Open leads — `vh` reportedly pinning to `window.outerHeight`,
+three new tab modes yielding different `innerHeight`, iPadOS 26 windowed mode
+reportedly returning nothing for `env(safe-area-inset-*)` — need a physical
+device, not more documentation.
+---
+## Where the detail lives
+| Page                                       | What it settles                                                                            |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------ |
+| [ios-conformance.md](./ios-conformance.md) | every iOS metric with its source, the folklore named, the letterbox, the `<head>` contract |
+| [browser-support.md](./browser-support.md) | the three floors, all 15 features with degrade-or-break, the two shipped silent failures   |
+| [getting-started.md](./getting-started.md) | the required viewport meta and what depends on it                                          |
+| [accessibility.md](./accessibility.md)     | the WCAG 2.2 criterion behind each target size, and the per-component ARIA contract        |
+| [integration.md](./integration.md)         | import order, the token bridge, and where app-specific things go                           |
+| [boot-shell.md](./boot-shell.md)           | the boot ladder — a pattern to implement, not code junoui ships                            |

package/docs/native.md CHANGED Viewed

@@ -1,4 +1,4 @@
-# Native mobile (Android / iOS)
+# Native (Android / iOS / Rust)
 Native platforms can't parse `oklch()`, so colors are pre-converted to sRGB hex
 during the build. Values match the web rendering.
@@ -43,6 +43,43 @@ let body: CGFloat = JunoTokens.fontSize14
 - Colors are `UIColor` constants named `<palette><Mode><Role>` (camelCase).
 - Dimensions are `CGFloat` constants.
+## Rust
+Any native Rust stack — egui, iced, Slint, Bevy, Dioxus desktop, Tauri's Rust
+side. Vendor `dist/rust/juno_tokens.rs` into your crate, or add junoui as a
+build dependency and copy it in `build.rs`.
+```rust
+include!(concat!(env!("OUT_DIR"), "/juno_tokens.rs")); // or `mod juno_tokens;`
+let bg = STANDARD_DARK.s0.to_f32_array();   // a whole theme, picked at runtime
+let accent = STANDARD_DARK_ACTIVE;          // or one role, flat
+let gap = SPACE_16;                         // f32 px
+let fade = MOTION_DURATION_BASE_MS;         // f32 milliseconds
+```
+| Emitted as                                         | From                                                 |
+| -------------------------------------------------- | ---------------------------------------------------- |
+| `Rgba` (`hex()`, `to_f32_array()`, `with_alpha()`) | every color token                                    |
+| `Palette` + one const per palette/mode             | the same colors, grouped                             |
+| `f32`                                              | `px` lengths                                         |
+| `f32`, suffixed `_MS`                              | `ms` durations                                       |
+| `i32`                                              | whole numbers (z-index, font weight)                 |
+| `f32`                                              | ratios (opacity, line height)                        |
+| `&str`                                             | CSS-authored values, verbatim (shadows, font stacks) |
+**`to_f32_array()` is sRGB-encoded, not linear.** If your pipeline wants linear
+(wgpu with a non-sRGB surface format), convert at your boundary — junoui cannot
+know which surface you created.
+**Shadows and font stacks are shipped unparsed.** A Rust renderer cannot consume
+`0 4px 14px rgb(0 0 0 / 0.35)` directly; they are here so the values live in one
+place, not as ready-made native input.
+**Do not transcribe these values into your own crate.** That copy is exactly
+what this target exists to stop — it goes stale on the first patch release and
+no lint catches it.
 ## Keeping in sync
 Re-run `npm run build` in junoui and re-copy the files (or script the copy in your