SSR and hydration
Imports and server renders do not read browser globals. The server snapshot stays stable with ready: false; render a geometry-neutral placeholder until the first client measurement.
Hydration uses that same snapshot before subscribing to the selected window. The browser matrix fails on any console error or uncaught page error, not only messages containing the word hydration.
Performance model
Subscribers share one store, listener set, and safe-area probe per window. Browser events are coalesced into one animation-frame measurement, and unchanged scalar snapshots do not notify React.
CSS-variable updates subscribe directly to the store. No throughput or CPU benchmark is claimed for this alpha; the evidence covers lifecycle sharing and event batching.
Factual comparison
| Approach | Provides | Boundary |
|---|---|---|
| CSS viewport units | Layout sizing with dvh, svh, and lvh without JavaScript. | No React state, viewport offsets, page coordinates, or keyboard classification. |
| Direct VisualViewport | Native visible-region size, offsets, page coordinates, scale, and events. | No shared React subscription, safe-area measurement, or keyboard policy. |
| Direct VirtualKeyboard | Native keyboard bounding geometry where the browser exposes the API. | Availability is limited; consumers still own subscription and intersection logic. |
| This library | One React snapshot combining layout, visual, keyboard, safe-area, and support state. | Fallback keyboard inference is conservative and physical-device QA remains required. |
Frequently asked questions
Does focus mean the keyboard is open?
No. Without native geometry, focus only enables an evidence gate. Reported height is the current layout-bottom occlusion and must also cross the configured threshold.
When will safe-area values be non-zero?
The page must opt into viewport-fit=cover, and the device/browser must expose non-zero env(safe-area-inset-*) values.
Can multiple hooks target one element?
Yes. Property ownership is coordinated; the last-mounted live owner supplies values, and consumer styles are restored only after the final owner leaves.
Limitations
- Floating or split keyboards may expose no bottom occlusion.
- Small keyboards may remain below the conservative fallback threshold.
- Browser chrome and keyboard animation fidelity require physical devices.
- Embedded WebViews vary with host configuration.
- Foldable segments and synthetic keyboard animation are outside v1.