@junoput01/junoui 0.3.0 → 0.4.0

package/docs/ios-conformance.md

@@ -0,0 +1,224 @@
+# iOS conformance
+
+What junoui encodes for iOS, **with sources**, and — just as important — what it
+deliberately does _not_ encode because no primary source supports it.
+
+Most numbers the design community attributes to Apple are not in Apple's text.
+This page exists so nobody re-derives folklore, and so nobody "fixes" a correct
+value into a wrong one later.
+
+> **Verifying anything here.** Apple's HIG is a JavaScript app: a plain `curl`
+> returns an empty shell. Check the backing DocC JSON instead —
+> `developer.apple.com/tutorials/data/design/human-interface-guidelines/<page>.json`.
+> Also pin a Wayback snapshot: the HIG silently drops guidance (see the 44pt
+> story below). State verified 2026-08-03.
+
+## The units question, first
+
+**One Apple point = one CSS pixel.** Apple's `pt` is a density-independent
+point, not the CSS typographic point; `devicePixelRatio` absorbs @2x/@3x. So
+Apple's 44pt is CSS `44px`.
+
+Converting through the CSS unit (`1pt = 1/72in`, `1px = 1/96in` → 44pt =
+58.67px) is **wrong**. If you ever see 58.67 in this codebase, it is a bug.
+
+This identity holds only when the page ships
+`<meta name="viewport" content="width=device-width, initial-scale=1">`. Without
+it iOS Safari lays out at ~980px and every metric drifts.
+
+- Source: [css-values-4](https://www.w3.org/TR/css-values-4/) for the CSS units,
+  [WebKit iPhone X guide](https://webkit.org/blog/7929/designing-websites-for-iphone-x/)
+  for the viewport model.
+
+## Touch targets
+
+| What                                          | Value                                                    | Status                      |
+| --------------------------------------------- | -------------------------------------------------------- | --------------------------- |
+| WCAG 2.2 SC 2.5.8 Target Size (Minimum)       | **24×24 CSS px**                                         | **Hard requirement** for AA |
+| WCAG 2.2 SC 2.5.5 Target Size (Enhanced)      | **44×44 CSS px**                                         | AAA (recommendation tier)   |
+| HIG Buttons — hit region                      | **44×44 pt** ("needs a hit region of at least 44×44 pt") | Recommendation              |
+| HIG Accessibility — control size (iOS/iPadOS) | **44×44 pt default, 28×28 pt minimum**                   | Recommendation              |
+| HIG Accessibility — padding between controls  | **~12 pt** bezeled, **~24 pt** non-bezeled               | Recommendation, hedged      |
+
+junoui encodes `--juno-size-tap-min` = 24px (the AA floor) and
+`--juno-size-tap-comfortable` = 44px, and promotes the former to the latter
+under `@media (pointer: coarse)` — see [accessibility.md](./accessibility.md).
+
+- Sources: [WCAG 2.5.8](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html),
+  [WCAG 2.5.5](https://www.w3.org/WAI/WCAG22/Understanding/target-size-enhanced.html),
+  [HIG Accessibility](https://developer.apple.com/design/human-interface-guidelines/accessibility),
+  [HIG Buttons](https://developer.apple.com/design/human-interface-guidelines/buttons).
+
+### Folklore, named
+
+- **"Apple mandates a 44pt _minimum_ tap target — see HIG Layout."** That
+  sentence has been **deleted**. The current Layout page contains no tap-target
+  number at all (`"44x44"` and `"tappable"` both return zero hits); a 2023
+  Wayback snapshot of the same endpoint still has it. Every checklist citing
+  that URL cites a dead page. What survives is the Buttons wording above.
+- **"44px because WCAG."** Wrong at AA — the AA floor is 24px. 44 is Apple's
+  number, which WCAG AAA happens to match. W3C never says it derived 44 from
+  Apple.
+
+## Spacing
+
+**Apple publishes no numeric spacing scale for iOS.** No 4pt or 8pt grid, no
+named spacing steps, no layout-margin or gutter constants, no readable-width
+number. Standard margins are delegated to system layout guides.
+
+The only Apple-published numbers found anywhere:
+
+- **~12 pt / ~24 pt** control padding (HIG Accessibility, hedged: "in general",
+  "about", "works well").
+- **8 pt** — `UIView.directionalLayoutMargins` default. This is a **UIKit API
+  default, not an HIG design rule**; cite it as such.
+
+So: **"Apple's 8pt grid" and "HIG standard margins are 16–20pt" are folklore.**
+junoui's spacing scale is junoui's own; do not claim Apple provenance for it.
+
+- Source: [HIG Layout](https://developer.apple.com/design/human-interface-guidelines/layout),
+  [UIView.directionalLayoutMargins](https://developer.apple.com/documentation/uikit/uiview/directionallayoutmargins).
+
+## Safe areas
+
+`env(safe-area-inset-top|right|bottom|left)` — four variables, iOS 11 (shipped
+as `constant()` in 11.0, renamed `env()` in 11.2). There is no numeric constant
+to hardcode; values are system-supplied and vary by device.
+
+**They are inert unless the page opts in.** `viewport-fit` defaults to `auto`,
+and WebKit reports every inset as `0` until you set `cover`. `contain` does
+_not_ opt out — only `cover` does. junoui is a stylesheet and cannot set this
+for you, so it is stated as a hard requirement in
+[getting-started.md](./getting-started.md), every showcase page carries it, and
+a build test enforces that.
+
+- Sources: [WebKit iPhone X guide](https://webkit.org/blog/7929/designing-websites-for-iphone-x/),
+  [WebKit bug 272779](https://bugs.webkit.org/show_bug.cgi?id=272779),
+  [css-env-1](https://www.w3.org/TR/css-env-1/).
+- Spec ownership, for citation hygiene: `env()` and `safe-area-inset-*` are
+  **css-env-1**; `viewport-fit` is **css-round-display-1**. CSS Viewport Module
+  L1 defines none of them — citing it is misattribution.
+
+### `max()` vs addition — the rule
+
+WebKit's documented pattern is `padding-left: max(12px, env(safe-area-inset-left))`
+— "the default padding **or** the safe area inset, whichever is greater". (The
+`12px` there is an arbitrary demo value, not an Apple metric.)
+
+That pattern applies to **padding on a surface that reaches the screen edge**:
+the inset's job is to push content clear of the cutout, so it _replaces_ your
+baseline rather than stacking on it.
+
+It does **not** apply to a **floating element positioned off the edge**, where
+addition is correct:
+
+```css
+/* floating pill: sit 16px ABOVE the home-indicator region */
+inset-block-end: calc(var(--juno-space-16) + env(safe-area-inset-bottom, 0px));
+
+/* NOT max() — that would park the pill flush against the indicator */
+```
+
+Nor to the **clearance tokens** (`--juno-dock-clearance`,
+`--juno-pillbar-clearance`), where content must clear the control's height _and_
+the inset beneath it — genuinely additive.
+
+junoui's call sites were audited against this rule (2026-08-03) and the additive
+ones are correct as written. Do not "fix" them to `max()` without re-reading
+this section.
+
+### The unit trap
+
+Inside `calc()`, an env() fallback **must carry a unit**:
+
+```css
+/* WRONG — unitless 0 is a <number>, the sum is invalid, and the whole
+   DECLARATION is dropped (it does not evaluate to zero) */
+padding-block-end: calc(var(--juno-space-12) + env(safe-area-inset-bottom, 0));
+
+/* RIGHT */
+padding-block-end: calc(var(--juno-space-12) + env(safe-area-inset-bottom, 0px));
+```
+
+A bare (non-`calc`) value may keep a unitless `0`. A build test enforces this.
+Note this follows from ordinary CSS type rules; no Apple/WebKit source states it
+specifically. The adjacent _confirmed_ unit pitfall is that the
+`@supports (padding: max(0px))` feature test needs a unit — and that `@supports`
+wrapper is itself obsolete boilerplate in 2026.
+
+## Viewport units
+
+CSS defines three families by how dynamic browser chrome is treated:
+`sv*` (chrome assumed **expanded** — smallest), `lv*` (assumed **retracted** —
+largest), `dv*` (tracked live). **The unprefixed `vh`/`vw` are normatively equal
+to `lv*`** — that is the spec-level cause of the classic `100vh` overflow: a
+`100vh` box is sized as if the toolbar were retracted.
+
+junoui uses **zero raw `vh`**. Full-height surfaces use `dvh`
+(`layout.css`, `drawer.css`) and `85dvh` caps the bottom sheet.
+
+Caveats worth knowing before changing any of that:
+
+- `dv*` is explicitly **not stable** and not guaranteed to update every frame,
+  so it can churn while the address bar collapses. `sv*` is the calm choice when
+  a surface must never overflow.
+- iOS shipped viewport-unit bugs into the **iOS 26** era: Safari 26.0 fixed
+  `lvh`/`vh` being sized against the _small_ viewport in `SFSafariViewController`.
+  The underlying WebKit bug (255708, filed 2023) is **still open**, so Apple's
+  "Fixed" is stronger than the tracker supports. Scope is the in-app browser used
+  by Slack/X — not standalone Safari, and not `WKWebView`-based in-app browsers
+  (Instagram/Facebook), a separate unfixed path.
+- Do **not** reach for `env(safe-area-max-inset-*)` as a fix. It is in css-env-1
+  but could not be confirmed shipping in any engine.
+
+- Sources: [css-values-4 §6.1.2.1](https://www.w3.org/TR/css-values-4/),
+  [csswg-drafts#6454](https://github.com/w3c/csswg-drafts/issues/6454),
+  [Safari 26.0 release notes](https://developer.apple.com/documentation/safari-release-notes/safari-26-release-notes),
+  [WebKit bug 255708](https://bugs.webkit.org/show_bug.cgi?id=255708).
+
+## Typography
+
+iOS: **17 pt default body size, 11 pt minimum**; Dynamic Type must accommodate
+enlargement to **200%**. Contrast minimums are 4.5:1 up to 17pt, 3:1 at 18pt or
+bold. Since 1pt = 1 CSS px, that is 17px / 11px.
+
+Confidence: medium — extracted from the HIG Accessibility page but not
+adversarially re-verified. Re-check before encoding as a hard constraint.
+
+### The 16px input rule
+
+junoui holds text-entry controls at a 16px floor on coarse pointers, because
+iOS Safari is widely observed to zoom the page onto a focused field under 16px.
+
+**No primary WebKit or Apple source for this was found.** It is empirical
+behavior, not published spec. The mitigation is harmless, so it stays — but do
+not cite it as documented, and re-verify it on iOS 26.
+
+## Things a stylesheet controls that Apple says nothing about
+
+No primary Apple source was found for any of: `touch-action`,
+`-webkit-tap-highlight-color`, `overscroll-behavior`, momentum scrolling, or
+`scroll-snap` on iOS. Where junoui uses these (the coarse-pointer tap-highlight
+reset, `overscroll-behavior: contain` on the modal body), it is **community
+convention** — sensible, but do not attribute it to Apple.
+
+`-webkit-overflow-scrolling: touch` is legacy and must not be reintroduced.
+
+## Open risk: iOS 26
+
+The claim "iOS 26 changed nothing about safe areas, viewport-fit, touch
+behavior, or focus zoom" was **refuted** during verification, so junoui's iOS 26
+behavior is unverified rather than confirmed-safe.
+
+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.
+
+Unconfirmed leads, tracked in ticket 20260803-034: `vh` reportedly pinning to
+`window.outerHeight`; three new tab modes yielding different `innerHeight`; a
+reported iPadOS 26 windowed-mode bug where `env(safe-area-inset-*)` returns
+nothing. Resolving these needs a physical device, not more documentation.
+
+- Source: [WebKit features in Safari 26.0](https://webkit.org/blog/17333/webkit-features-in-safari-26-0/).

package/docs/layout.md

@@ -36,6 +36,7 @@ default — override per instance inline.
 | `.juno-grid-auto--tiles` | Media wall wired to the density layer    | `--juno-tile-min` / `--juno-gap-content` |
 | `.juno-sidebar`          | Aside + fluid content, stacks when tight | `--juno-sidebar-width` (`280px`)         |
 | `.juno-switcher`         | N-up or all-stacked at a threshold       | `--juno-switcher-threshold` (`bp-sm`)    |
+| `.juno-scroller`         | Bare scroll container (axis/snap/bar)    | `--juno-scroller-snap` (`none`)          |
 | `.juno-reel`             | Horizontal scroll-snap row               | `--juno-reel-space` (`space-12`)         |
 
 ### Examples
@@ -75,6 +76,73 @@ default — override per instance inline.
 `data-juno-density` attribute re-densifies controls, surfaces **and** content
 grids together.
 
+## Scroller
+
+Every scrolling region in the library — `.juno-reel`, `.juno-app-shell__main`,
+tab strips — is the same three knobs: overflow axis, overscroll containment,
+snap type. `.juno-scroller` ships them as overridable custom props instead of
+each consumer re-deriving (and usually forgetting `overscroll-behavior`, which
+lets iOS pull-to-refresh/scroll-chain through an inner scroller into the
+page). Defaults: `overflow: auto` (both axes), `overscroll-behavior: contain`,
+no snap.
+
+```html
+<!-- vertical list scroller with containment, no snap -->
+<div class="juno-scroller juno-scroller--y">…</div>
+
+<!-- horizontal, scrollbar hidden, softer "proximity" snap, opt-in stops -->
+<div
+  class="juno-scroller juno-scroller--x juno-scroller--bare"
+  style="--juno-scroller-snap: x proximity;"
+>
+  <div class="juno-snap">…</div>
+  <div class="juno-snap">…</div>
+</div>
+```
+
+- `.juno-scroller--x` — horizontal axis only (`overflow: auto hidden`)
+- `.juno-scroller--y` — vertical axis only (`overflow: hidden auto`)
+- `.juno-scroller--bare` — hides the scrollbar (Firefox + WebKit)
+- `.juno-snap` — on a child: opts into `scroll-snap-align`
+
+`.juno-reel` is `.juno-scroller`'s horizontal-snap preset baked into one
+class: it now reads its `scroll-snap-type` from the same `--juno-scroller-snap`
+prop (default unchanged: `inline mandatory`), so the mode is overridable
+per instance instead of hardcoded — e.g. a "magnet" strip that wants
+`proximity` instead of a stepped `mandatory` feel:
+
+```html
+<div class="juno-reel" style="--juno-scroller-snap: inline proximity;">…</div>
+```
+
+## Gesture surfaces
+
+For an element whose pointer events an app JS layer owns outright — drag-pan,
+pinch-zoom, swipe classification, anything that is a state machine rather than
+native scrolling — junoui ships the CSS side of that contract as one class.
+The gesture handler itself is the app's job (or a sibling `junoui-<framework>`
+package): junoui declares the surface, never the logic.
+
+```html
+<div class="juno-gesture-surface" id="viewport"><!-- JS drag/pinch handlers attach here --></div>
+
+<!-- only needs the touch-action axis lock, not the full reset -->
+<li class="juno-list__item juno-pan-x"><!-- swipe-to-reveal row --></li>
+```
+
+`.juno-gesture-surface` sets `touch-action: var(--juno-touch-action, none)`,
+`-webkit-touch-callout: none`, `user-select: none` and
+`-webkit-tap-highlight-color: transparent` — so the UA never fights the
+handler with its own scroll/zoom recognition, long-press callout, text
+selection or tap flash. Override `--juno-touch-action` per instance to hand
+back one axis (`pan-x` / `pan-y`) instead of all of them. `.juno-pan-x` /
+`.juno-pan-y` are standalone single-axis classes for elements that want the
+axis lock alone.
+
+These four properties are **community convention, not Apple-documented
+behavior** — see [ios-conformance.md](./ios-conformance.md) before citing them
+as a platform requirement.
+
 ## App shell
 
 Every product app assembles the same frame; `.juno-app-shell` ships it as
@@ -117,7 +185,9 @@ What the primitive encodes so you don't have to:
   short-page pitfall of sticky nav bars (below) can't happen here.
 - **Safe-area insets** — the shell pads for landscape notches
   (`inset-left`/`right`), the topbar for `inset-top`, the dock for
-  `inset-bottom`.
+  `inset-bottom`. **This requires `viewport-fit=cover` in your page's viewport
+  meta** ([getting-started](./getting-started.md#required-the-viewport-meta)) —
+  without it iOS reports every inset as `0` and none of this padding happens.
 
 Collapse the rail by toggling `.juno-rail--collapsed` (one class; the width
 transition and label hiding are built in). Trays/detail panels: the

package/docs/web.md

@@ -87,3 +87,9 @@ import '@junoput01/junoui/fonts.css'; // opt-in: self-hosted B612 woff2, no netw
 
 …or bring your own B612 (e.g. `@fontsource/b612`). Without either, the UI falls back to
 system sans/mono. See [integration.md](./integration.md#2-fonts-opt-in-csp-safe).
+
+## Boot performance
+
+An app that wants chrome on screen at the first HTML parse — before `juno.css`
+or any bundle arrives — and everything else loaded in the background follows
+the boot-shell ladder: [boot-shell.md](./boot-shell.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@junoput01/junoui",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "junoui — a token-driven design system. Color carries semantic meaning, never decoration: every hue has one assigned role (NOMINAL / ACTIVE / TARGET / CAUTION / WARNING). Ships multi-platform tokens (CSS, SCSS, JS/TS, JSON, Android, iOS, Flutter) plus a framework-agnostic CSS component layer.",
   "type": "module",
   "license": "MIT",
@@ -29,7 +29,8 @@
   "module": "./dist/js/tokens.js",
   "types": "./dist/js/tokens.d.ts",
   "sideEffects": [
-    "**/*.css"
+    "**/*.css",
+    "./dist/icons/inline.js"
   ],
   "exports": {
     ".": {
@@ -39,6 +40,7 @@
     },
     "./css": "./dist/css/juno.css",
     "./css/tokens": "./dist/css/juno-tokens.css",
+    "./css/custom-media": "./dist/css/juno-custom-media.css",
     "./fonts.css": "./dist/css/juno-fonts.css",
     "./scss": "./dist/scss/_juno-tokens.scss",
     "./tokens.json": "./dist/json/tokens.json",
@@ -47,6 +49,7 @@
     "./ios": "./dist/ios/JunoTokens.swift",
     "./flutter": "./dist/flutter/juno_tokens.dart",
     "./icons": "./dist/icons/juno-icons.svg",
+    "./icons/inline": "./dist/icons/inline.js",
     "./package.json": "./package.json"
   },
   "files": [

package/src/css/base.css

@@ -13,7 +13,37 @@
 /* System color scheme. Without data-juno-mode the theme follows the OS
    (`prefers-color-scheme`; see juno-tokens.css) — `dark light` here lets the
    UA pick matching scrollbars/form chrome. An explicit mode pins both. */
-:root { color-scheme: dark light; }
+:root {
+  color-scheme: dark light;
+
+  /* Floating-nav scroll clearance — a page/scroller that a fixed dock or
+     pillbar floats over reserves this much room at its foot so the last row
+     clears the overlay. Consumers write `padding-block-end:
+     var(--juno-dock-clearance)` and stay correct when the dock geometry
+     changes — no hand-rolled calc() per app. Web-only (they carry env()), so
+     they live in the CSS layer, not the cross-platform token set.
+     --juno-dock-clearance ≈ pill height + bottom margin + breathing room;
+     --juno-pillbar-clearance suits the shorter centered pill. */
+  --juno-dock-clearance: calc(var(--juno-space-72) + var(--juno-space-20) + env(safe-area-inset-bottom, 0px));
+  --juno-pillbar-clearance: calc(var(--juno-space-72) + env(safe-area-inset-bottom, 0px));
+
+  /* JS-readable motion contract. CSS-only `prefers-reduced-motion` never reaches
+     imperative JS (scrollTo/scrollIntoView smooth behavior, rAF-driven transforms,
+     an "animate or not" branch) — so the preference is also exposed as a custom
+     property script can read with one getComputedStyle call, no matchMedia
+     listener required for a one-shot check:
+       getComputedStyle(document.documentElement)
+         .getPropertyValue('--juno-motion').trim() !== 'none'
+     A component MAY author its durations through the scale rather than a raw
+     duration token — `calc(var(--juno-motion-duration-base) * var(--juno-motion-scale))`
+     — so the reduced-motion override below collapses them to 0 without its own
+     per-component media query. Web-only DOM contract, so it lives
+     here rather than in the cross-platform token set (see --juno-dock-clearance
+     above for the same reasoning). */
+  --juno-motion: auto;
+  --juno-motion-scale: 1;
+}
+
 :root[data-juno-mode='dark'] { color-scheme: dark; }
 
 /* Control surfaces. On dark panels the hairline border (~23% L) disappears, so
@@ -90,17 +120,102 @@ code, kbd, samp, pre { font-family: var(--juno-font-family-mono); }
 @media (pointer: coarse) {
   :root { --juno-size-tap-min: var(--juno-size-tap-comfortable); }
 
-  /* iOS Safari zooms the page onto any focused text field whose font-size is
-     below 16px. Hold text-entry controls (.juno-input covers input, textarea
-     and the select's inner control) at a 16px floor on touch so focusing never
-     triggers that jump. max() keeps the floor even under a scaled-down
-     --juno-font-scale, and still grows when scaled up. */
+  /* iOS Safari is widely observed to zoom the page onto a focused text field
+     whose font-size is under 16px. NOTE: no primary WebKit/Apple source states
+     this — it is empirical behavior, not published spec, so don't cite it as
+     one (see docs/ios-conformance.md and ticket 20260803-032). The mitigation
+     is harmless either way: hold text-entry controls (.juno-input covers input,
+     textarea and the select's inner control) at a 16px floor on touch. max()
+     keeps the floor even under a scaled-down --juno-font-scale, and still grows
+     when scaled up. */
   .juno-input { font-size: max(16px, var(--juno-font-size-16)); }
+
+  /* Kill the UA tap-highlight square on the interactive surfaces so it never
+     flashes past a rounded control on tap. Consumers were adding this by hand
+     per component; make it a first-class touch default. See 20260802-020. */
+  :where(
+    .juno-btn,
+    .juno-dock__item,
+    .juno-pillbar__item,
+    .juno-tabs__tab,
+    .juno-list__item,
+    .juno-menu__item
+  ) {
+    -webkit-tap-highlight-color: transparent;
+  }
+}
+
+/* Tappable primitives opt out of double-tap-to-zoom. A browser that still
+   recognises that gesture has to WAIT after the first tap to see whether a
+   second one is coming, which reads as a late, mushy tap on exactly the
+   surfaces a phone UI is built from. `manipulation` keeps panning and
+   pinch-zoom (so the page stays zoomable — never `none` here, that would be an
+   a11y regression) and drops only the double-tap.
+   NOT inside the pointer:coarse block above: a hybrid device (touch laptop,
+   iPad with a trackpad) reports a fine primary pointer while still taking
+   touch input, and the property is inert on a mouse anyway.
+   Community convention — no primary Apple/WebKit source names it; see
+   docs/ios-conformance.md. Named components only, so a consumer's own elements
+   are untouched. See 20260803-038. */
+:where(
+  .juno-btn,
+  .juno-dock__item,
+  .juno-pillbar__item,
+  .juno-pillbar__overflow,
+  .juno-tabs__tab,
+  .juno-list__item,
+  .juno-menu__item,
+  .juno-seg__option,
+  .juno-chip,
+  .juno-toggle-btn
+) {
+  touch-action: manipulation;
+}
+
+/* Gesture-owned surfaces — for an element whose pointer events are fully
+   driven by app JS (drag-pan, pinch-zoom, swipe classification: a state
+   machine, not a native scroller). The UA must get out of the way: no
+   scroll/zoom gesture recognition, no callout menu on long-press, no text
+   selection, no tap-highlight flash. Community convention — no primary
+   Apple/WebKit source names any of these four properties for iOS, see
+   docs/ios-conformance.md; do not attribute them to Apple. Opt-in utility
+   class (unlike the pointer:coarse reset above, which targets junoui's own
+   named components), so it isn't gated behind a pointer-type query — apply
+   it only to elements a gesture handler actually owns.
+   --juno-touch-action narrows the axis without overriding the rest of the
+   block; default `none` hands every axis to JS. */
+.juno-gesture-surface {
+  touch-action: var(--juno-touch-action, none);
+  -webkit-touch-callout: none;
+  user-select: none;
+  -webkit-tap-highlight-color: transparent;
 }
 
+/* Single-axis escape hatches: the UA keeps native scrolling on one axis
+   while JS reads gestures on the other (e.g. a vertical list row that also
+   supports horizontal swipe-to-reveal). Equivalent to
+   `--juno-touch-action: pan-x|pan-y` on .juno-gesture-surface, offered as
+   standalone classes for elements that only need the axis lock and none of
+   the callout/selection/tap-highlight resets. */
+.juno-pan-x { touch-action: pan-x; }
+.juno-pan-y { touch-action: pan-y; }
+
 @keyframes juno-blink { 0%, 100% { opacity: 1; } 50% { opacity: 0; } }
 
+/* Softer opacity pulse — a "working / refreshing" cadence that dims rather
+   than fully blinks out (used by the reload indicator and any live dot that
+   wants a gentler beat than juno-blink). */
+@keyframes juno-pulse { 0%, 100% { opacity: 1; } 50% { opacity: 0.35; } }
+
 @media (prefers-reduced-motion: reduce) {
+  /* Flip the JS-readable contract declared at the top of this file. Without
+     this the property would always report `auto` and script could never see
+     the preference — the whole point of exposing it. */
+  :root {
+    --juno-motion: none;
+    --juno-motion-scale: 0;
+  }
+
   *, *::before, *::after {
     animation-duration: 0.01ms !important;
     animation-iteration-count: 1 !important;
@@ -125,3 +240,51 @@ code, kbd, samp, pre { font-family: var(--juno-font-family-mono); }
   .juno-readout { border: 1px solid CanvasText; }
   .juno-badge { forced-color-adjust: none; } /* keep status fill meaningful */
 }
+
+/* ── iOS standalone letterbox unlock ─────────────────────────────────────────
+   iOS WebKit (observed through 26.6, iPhone 16 Pro, iOS 18.7) sizes a
+   Home-Screen standalone window whose DOCUMENT cannot scroll as if a
+   retractable browser toolbar existed: `screen.height − status bar`, pinned to
+   the top. The reserved strip — exactly env(safe-area-inset-top) — surfaces at
+   the BOTTOM of the glass, outside the window, painting black on every screen.
+   The same install with a scrollable document gets the whole screen.
+
+   Established by measurement, not inference (nexora 20260812-006): 201 device
+   readings; a four-structure A/B on one install where doc-scroll = full screen
+   and fixed-shell = letterboxed on every cold launch; and this exact mechanism
+   — the shell kept, the document left scrollable behind it by an invisible
+   in-flow spacer — verified full-screen on the device before landing here.
+   Transient scrollability is NOT enough (seven timed interventions, five
+   controlled runs, all negative): iOS samples the resting structure.
+
+   So: keep the document scrollable behind the app. The spacer is body::after
+   (a consumer that needs body::after for itself overrides this at the same
+   gate — none of ours do), invisible, 1px wide, and taller than the LARGE
+   viewport so the document always overflows whatever window iOS grants.
+   `overscroll-behavior: none` keeps the ghost scroller from rubber-banding;
+   apps put `overscroll-behavior: contain` on their real scrollers so an
+   inner fling never chains into it.
+
+   Gate, all three required:
+     display-mode: standalone       only installed apps are letterboxed
+     pointer: coarse                touch devices — keeps macOS Dock apps out
+     -webkit-touch-callout support  iOS/iPadOS WebKit only
+   Selectors carry `html:root` (0,1,2) on purpose: app resets commonly declare
+   `body { overflow: hidden }` at (0,0,1) AFTER this sheet, and the unlock must
+   win the cascade without !important. */
+@media (display-mode: standalone) and (pointer: coarse) {
+  @supports (-webkit-touch-callout: none) {
+    html:root,
+    html:root body { overflow: visible; }
+    html:root body { overscroll-behavior: none; }
+
+    html:root body::after {
+      content: '';
+      display: block;
+      width: 1px;
+      height: calc(100lvh + 80px);
+      visibility: hidden;
+      pointer-events: none;
+    }
+  }
+}