The decision in one paragraph
Keep the app a single web document whose history is the only truth. Add native transitions as primitives the page asks for: motion (snapshot the screen, fly 2–3 native layers) and stack (a native back gesture driving cached snapshots of earlier pages). The page decides when and how, from route rules shipped in its own signed bundle, so every rule, timing and kill switch updates over the air. A host without the extension, a browser or a TV simply runs the web fallback through the same API. We do not copy Hotwire's native navigation stack or its natively parsed path configuration; both exist to serve Turbo, which we don't use. Run the web-only rungs first: our own controls say the WebView can hold 120 fps, so native motion has to earn its place.
What Hotwire Native does, and what we take
Hotwire Native (Basecamp's WebView shell) has one idea at its core: "Content is all web. Navigation is all native" (how it works). Before leaving a page it screenshots it (Session.swift:128), moves its single web view into the next native screen (Session.swift:114), and lets UINavigationController animate and swipe back over the screenshot. Rules for which URL opens how live in a versioned JSON *path configuration*, bundled and refreshed from the server (docs).
| Hotwire mechanism | Verdict | Why |
|---|---|---|
Screenshot before leaving a page (snapshotView on iOS, VisitableView.swift:142; PixelCopy on Android, HotwireViewScreenshotHolder.kt:44) | take | the cheapest way to give native code something to animate |
Free-memory check before each capture (hasEnoughMemory) | take as is | a full 1080p ARGB frame is about 8.3 MB |
| Rule cascade: last match wins, plus a named fallback for older apps (path configuration) | take the shape | proven, readable, versionable |
| Native navigation stack, one web view re-parented between screens | reject | built for Turbo page visits. For a single-page app it creates a second back stack to keep in sync with history |
| Path configuration parsed by native code | reject | rules interpreted in the page are fully OTA. Native only executes primitives with explicit parameters |
| Bridge Components (web declares, native renders) | already have it | a kwry island is exactly this. Ship named islands when a screen needs one, not a generic layer |
Architecture
any web app (Solid, React, plain JS, SSR multi-page)
│ nav.go(href, { from: cardEl }, () => router.navigate(href))
▼
packages/nav (TS, framework-free) ◄── rules JSON in the signed bundle
• match route → transition + params + /.well-known/kwry-nav.json (kill switch)
• decide native vs web BEFORE the tap (from hello)
• begin → run router → wait for paint → commit
• fallback: View Transitions / CSS / none
│ typed JSON-RPC (generated client)
▼
contracts/nav (Kotlin, common) @Island("motion") @Island("stack")
│ generated dispatch
├── kwry-nav-android : PixelCopy · overlay layers · predictive back · postVisualStateCallback
├── kwry-nav-apple : snapshotView · CALayer flight · edge-pan recognizer
└── (no artifact) : TV, macOS, Windows, Linux, Vega → island absent → web fallbackOpt-in uses what kwry already has
- Host: add the island rows to
KwryApp.entries, "one+per island" (README). No change tokwry-core, which stays its five files. - Page: a missing island is
nullon the client, and Hoichoi already wraps that ashostIsland/hostAdvertises(islands.ts:12-19). - New kinds later: behind
@Capabilityfields, which the client refuses withUNSUPPORTEDbefore sending on an older host. - Grant: trusted only. A partner page or embed must never be able to cover the screen.
How a third-party site adopts it
- Host: add
kwry-nav-android/kwry-nav-appleand the two island rows. - Page: load
packages/nav, callnav.install({ rules }). - Markup only:
data-kwry-transition="card"on the tapped element,data-kwry-heroon the destination. No framework required. - Single-page app:
begin→ router →commit, all in one document. - Multi-page site: each navigation is a new document, so the host holds the overlay across the swap and commits on the new page's
app.ready(the gate already re-arms per navigation,Host.kt:39-41).
Navigation model
| Option | Verdict | Why |
|---|---|---|
| Hotwire: native stack, one web view moved between screens | reject | it restores screens through Turbo's restoration ids (Session.swift:148-153); we have no Turbo, and a single-page app would carry two back stacks |
| One WebView per screen | reject | each is its own document, bridge and hello; app state isn't shared; memory falls hardest on low-RAM TVs. Hotwire itself uses a second web view only for modals |
| Single document + native transitions | adopt | matches kwry's existing rule that the host keeps no back chain of its own. Web history stays the truth; snapshots are a disposable cache |
Changes this forces
- Android predictive back: today one always-on callback asks the page after the press (
KwryActivity.kt:78-80). A predictive gesture needs the answer before it starts, so the page must pushcanPopahead of time throughstack.sync. - iOS swipe-back: the base controller deliberately has no native gesture and disables WebKit's (
KwryViewController.kt:18-21,:117-121). The extension adds its own edge recognizer and must never re-enable WebKit's. - iOS web content process crash: the base controller has no handling for it; the extension tears its overlay down itself. Android already recreates the activity.
Failure modes that stay harmless
- State loss: none new. A missing snapshot degrades to the web close animation.
- Back-stack sync: the page already tags history entries with a depth (
details-open-anim.ts:719-723); snapshots are keyed by that entry and all dropped on clear-history. - Deep links have no source element, so no flight; the page already handles that case.
- Memory: cap the snapshot depth and check free memory first, as Hotwire does.
What updates over the air
| Changes without a store release | Needs a host release |
|---|---|
| which routes transition, and which kind | a new transition kind (new layer choreography) |
| durations, easing, corner radius, dim | a new gesture |
| per-platform enable or disable, the fallback choice | a new native component |
kill switch, and blocking one broken host version (denyHosts) | changes to how the snapshot is taken |
Rules ship inside the signed web bundle, which brings signature checks and automatic rollback when a new bundle fails to call ready (bundle.md). shell-policy.json is the wrong carrier: its schema is frozen additive-only, it covers only android, androidtv and ios, and it's read once at launch with a 2 s timeout. A small /.well-known/kwry-nav.json, fetched by the page with a short cache, is the fast kill switch. Every method carries @Since; new behaviour is a new method, never an edit (guide).
Contract sketch
@Island("motion", doc = "Snapshot-overlay flights. The page owns layout; the host animates 2-3 layers.")
interface MotionApi {
/** Freezes the screen. Says what the host actually got, so the page can skip a blind flight. */
@Method(userInitiated = true, deadlineMs = 300) @Since(TAG)
suspend fun begin(p: MotionBegin): MotionBegun // {id, frozen: FROZEN | LIVE | REFUSED}
/** Final layout is in the DOM. The host waits for its own paint signal, then flies. */
@Method(kind = Kind.NOTIFICATION) @Since(TAG) suspend fun commit(p: MotionCommit) // {id, to: Rect?, toRadius}
@Method(kind = Kind.NOTIFICATION) @Since(TAG) suspend fun cancel(p: MotionId)
@Observation(Mode.LOSSLESS, window = 8) @Since(TAG)
suspend fun events(p: MotionEventsParams): LosslessOut<MotionEvent> // ended | timedOut | cancelled(reason)
}
@Island("stack", doc = "Web history is the truth; the host caches snapshots and drives the back gesture.")
interface StackApi {
@Method(kind = Kind.NOTIFICATION) @Since(TAG) suspend fun sync(p: StackState) // {entryKey, depth, canPop}
@Observation(Mode.LOSSLESS, window = 8) @Since(TAG)
suspend fun pops(p: PopsParams): LosslessOut<PopEvent> // began | progress | committed(entryKey) | cancelled
}
// MotionBegin = {kind: PUSH | CARD | FADE, from: Rect?, fromRadius, durationMs, easing, dim}// Page side: one call per navigation. client.motion == null (browser, TV, old host) → web fallback, same API.
const nav = await createNav(client, rules)
await nav.go(href, { from: cardEl }, () => router.navigate(href)){ "version": 1, "enabled": true,
"denyHosts": [{ "platform": "android", "appVersion": "4.2.0" }],
"rules": [
{ "match": "^/(movies|shows)/", "transition": "card", "back": "swipe", "fallback": "view-transition",
"params": { "durationMs": 350, "easing": "standard", "dim": 0.4 },
"platforms": { "androidtv": { "transition": "none" } } }
] }
// Last match wins (Hotwire's cascade). Unknown transition → its fallback. Unknown keys are ignored.Every platform
| Platform | Snapshot | Flight | Gesture back | Default |
|---|---|---|---|---|
| Android phone | PixelCopy, async (about one frame) | yes | predictive back | native |
| Android TV | same API | no | none (remote) | web fallback; overlays never take focus |
| iOS | snapshotView(afterScreenUpdates:false), synchronous | yes | edge pan | native |
| iPadOS | same | yes | edge pan | native; a resize mid-flight cancels |
| macOS, Windows (WebView2), Linux (WebKitGTK) | async (unverified, no source) | no | none | web fallback |
| Amazon Vega (Kotlin/JS) | none; the React Native shell owns the WebView (kmp-targets.md) | no | none | web fallback |
| Plain browser | none | View Transitions or CSS | browser's | web fallback |
Hoichoi's route motion already loads only in the app runtime, so desktop web and TV never fetch or evaluate it (route-motion.ts:1-3); packages/nav keeps that rule.
Holes the review found in the first draft
Could make it pointless or worse
- It may solve a solved problem. The open now animates only transform and opacity on the compositor and starts in the tap's own task (
details-open-anim.ts:1-11), and route changes already usestartViewTransition(route-motion.ts:258). The October Fold numbers predate that, so step 0 re-measures. - Tap-to-first-frame gets worse: a bridge round trip plus an async
PixelCopybefore anything moves. The flight-only measurement hides it; measure it separately. - "Two rAFs" doesn't prove paint. On Android use
postVisualStateCallback, which kwry already uses with an 800 ms cap (KwryActivity.kt:132-139). iOS has no public equivalent (unverified), so its destination frame can be stale. - Card to hero needs destination pixels: a crop of the source scales up blurry, and a second snapshot is another async copy.
Must be designed in from day one
- Video and DRM: the player draws on a
SurfaceViewunder the WebView (PlayerSurface.kt:25-30) and the window turns onFLAG_SECUREduring playback (PlayerWindow.kt:26).beginrefuses while either is active. - Accessibility: the overlay is hidden from screen readers, a screen-changed notice is posted at the end, and reduce-motion skips the flight.
- Input mid-flight: a second tap or Back means
cancel, then reveal the live page. The timeout reveal cross-fades rather than cutting to a half-rendered page. - Stale snapshots: theme, text size, rotation or fold posture changes drop every cached snapshot and cancel a flight in progress. Blur the focused input before
begin. - Decide before the tap: if
beginmisses its deadline, the page has already skipped its CSS animation. Native-or-web is chosen from the hello, never after a failed call. - Sheets with web content need a second WebView. Deferred until a real screen needs one.
Spike plan
Ordered steps; each one either stops the work or earns the next. Measure on the Fold with the existing rig: a CDP-driven tap plus dumpsys gfxinfo framestats, counting only frames in the first 500 ms after the tap, and record host CPU and memory pressure before every run. Pass lines are proposals set against the native app's measured p95 of 15 ms.
0 · Re-measure both baselines
No code. Today's WebView open (compositor-driven since October) and the native app, on the same Fold, same rig.
Pass: both reproduce within run-to-run noise. Kill: they don't; fix the rig before anything else.1 · Flatten the open, web only
Cut the open to a few transform layers with no offscreen passes; pre-decode the poster; warm the shaders the open uses before the tap.
Pass: flight p95 ≤ 16.7 ms with no dropped frames, and native motion for the open stops here. Kill: p95 > 33 ms after flattening; go to step 2.2 · Card to hero with View Transitions
Extend route-motion.ts, which already calls startViewTransition, to name the card and hero as a shared element.
3 · Android native flight (no contract yet)
Hard-wired in the Hoichoi host: PixelCopy, 2–3 overlay layers, commit on postVisualStateCallback. Also run with a player surface and FLAG_SECURE active.
4 · iOS snapshot and swipe-back
Synchronous snapshotView, an edge-pan recognizer driving the previous page's snapshot, cancel restoring the live page.
5 · Back-stack torture test
500 random push, pop, deep-link and clear-history steps, checking the snapshot key against the history entry at every step.
Pass: zero mismatches. Kill: any wrong snapshot shown.6 · Contract and graceful degrade
Move steps 3–4 behind contracts/nav. Run new web on a host without the islands, with enabled: false, and with denyHosts matching. Confirm an app's contract can list islands from another Gradle module (not yet verified).
7 · Adversarial matrix
Screen reader on, rotation and fold mid-flight, theme flip, web content process killed mid-flight, low memory.
Pass: no stuck overlay in any case. Kill: a stuck overlay that the timeout doesn't clear.8 · External adopter
kwry's own samples/todo, which navigates across documents (Contract.kt:41-44): the host holds the overlay across the document swap until app.ready.
kwry-core.9 · TV, desktop, Vega
Package installed, islands absent.
Pass: no behaviour change and no extra code evaluated. Kill: any regression.Ideas from other frameworks
| Framework | Idea | Verdict |
|---|---|---|
| Hotwire Native | memory check before capture; last-match-wins rules with a named fallback; snapshot on leaving a page | take |
| Expo Router / react-native-screens | the system owns the back gesture; the app only supplies content (unverified, from memory) | take, as the stack island's model |
| Ionic | swipe-back as a web gesture over two live pages (unverified, from memory) | this is the web fallback, and roughly what Hoichoi does today |
| Capacitor | plugin model with no transition primitive (unverified) | nothing to take |
| Tauri mobile | a single web view with no native navigation (unverified) | nothing to take |
How this plan was made method
kwry at c30fa1f (README, App.kt, Host.kt, the island and bundle guides, the Android and Apple base hosts), Hoichoi.SharedClientPlatform at a950df76e (shell-kwry ports, mweb motion, the player island), Hotwire Native iOS dbc4fc0, Android 56e02c8 and its docs site.
An independent architecture review by Claude Fable 5.2, briefed with the goal and the measured Fold numbers but not the conclusion. Its file and line citations were spot-checked against the code before this page was written. Claims about platform APIs that weren't read in code are marked unverified.
Nothing has been built or measured for this plan. Step 0 re-measures because the open animation changed after the October Fold readings.