Hoichoi client platform · kwry extension · spike plan

kwry motion: native transitions as an opt-in extension

Web content, native-feeling navigation: an opt-in kwry extension that gives any web app (Hoichoi or not, Solid or not, single-page or multi-page) native transitions and a native back gesture, while the rules and the look stay over-the-air updatable. This page sets out the architecture, what we take from Hotwire Native and what we leave, the contract, the platform matrix, and an ordered spike plan with pass and kill lines.

Plan by Claude (agent) with an independent architecture review by Claude Fable 5.2, from kwry c30fa1f, Hoichoi.SharedClientPlatform a950df76e, hotwire-native-ios dbc4fc0 and hotwire-native-android 56e02c8Public · every page in this group shares one access rule

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.

2motion · stack
New islands
0rides existing islands, grants, capabilities
New kwry-core code
Android · iOS · iPadOSeverything else: web fallback
Native on
new kinds onlyrules, timings, kill switch are OTA
Store release needed for

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 mechanismVerdictWhy
Screenshot before leaving a page (snapshotView on iOS, VisitableView.swift:142; PixelCopy on Android, HotwireViewScreenshotHolder.kt:44)takethe cheapest way to give native code something to animate
Free-memory check before each capture (hasEnoughMemory)take as isa 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 shapeproven, readable, versionable
Native navigation stack, one web view re-parented between screensrejectbuilt 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 coderejectrules interpreted in the page are fully OTA. Native only executes primitives with explicit parameters
Bridge Components (web declares, native renders)already have ita 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 fallback

Opt-in uses what kwry already has

  • Host: add the island rows to KwryApp.entries, "one + per island" (README). No change to kwry-core, which stays its five files.
  • Page: a missing island is null on the client, and Hoichoi already wraps that as hostIsland / hostAdvertises (islands.ts:12-19).
  • New kinds later: behind @Capability fields, which the client refuses with UNSUPPORTED before 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-apple and the two island rows.
  • Page: load packages/nav, call nav.install({ rules }).
  • Markup only: data-kwry-transition="card" on the tapped element, data-kwry-hero on 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

OptionVerdictWhy
Hotwire: native stack, one web view moved between screensrejectit 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 screenrejecteach 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 transitionsadoptmatches 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 push canPop ahead of time through stack.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 releaseNeeds a host release
which routes transition, and which kinda new transition kind (new layer choreography)
durations, easing, corner radius, dima new gesture
per-platform enable or disable, the fallback choicea 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

PlatformSnapshotFlightGesture backDefault
Android phonePixelCopy, async (about one frame)yespredictive backnative
Android TVsame APInonone (remote)web fallback; overlays never take focus
iOSsnapshotView(afterScreenUpdates:false), synchronousyesedge pannative
iPadOSsameyesedge pannative; a resize mid-flight cancels
macOS, Windows (WebView2), Linux (WebKitGTK)async (unverified, no source)nononeweb fallback
Amazon Vega (Kotlin/JS)none; the React Native shell owns the WebView (kmp-targets.md)nononeweb fallback
Plain browsernoneView Transitions or CSSbrowser'sweb 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 use startViewTransition (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 PixelCopy before 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 SurfaceView under the WebView (PlayerSurface.kt:25-30) and the window turns on FLAG_SECURE during playback (PlayerWindow.kt:26). begin refuses 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 begin misses 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.

Pass: same as step 1, with tap-to-first-frame no worse. Kill: no gain over step 1, or the browser's capture adds more than a frame.
↓

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.

Pass: flight p95 ≤ 16.7 ms and tap-to-first-frame no worse than steps 1–2. Kill: the first frame arrives more than one frame later than the web path, or snapshots are unusable beside video.
↓

4 · iOS snapshot and swipe-back

Synchronous snapshotView, an edge-pan recognizer driving the previous page's snapshot, cancel restoring the live page.

Pass: no hitch in 50 runs in Instruments; the gesture tracks the finger; cancel is clean. Kill: a stale destination frame is visible on commit.
↓

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

Pass: all three fall back with no error. Kill: the extension islands can't live outside the app's own contract module.
↓

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.

Pass: works with no Solid and no Hoichoi code. Kill: it needs changes in 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

FrameworkIdeaVerdict
Hotwire Nativememory check before capture; last-match-wins rules with a named fallback; snapshot on leaving a pagetake
Expo Router / react-native-screensthe system owns the back gesture; the app only supplies content (unverified, from memory)take, as the stack island's model
Ionicswipe-back as a web gesture over two live pages (unverified, from memory)this is the web fallback, and roughly what Hoichoi does today
Capacitorplugin model with no transition primitive (unverified)nothing to take
Tauri mobilea 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.