Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

spec(AST-099): the keyboard height comes from the visual viewport in every browser (#8385)

Christopher Chedeau106a98cfbd56
diff --git a/docs/architecture/react-component-runtime.md b/docs/architecture/react-component-runtime.md
index b9c2df7a63..d4c3042915 100644
--- a/docs/architecture/react-component-runtime.md
+++ b/docs/architecture/react-component-runtime.md
@@ -154,8 +154,7 @@ those contracts.
keyboard change. A component outside Core does not ride; it commits the
resting value once. Packages outside Core cannot import the hook; a
component there that responds to the keyboard keeps one listener that
- measures as `spec:AST-099` FR2 defines, or takes the browser's keyboard report
- where FR8 applies, keeps focus from panning as FR4
+ measures as `spec:AST-099` FR2 defines, keeps focus from panning as FR4
does, blurs as FR5 does, applies the height through a functional style on
its own elements, and follows INV3 and INV5. The hook follows INV3 and
INV5.
@@ -293,13 +292,13 @@ observable-behavior predicates require review or runtime evidence. Likewise, a
focused test proves only its named behavior and mutation expectation; a green
component suite is not blanket conformance with every invariant.
-| Invariant | Evidence | Failure signal |
-| ---------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| INV1–INV2 | Initial-render and interaction tests | Output flashes a known-wrong state, or one action is delayed or repeated through an Effect |
-| INV3, INV5 | StrictMode setup/cleanup and dependency-change tests | Duplicate callback, leaked work, stale subscription, or missing resynchronization |
-| INV1, INV4, INV6 | Ref attach/null/replacement, DOM-in-state rejection, and old-node cleanup-before-new-attach mutations | A DOM node or collection enters state, old node remains active, cleanup misses replacement, or ref mutation changes semantics silently |
-| INV7 | Real-browser geometry plus N-consumer observer-instance/subscription mutations | Geometry is invalid, observer instances grow with repeated consumers, one unsubscribe silences peers, or cleanup removes another subscriber |
-| INV8 | Owner-observable behavior across documented composition replacement; optional focused internal mechanism tests | Behavior disappears or changes owner when a documented subpart is replaced |
-| INV9 | Provider/external-store identity and render-count tests | Unchanged semantic payload changes identity, or snapshot identity creates a render loop |
-| INV10 | Shared test over every adopter of the announcement module | An adopter holding its own Effect, observer, timer, or listener for its own-content announcement |
-| INV11 | Source boundary check plus hook tests across StrictMode replay and unmount | A second keyboard listener or measurement in Core; a consumer reading a CSS custom property on the root or a shared ancestor for the height; an export of the hook; a component outside Core measuring by a rule other than AST-099 FR2 or, where it applies, FR8, or riding the keyboard; a listener left after unmount; a Core rider driven by JavaScript per frame or by its own transition; or more than one layout read per keyboard change |
+| Invariant | Evidence | Failure signal |
+| ---------------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| INV1–INV2 | Initial-render and interaction tests | Output flashes a known-wrong state, or one action is delayed or repeated through an Effect |
+| INV3, INV5 | StrictMode setup/cleanup and dependency-change tests | Duplicate callback, leaked work, stale subscription, or missing resynchronization |
+| INV1, INV4, INV6 | Ref attach/null/replacement, DOM-in-state rejection, and old-node cleanup-before-new-attach mutations | A DOM node or collection enters state, old node remains active, cleanup misses replacement, or ref mutation changes semantics silently |
+| INV7 | Real-browser geometry plus N-consumer observer-instance/subscription mutations | Geometry is invalid, observer instances grow with repeated consumers, one unsubscribe silences peers, or cleanup removes another subscriber |
+| INV8 | Owner-observable behavior across documented composition replacement; optional focused internal mechanism tests | Behavior disappears or changes owner when a documented subpart is replaced |
+| INV9 | Provider/external-store identity and render-count tests | Unchanged semantic payload changes identity, or snapshot identity creates a render loop |
+| INV10 | Shared test over every adopter of the announcement module | An adopter holding its own Effect, observer, timer, or listener for its own-content announcement |
+| INV11 | Source boundary check plus hook tests across StrictMode replay and unmount | A second keyboard listener or measurement in Core; a consumer reading a CSS custom property on the root or a shared ancestor for the height; an export of the hook; a component outside Core measuring by a rule other than AST-099 FR2, or riding the keyboard; a listener left after unmount; a Core rider driven by JavaScript per frame or by its own transition; or more than one layout read per keyboard change |
diff --git a/docs/specs/AST-099-mobile-keyboard/spec.md b/docs/specs/AST-099-mobile-keyboard/spec.md
index 1c2ce40be7..11360a051d 100644
--- a/docs/specs/AST-099-mobile-keyboard/spec.md
+++ b/docs/specs/AST-099-mobile-keyboard/spec.md
@@ -59,8 +59,8 @@ a chat composer, or a search field.
- **FR1 — One keyboard height for every component.** Every Core and Lab
component that positions, sizes, or dismisses relative to the on-screen
- keyboard responds to the same keyboard height at the same moment (FR2, or
- FR8 where it applies), including
+ keyboard responds to the same keyboard height (FR2) at the same moment,
+ including
BottomSheet, the chat composer, a search field placed at the bottom, tab bar
search, drag to dismiss, and any keyboard layout guide, so no two components disagree about where the
keyboard is. `architecture:react-component-runtime` INV11 owns the single
@@ -103,30 +103,34 @@ a chat composer, or a search field.
- **FR6 — Capability detection.** Keyboard handling acts where the visual viewport
shrinks for the keyboard while the layout viewport keeps its height. It
detects that from the platform's viewport and keyboard capabilities, never
- from the user agent (`spec:AST-013` FR6). Where the browser itself reports
- the on-screen keyboard's geometry, as Chrome on Android does, the
- visual-viewport measurement does not apply and FR8 governs, on any device
- that shows an on-screen keyboard; a browser that offers the report but shows
- no on-screen keyboard reads 0. A page that is not a secure context gets no
- such report and follows FR2.
+ from the user agent (`spec:AST-013` FR6). Where the browser also reports
+ the on-screen keyboard's geometry, as Chrome on Android does, the height
+ comes from FR2 there too and FR8 governs how surfaces ride the keyboard, on any
+ device that shows an on-screen keyboard; a browser that offers the report but
+ shows no on-screen keyboard reads 0. A page that is not a secure context gets
+ no such report, so FR8 does not apply there.
- **FR7 — Top-level documents only.** Inside an iframe the frame's visual
viewport does not change when the keyboard opens, so the keyboard height is
0 there and nothing changes. Behavior and evidence for this record come
from a top-level document.
- **FR8 — Browsers that report the keyboard ride it smoothly.** In a browser
that reports the on-screen keyboard's geometry itself, such as Chrome on
- Android, the keyboard height comes from that report rather than FR2's
- visual-viewport measurement, and Core's
+ Android, the keyboard height comes from FR2's visual-viewport
+ measurement there too (DEC-4), and Core's
keyboard-aware surfaces ride the keyboard on show and on hide: they move with
the keyboard's slide, within one frame of it on the measured keyboards, with
no one-step jump and no surface left under the keyboard, no JavaScript per
frame, and one layout commit at rest (FR3). Under reduced motion nothing
travels with the keyboard, and the change follows `design:reduced-motion`
DR2, a cross-fade on a touch screen. A Lab surface commits the resting value without riding
- (`architecture:react-component-runtime` INV11). Outside keyboard-aware
- fields, Astryx never overrides the app's own viewport setting; the app's
+ (`architecture:react-component-runtime` INV11). Astryx never overrides
+ the app's own viewport setting. Where the app sets
`interactive-widget=resizes-content`, which Astryx documents and does not
- set, still applies there. An Android browser without a keyboard geometry API
+ set, Chrome on Android shrinks the layout viewport with the keyboard, so
+ FR2 reads 0: a keyboard-aware field's keyboard height is 0 there and it
+ does not ride, since the browser has already made the room. Everywhere
+ else, keyboard-aware surfaces ride the visual-viewport height (DEC-4).
+ An Android browser without a keyboard geometry API
that shrinks only its visual viewport, such as Firefox for Android, gets
FR2–FR5 under FR6.
@@ -178,19 +182,19 @@ a chat composer, or a search field.
## Verification
-| Contract | Verification | Representative states | Mutation or failure expectation |
-| ------------ | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| FR1 | Source boundary check over Core and Lab plus a shared test that drives one keyboard change | each listed consumer; a new keyboard-aware component | Two components reading different heights for one keyboard, or a component measuring by a rule other than FR2 or, where it applies, FR8 |
-| FR2 | Module tests driving visual-viewport resize and scroll events | keyboard shown; hidden; page panned with the keyboard shown; offset without a keyboard; page pinch-zoomed with and without the keyboard | A pan that lowers the reported height, or a height when no keyboard is shown |
-| FR3 | Consumer tests of computed layout, plus a public-surface check | keyboard shown and hidden; composer, bottom search field, tab bar search, Tall sheet; no animation running; a ride animation running with the composer, a scroll view, and a header together | A consumer whose layout ignores the height, layout that is only correct after an animation, riding surfaces out of sync on one keyboard change, per-frame layout work during a ride, content hidden or unscrollable at the resting value, or a public CSS custom property, export, or prop for the height |
-| FR4 | Focus-route tests with document scroll spies | tap, previous and next buttons, Tab, programmatic focus, Done then tap, app resume while scroll-locked | A route that scrolls the document, or a slipped scroll left in place |
-| FR5 | Surface move tests | sheet drag between heights, drag to dismiss, close, with a focused field | The field stays focused after a move starts, or content jumps on the first frame |
-| FR6 | Capability tests with the user agent varied | visual viewport shrinking with a fixed layout viewport; Chrome on Android reporting keyboard geometry; a desktop browser with the API and no on-screen keyboard; a page that is not a secure context; neither | Behavior that changes with the user agent alone, or measurement where the platform geometry API applies |
-| FR7 | Tests in an iframe and in a top-level document | the same keyboard event sequence in both | A non-zero value or a claimed focus inside an iframe |
-| FR8 | Chrome on Android in the emulator with Gboard, top-level document, plus a consumer documentation check | keyboard show and hide with the composer and a Tall sheet; a Lab bottom search field; reduced motion on; an app with `interactive-widget=resizes-content`, focus outside keyboard-aware fields | A Core surface jumping after the keyboard settles, lagging the keyboard by more than a frame, left under the keyboard, moved by JavaScript per frame, or committing layout more than once; a Lab surface riding instead of committing at rest; anything travelling with the keyboard under reduced motion instead of DR2's cross-fade; the app's viewport setting overridden outside keyboard-aware fields; or the setting missing from the docs |
-| FR8 | Firefox for Android, emulator or device, top-level document | focus routes, keyboard shown and hidden, page panned and pinch-zoomed, a sheet moved | The page lurches, the field ends under the keyboard, or the height is wrong after a pan or zoom |
-| FR2–FR5 | Safari on iOS in the iOS Simulator or on a device, top-level document | focus routes, keyboard shown and hidden, page panned and pinch-zoomed, a sheet moved, in Safari and as a home-screen app | The page lurches, the field ends under the keyboard, or the height is wrong after a pan or zoom |
-| FR2–FR5, FR8 | Release gate: physical devices in a top-level document (DEC-3) | iPhone Safari with the toolbar expanded and collapsed; iPhone home-screen app; Firefox for Android (FR2–FR5); Android Chrome with Gboard and Samsung Keyboard at the phone's refresh rate | The page lurches, the field ends under the keyboard, or the surface does not follow the keyboard |
+| Contract | Verification | Representative states | Mutation or failure expectation |
+| ------------ | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| FR1 | Source boundary check over Core and Lab plus a shared test that drives one keyboard change | each listed consumer; a new keyboard-aware component | Two components reading different heights for one keyboard, or a component measuring by a rule other than FR2 |
+| FR2 | Module tests driving visual-viewport resize and scroll events | keyboard shown; hidden; page panned with the keyboard shown; offset without a keyboard; page pinch-zoomed with and without the keyboard | A pan that lowers the reported height, or a height when no keyboard is shown |
+| FR3 | Consumer tests of computed layout, plus a public-surface check | keyboard shown and hidden; composer, bottom search field, tab bar search, Tall sheet; no animation running; a ride animation running with the composer, a scroll view, and a header together | A consumer whose layout ignores the height, layout that is only correct after an animation, riding surfaces out of sync on one keyboard change, per-frame layout work during a ride, content hidden or unscrollable at the resting value, or a public CSS custom property, export, or prop for the height |
+| FR4 | Focus-route tests with document scroll spies | tap, previous and next buttons, Tab, programmatic focus, Done then tap, app resume while scroll-locked | A route that scrolls the document, or a slipped scroll left in place |
+| FR5 | Surface move tests | sheet drag between heights, drag to dismiss, close, with a focused field | The field stays focused after a move starts, or content jumps on the first frame |
+| FR6 | Capability tests with the user agent varied | visual viewport shrinking with a fixed layout viewport; Chrome on Android reporting keyboard geometry; a desktop browser with the API and no on-screen keyboard; a page that is not a secure context; neither | Behavior that changes with the user agent alone, or a height taken from the browser's keyboard geometry report instead of FR2's measurement |
+| FR7 | Tests in an iframe and in a top-level document | the same keyboard event sequence in both | A non-zero value or a claimed focus inside an iframe |
+| FR8 | Chrome on Android in the emulator with Gboard, top-level document, plus a consumer documentation check | keyboard show and hide with the composer and a Tall sheet; a Lab bottom search field; reduced motion on; focus inside a keyboard-aware field, which rides by the visual-viewport height; an app with `interactive-widget=resizes-content`, focus inside and outside keyboard-aware fields, where a field's keyboard height is 0 | A Core surface jumping after the keyboard settles, lagging the keyboard by more than a frame, left under the keyboard, moved by JavaScript per frame, or committing layout more than once; a Lab surface riding instead of committing at rest; anything travelling with the keyboard under reduced motion instead of DR2's cross-fade; the app's viewport setting overridden; a keyboard-aware field not riding by the visual-viewport height, or adding an offset under `interactive-widget=resizes-content`; or the setting missing from the docs |
+| FR8 | Firefox for Android, emulator or device, top-level document | focus routes, keyboard shown and hidden, page panned and pinch-zoomed, a sheet moved | The page lurches, the field ends under the keyboard, or the height is wrong after a pan or zoom |
+| FR2–FR5 | Safari on iOS in the iOS Simulator or on a device, top-level document | focus routes, keyboard shown and hidden, page panned and pinch-zoomed, a sheet moved, in Safari and as a home-screen app | The page lurches, the field ends under the keyboard, or the height is wrong after a pan or zoom |
+| FR2–FR5, FR8 | Release gate: physical devices in a top-level document (DEC-3) | iPhone Safari with the toolbar expanded and collapsed; iPhone home-screen app; Firefox for Android (FR2–FR5); Android Chrome with Gboard and Samsung Keyboard at the phone's refresh rate | The page lurches, the field ends under the keyboard, or the surface does not follow the keyboard |
## Decision log
@@ -220,11 +224,13 @@ Rejected: each component measuring the keyboard by its own rule and predicting i
People on Android should see the same smooth keyboard motion as on iPhone: a
surface that jumps once the keyboard has finished, or sits under it while it
moves, feels broken. So keyboard-aware surfaces ride the keyboard's slide on
-show and hide in Chrome on Android too, while the app's own viewport setting
-stays in charge everywhere else. The mechanism is left to the implementation;
-this record states only the motion and its limits.
+show and hide in Chrome on Android too, by the visual-viewport height
+(DEC-4), and the app's own viewport setting stays in charge: where the app
+sets `interactive-widget=resizes-content`, the browser already makes the room
+and those surfaces have nothing to ride. The mechanism is left to the
+implementation; this record states only the motion and its limits.
-Rejected: a one-step relayout that jumps after the keyboard settles; and overriding the app's viewport setting outside keyboard-aware fields.
+Rejected: a one-step relayout that jumps after the keyboard settles; and overriding the app's viewport setting.
### DEC-3 — Simulators gate merge; physical phones gate release
@@ -240,6 +246,21 @@ real devices.
Rejected: physical devices as a merge gate, which blocks work on hardware; and physical devices as optional follow-up, which can ship untested keyboard behavior.
+### DEC-4 — The keyboard height comes from the visual viewport in every browser
+
+**Reference:** `spec:AST-099/DEC-4`
+**Decider:** `cixzhang`, `2026-10-25`
+
+In Chrome on Android the visual viewport shrinks for the keyboard as the
+keyboard starts to slide, so FR2's measurement reaches the page in time for
+surfaces to join the slide within a frame, and reading it changes nothing on
+the page. The browser's own keyboard geometry report needs the page to overlay
+the keyboard, arrives later and less steadily, and in Chromium hides the
+bottom toolbar on the keyboard's frame, which moves the layout. One
+measurement in every browser also keeps FR1's single height.
+
+Rejected: the browser's keyboard geometry report as the height, which arrives later and less steadily and shifts the layout.
+
## Open questions
None.