Restore native scrolling and reliable recognition; add feel tests

The previous round regressed the demo against main: dropped frames while a finger drags, and swipes ignored when they start imperfectly. Frame drops: hosts used touch-action: manipulation plus a blocking touchmove listener, so Chrome waited for JavaScript on every touch move (~30% of frames over 20ms in a drag, p95 28ms). Hosts again use per-axis touch-action like main (pan-y for horizontal gestures, and so on), and attach no touch listener. Flaky recognition: an irreversible decision after 6px dropped swipes with a wobbly or backward start. Recognition again measures from the pointer-down point until the pointer lifts, as on main. Scrolling beside gestures, natively: - .from.scrollEdge() uses direction-specific touch-action while its scroller is at the edge (pan-x pan-down for drag-down at the top), the pull-to-refresh pattern from the Pointer Events spec. A passive scroll listener keeps it current; no touch handling blocks the browser. - Where directional values are unsupported (Safari), scroll-edge gestures alone fall back to claiming touches at the browser's first cancelable touchmove. - Hosts publish touch-action as --nvo-touch-action and the stylesheet applies it to descendants, so nested scroll containers keep it and horizontal swipes over lists are not cancelled. Ignored subtrees get touch-action: auto back. - Bindings gain listeners and ref (spread on the host); the components use them. Feel tests (npm run test:feel): Chromium with emulated touch checks recognition on ten human-like traces, frame pacing budgets while dragging (p95 <= 20ms, <= 5% over 20ms) for a swipe and a scroll-edge dismiss, and the behaviour checks. Against the previous code they fail on exactly the reported regressions; now 23/23 pass. On the demo, all traces match main and drag frame pacing matches or beats it. Commit thresholds are unchanged (0.25 distance, 0.2 flick). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Faarh2Ts6StJPcz2mRiHiR
Make gestures cooperate with scrolling and feel smoother
2026-11-03 05:56:26 +00:00 · 2026-10-31 08:22:11 +00:00 · 2026-10-31 05:41:51 +00:00 · 2026-10-16 04:28:43 +00:00 · 2026-10-16 04:24:47 +00:00 · 2026-10-16 04:10:53 +00:00
173 changed files with 27548 additions and 2137 deletions
@@ -27,3 +27,5 @@ apps/demo/dev-dist
 *.njsproj
 *.sln
 *.sw?
+
+docker-compose.yml
@@ -4,12 +4,61 @@ Native Vue Router is a gesture-first navigation runtime for Vue 3 and Vue Router

 The repository includes a reusable headless core, a platform-adaptive visual preset, Capacitor and Electron adapters, and one messaging demo delivered as a PWA and through native hosts.

+## Install the routeless core-v2 experiment
+
+The repository root is an installable facade for
+`@native-vue-router/core-v2`. npm builds the package from source when it installs
+the Git dependency:
+
+```bash
+npm install git+https://git.harvmaster.com/Harvmaster/Native-Router-Vue.git
+```
+
+Import it by its package name and include the compositor stylesheet:
+
+```ts
+import {
+  OriginScene,
+  createOriginScene,
+  gesture,
+  originView,
+} from "@native-vue-router/core-v2";
+import "@native-vue-router/core-v2/style.css";
+```
+
+Pin production applications to a commit or tag:
+
+```bash
+npm install "git+https://git.harvmaster.com/Harvmaster/Native-Router-Vue.git#<commit-or-tag>"
+```
+
+Core-v2 is routeless and does not depend on Vue Router. Its usage guide and API
+are in [packages/core-v2/README.md](packages/core-v2/README.md) and
+[packages/core-v2/API.md](packages/core-v2/API.md).
+
+### Codex skill
+
+The Git package also includes
+[`build-with-native-vue-router-v2`](skills/build-with-native-vue-router-v2/SKILL.md),
+a Codex skill for creating and integrating routeless core-v2 applications.
+After installing the dependency, copy the skill into Codex's skill directory:
+
+```bash
+mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
+cp -R \
+  node_modules/@native-vue-router/core-v2/skills/build-with-native-vue-router-v2 \
+  "${CODEX_HOME:-$HOME/.codex}/skills/"
+```
+
+Restart or reload Codex if necessary, then invoke it explicitly with
+`$build-with-native-vue-router-v2`.
+
 ## What works

 - Interactive edge pop that can be held indefinitely at any progress.
 - Ordered horizontal route paging with replace-by-default history.
 - Component-originated route dragging with a live target route.
- Interactive push, adjacent-page sibling slide, modal, sheet, fade, and application-defined presentations.
+- Interactive push, adjacent-page sibling slide, modal, safe-area-contained content/snap-point sheets with scroll-boundary handoff, fade, and application-defined presentations.
 - Concurrent `from` and `to` routes using only public Vue Router 5 APIs.
 - Guarded commits: previews do not alter the URL, and rejected navigation springs back.
 - Cold-start predictive back through declared parent routes.
@@ -39,38 +88,44 @@ Native projects live under `apps/capacitor/ios` and `apps/capacitor/android`. Op

 Run the normal `npm run dev` command, expose its printed network address through an HTTPS URL, and open that URL on the iPhone. The development server includes the PWA service worker and already listens on the local network. Safari still requires a secure context for the service worker; a plain LAN `http://` address is not sufficient. Choose **Share → Add to Home Screen**, then launch **NVR Messenger** from its Home Screen icon.

-The Navigation Lab reports `Standalone`, `ready`, and `App reserved` when the correct environment is active. Open a conversation and drag from the extreme left edge. The “Leading-edge touches claimed” counter should increment while the router renders its live predictive-back view.
+The Navigation Lab reports `Standalone`, `ready`, and `App reserved` when the correct environment is active, and shows the exact build ID plus update-check count. Production builds check for updates whenever the app starts, returns to the foreground, regains connectivity, or has been open for a minute; activation reload waits for any live gesture to finish. Open a conversation and drag from the extreme left edge. The “Leading-edge touches claimed” counter should increment while the router renders its live predictive-back view.
+
+For more aggressive lifecycle testing, open **You → Runtime stress lab**. It is a deeper route that keeps the primary tab bar, opts into push-style sibling history, exposes its mount lifetime, and renders a one-second async child through `<Suspense>`. Backing out evicts this pushed screen after its exit; browser Forward reconstructs it and shows the fallback again. To exercise a guard against an already-mounted destination, visit **Stories**, switch to **You**, enable **Block cached Stories re-entry**, and try returning to Stories. The guard rejects and evicts the cached view.

 An installed web app cannot access `WKWebView.allowsBackForwardNavigationGestures`. The demo therefore reserves leading-edge touch sequences at the web-content boundary as an iOS standalone-only safeguard. Capacitor remains the deterministic option when native-level gesture suppression is required.

 ## Minimal integration

 ```ts
-import { createApp } from 'vue'
-import { createRouter, createWebHistory } from 'vue-router'
-import { createNativeRouter } from '@native-vue-router/core'
+import { createApp } from "vue";
+import { createRouter, createWebHistory } from "vue-router";
+import { createNativeRouter } from "@native-vue-router/core";

 const router = createRouter({
  history: createWebHistory(),
  routes: [
-    { path: '/', component: Home },
+    { path: "/", component: Home },
    {
-      path: '/chat/:id',
+      path: "/chat/:id",
      component: Chat,
      meta: {
-        native: { presentation: 'push', parent: '/', gesture: 'edge' },
+        native: { presentation: "push", parent: "/", gesture: "edge" },
      },
    },
  ],
-})
+});

-const nativeRouter = createNativeRouter({ router })
-createApp(App).use(router).use(nativeRouter).mount('#app')
+const nativeRouter = createNativeRouter({ router });
+createApp(App).use(router).use(nativeRouter).mount("#app");
 ```

 ```vue
 <script setup lang="ts">
-import { NativeGestureLink, NativeNavigator, NativeRouterView } from '@native-vue-router/core'
+import {
+  NativeGestureLink,
+  NativeNavigator,
+  NativeRouterView,
+} from "@native-vue-router/core";
 </script>

 <template>
@@ -87,6 +142,31 @@ Import `@native-vue-router/core/style.css` for the built-in presentation layers.

 Use `nativeRouter.sibling(to)` for tab or peer-route navigation. Direction is derived from `siblingOrder`, repeated navigation to the active route is a no-op, and `siblingHistory: 'replace'` keeps cached tab views out of the back stack.

+Sibling views are lazy rather than pre-mounted: only the initial route exists on startup, and a sibling joins the bounded cache on its first visit or interactive preview. Route metadata accepts `cache: false` to opt out or `cache: 'pin'` for views that must survive ordinary trimming. `useNativeViewLifecycle()`, the `onNativeView*` hooks, and `useNativeViewActiveEffect()` let cached screens pause polling, media, or subscriptions while retaining their local UI state.
+
+Call `nativeRouter.unload('/some-route')` to manually unmount inactive instances of one location while retaining their lightweight history descriptors. The active route and views participating in a transition are protected.
+
+### Capture frame pacing on a real device
+
+The Navigation Lab contains an opt-in profiler. Tap **Start profiling**, leave the lab, reproduce the choppy navigation once or twice, return to the lab, tap **Stop**, then **Share JSON**. Installed iOS PWAs use the system share sheet; other browsers download the file. Attach that JSON to a bug report.
+
+The core API is also available directly:
+
+```ts
+import { createNativeNavigationProfiler } from "@native-vue-router/core";
+
+const profiler = createNativeNavigationProfiler(nativeRouter, {
+  metadata: { build: import.meta.env.VITE_BUILD_ID },
+});
+
+profiler.start();
+// Reproduce the navigation issue.
+const report = profiler.stop();
+const json = profiler.toJSON(report);
+```
+
+No rAF loop or browser performance observer runs before `start()`, and `stop()` removes them. Reports contain frame intervals, refresh-rate estimates, per-navigation timing, cold-mount preparation, route loading, cache eviction, visibility changes, and browser-supported Long Task/layout-shift/resource timing. Route params, query values, and application state are omitted.
+
 ## Packages

 - `@native-vue-router/core` — transactions, route ledger, concurrent views, gestures, caching, and public components/composables.
@@ -94,7 +174,14 @@ Use `nativeRouter.sibling(to)` for tab or peer-route navigation. Direction is de
 - `@native-vue-router/capacitor` — hardware back, deep links, pause cancellation, root exit, and haptics.
 - `@native-vue-router/electron` — Chromium history-gesture suppression and renderer back/forward bridging.

-See [architecture](docs/architecture.md) and [platform integration](docs/platforms.md) for the transaction lifecycle and host-specific behavior.
+Design and engineering documentation:
+
+- [Complete installation and usage guide](usage.md)
+- [How it works and why the pattern is uncommon](docs/how-it-works.md)
+- [Engineering challenges, Vue Router limitations, and trade-offs](docs/challenges-and-tradeoffs.md)
+- [Core principles, scalability, and flexibility](docs/principles-and-scalability.md)
+- [Architecture reference](docs/architecture.md)
+- [Platform integration reference](docs/platforms.md)

 ## Support contract

@@ -1,21 +1,21 @@
-import type { CapacitorConfig } from '@capacitor/cli'
+import type { CapacitorConfig } from "@capacitor/cli";

 const config: CapacitorConfig = {
-  appId: 'dev.nativevuerouter.messenger',
-  appName: 'Native Vue Messenger',
-  webDir: '../demo/dist',
-  backgroundColor: '#0b0d12',
+  appId: "dev.nativevuerouter.messenger",
+  appName: "Native Vue Messenger",
+  webDir: "../demo/dist",
+  backgroundColor: "#0b0d12",
  plugins: {
    App: { disableBackButtonHandler: true },
    SplashScreen: {
      launchAutoHide: true,
-      backgroundColor: '#0b0d12',
-      androidScaleType: 'CENTER_CROP',
+      backgroundColor: "#0b0d12",
+      androidScaleType: "CENTER_CROP",
    },
-    StatusBar: { style: 'DARK', backgroundColor: '#0b0d12' },
+    StatusBar: { style: "DARK", backgroundColor: "#0b0d12" },
  },
-  android: { backgroundColor: '#0b0d12' },
-  ios: { backgroundColor: '#0b0d12', contentInset: 'never' },
-}
+  android: { backgroundColor: "#0b0d12" },
+  ios: { backgroundColor: "#0b0d12", contentInset: "never" },
+};

-export default config
+export default config;
@@ -1,85 +1,157 @@
-import { expect, test } from '@playwright/test'
+import { expect, test } from "@playwright/test";

-const iphoneUserAgent = 'Mozilla/5.0 (iPhone; CPU iPhone OS 18_5 like Mac OS X) AppleWebKit/605.1.15 Version/18.5 Mobile/15E148 Safari/604.1'
+const iphoneUserAgent =
+  "Mozilla/5.0 (iPhone; CPU iPhone OS 18_5 like Mac OS X) AppleWebKit/605.1.15 Version/18.5 Mobile/15E148 Safari/604.1";

-async function dispatchTouchStart(page: import('@playwright/test').Page, clientX: number) {
-  return await page.locator('.nvr-navigator').evaluate((element, x) => {
-    const event = new Event('touchstart', { bubbles: true, cancelable: true })
-    Object.defineProperty(event, 'touches', {
+async function dispatchTouchStart(
+  page: import("@playwright/test").Page,
+  clientX: number,
+) {
+  return await page.locator(".nvr-navigator").evaluate((element, x) => {
+    const event = new Event("touchstart", { bubbles: true, cancelable: true });
+    Object.defineProperty(event, "touches", {
      value: [{ identifier: 7, clientX: x, clientY: 240 }],
-    })
-    return { dispatched: element.dispatchEvent(event), prevented: event.defaultPrevented }
-  }, clientX)
+    });
+    return {
+      dispatched: element.dispatchEvent(event),
+      prevented: event.defaultPrevented,
+    };
+  }, clientX);
 }

-test('ships an installable standalone manifest and iOS metadata', async ({ page, request }) => {
-  await page.goto('/inbox')
-  await expect(page.locator('meta[name="apple-mobile-web-app-capable"]')).toHaveAttribute('content', 'yes')
-  await expect(page.locator('meta[name="apple-mobile-web-app-status-bar-style"]')).toHaveAttribute('content', 'black-translucent')
-  const touchIconPath = await page.locator('link[rel="apple-touch-icon"]').evaluate((link) =>
-    new URL(link.getAttribute('href') ?? '', document.baseURI).pathname,
-  )
-  expect(touchIconPath).toBe('/apple-touch-icon.png')
+test("ships an installable standalone manifest and iOS metadata", async ({
+  page,
+  request,
+}) => {
+  await page.goto("/inbox");
+  await expect(
+    page.locator('meta[name="apple-mobile-web-app-capable"]'),
+  ).toHaveAttribute("content", "yes");
+  await expect(
+    page.locator('meta[name="apple-mobile-web-app-status-bar-style"]'),
+  ).toHaveAttribute("content", "black-translucent");
+  const touchIconPath = await page
+    .locator('link[rel="apple-touch-icon"]')
+    .evaluate(
+      (link) =>
+        new URL(link.getAttribute("href") ?? "", document.baseURI).pathname,
+    );
+  expect(touchIconPath).toBe("/apple-touch-icon.png");

-  const manifestResponse = await request.get('/manifest.webmanifest')
-  expect(manifestResponse.ok()).toBe(true)
-  const manifest = await manifestResponse.json()
-  expect(manifest).toMatchObject({ id: '/', scope: '/', start_url: '/', display: 'standalone' })
-  expect(manifest.icons).toEqual(expect.arrayContaining([
-    expect.objectContaining({ src: '/pwa-192.png', sizes: '192x192', type: 'image/png' }),
-    expect.objectContaining({ src: '/pwa-512.png', sizes: '512x512', type: 'image/png' }),
-  ]))
-  expect((await request.get('/apple-touch-icon.png')).headers()['content-type']).toContain('image/png')
-  expect((await request.get('/sw.js')).ok()).toBe(true)
-})
+  const manifestResponse = await request.get("/manifest.webmanifest");
+  expect(manifestResponse.ok()).toBe(true);
+  const manifest = await manifestResponse.json();
+  expect(manifest).toMatchObject({
+    id: "/",
+    scope: "/",
+    start_url: "/",
+    display: "standalone",
+  });
+  expect(manifest.icons).toEqual(
+    expect.arrayContaining([
+      expect.objectContaining({
+        src: "/pwa-192.png",
+        sizes: "192x192",
+        type: "image/png",
+      }),
+      expect.objectContaining({
+        src: "/pwa-512.png",
+        sizes: "512x512",
+        type: "image/png",
+      }),
+    ]),
+  );
+  expect(
+    (await request.get("/apple-touch-icon.png")).headers()["content-type"],
+  ).toContain("image/png");
+  const workerResponse = await request.get("/sw.js");
+  expect(workerResponse.ok()).toBe(true);
+  expect(workerResponse.headers()["cache-control"]).toContain("no-cache");
+  const worker = await workerResponse.text();
+  expect(worker).toContain("self.skipWaiting()");
+  expect(worker).toContain("clientsClaim()");
+});

-test('does not interfere with Safari edge touches before Home Screen installation', async ({ page }) => {
+test("does not interfere with Safari edge touches before Home Screen installation", async ({
+  page,
+}) => {
  await page.addInitScript((userAgent) => {
-    Object.defineProperty(navigator, 'userAgent', { configurable: true, value: userAgent })
-    Object.defineProperty(navigator, 'standalone', { configurable: true, value: false })
-  }, iphoneUserAgent)
-  await page.goto('/chat/maya')
-  await expect(page.locator('html')).toHaveAttribute('data-pwa-display-mode', 'browser')
-  await expect(page.locator('html')).toHaveAttribute('data-pwa-edge-guard', 'inactive')
-  expect((await dispatchTouchStart(page, 1)).prevented).toBe(false)
-})
+    Object.defineProperty(navigator, "userAgent", {
+      configurable: true,
+      value: userAgent,
+    });
+    Object.defineProperty(navigator, "standalone", {
+      configurable: true,
+      value: false,
+    });
+  }, iphoneUserAgent);
+  await page.goto("/chat/maya");
+  await expect(page.locator("html")).toHaveAttribute(
+    "data-pwa-display-mode",
+    "browser",
+  );
+  await expect(page.locator("html")).toHaveAttribute(
+    "data-pwa-edge-guard",
+    "inactive",
+  );
+  expect((await dispatchTouchStart(page, 1)).prevented).toBe(false);
+});

-test('reserves only the leading edge in an installed iOS PWA', async ({ page }) => {
+test("reserves only the leading edge in an installed iOS PWA", async ({
+  page,
+}) => {
  await page.addInitScript((userAgent) => {
-    Object.defineProperty(navigator, 'userAgent', { configurable: true, value: userAgent })
-    Object.defineProperty(navigator, 'standalone', { configurable: true, value: true })
-  }, iphoneUserAgent)
-  await page.goto('/chat/maya')
-  const root = page.locator('html')
-  await expect(root).toHaveAttribute('data-pwa-platform', 'ios')
-  await expect(root).toHaveAttribute('data-pwa-display-mode', 'standalone')
-  await expect(root).toHaveAttribute('data-pwa-edge-guard', 'active')
+    Object.defineProperty(navigator, "userAgent", {
+      configurable: true,
+      value: userAgent,
+    });
+    Object.defineProperty(navigator, "standalone", {
+      configurable: true,
+      value: true,
+    });
+  }, iphoneUserAgent);
+  await page.goto("/chat/maya");
+  const root = page.locator("html");
+  await expect(root).toHaveAttribute("data-pwa-platform", "ios");
+  await expect(root).toHaveAttribute("data-pwa-display-mode", "standalone");
+  await expect(root).toHaveAttribute("data-pwa-edge-guard", "active");

-  expect((await dispatchTouchStart(page, 80)).prevented).toBe(false)
-  expect((await dispatchTouchStart(page, 1)).prevented).toBe(true)
-  await expect(root).toHaveAttribute('data-pwa-edge-claims', '1')
-})
+  expect((await dispatchTouchStart(page, 80)).prevented).toBe(false);
+  expect((await dispatchTouchStart(page, 1)).prevented).toBe(true);
+  await expect(root).toHaveAttribute("data-pwa-edge-claims", "1");
+});

-test('registers and activates the offline service worker', async ({ page }) => {
-  await page.goto('/inbox')
+test("registers and activates the offline service worker", async ({ page }) => {
+  await page.goto("/inbox");
  const workerUrl = await page.evaluate(async () => {
-    const registration = await navigator.serviceWorker.ready
-    return registration.active?.scriptURL ?? ''
-  })
-  expect(workerUrl).toMatch(/\/sw\.js$/)
-})
+    const registration = await navigator.serviceWorker.ready;
+    return registration.active?.scriptURL ?? "";
+  });
+  expect(workerUrl).toMatch(/\/sw\.js$/);
+  await expect(page.locator("html")).not.toHaveAttribute(
+    "data-pwa-update-checks",
+    "0",
+  );
+});

-test('precaches lazily split routes for offline navigation', async ({ page }) => {
-  await page.goto('/inbox')
-  await page.evaluate(async () => { await navigator.serviceWorker.ready })
+test("precaches lazily split routes for offline navigation", async ({
+  page,
+}) => {
+  await page.goto("/inbox");
+  await page.evaluate(async () => {
+    await navigator.serviceWorker.ready;
+  });
  const cachedUrls = await page.evaluate(async () => {
-    const urls: string[] = []
+    const urls: string[] = [];
    for (const name of await caches.keys()) {
-      const cache = await caches.open(name)
-      urls.push(...(await cache.keys()).map((request) => request.url))
+      const cache = await caches.open(name);
+      urls.push(...(await cache.keys()).map((request) => request.url));
    }
-    return urls
-  })
-  expect(cachedUrls.some((url) => /StoriesView-.*\.js$/.test(url))).toBe(true)
-  expect(cachedUrls.some((url) => /ProfileView-.*\.js$/.test(url))).toBe(true)
-})
+    return urls;
+  });
+  expect(cachedUrls.some((url) => /StoriesView-.*\.js$/.test(url))).toBe(true);
+  expect(cachedUrls.some((url) => /ProfileView-.*\.js$/.test(url))).toBe(true);
+  expect(cachedUrls.some((url) => /RuntimeLabView-.*\.js$/.test(url))).toBe(
+    true,
+  );
+});
@@ -4,14 +4,15 @@ import { NativeNavigator, NativeRouterView } from '@native-vue-router/core'
 import { NativeTabBar, type NativeTabItem } from '@native-vue-router/preset-native'
 import { useRoute } from 'vue-router'
 import PwaUpdate from './components/PwaUpdate.vue'
+import { profilerRecording } from './navigation-profiler'

 const route = useRoute()
-const siblingRoutes = ['/inbox', '/stories', '/profile']
+const siblingRoutes = ['/inbox', '/stories', '/profile', '/profile/runtime-lab']
 const showTabs = computed(() => Boolean(route.meta.tab))
 const tabs: NativeTabItem[] = [
  { label: 'Inbox', to: '/inbox', icon: '◉' },
  { label: 'Stories', to: '/stories', icon: '◎' },
-  { label: 'You', to: '/profile', icon: '◇' },
+  { label: 'You', to: '/profile', icon: '◇', activeWhen: (current) => current.path.startsWith('/profile') },
 ]
 </script>

@@ -21,6 +22,7 @@ const tabs: NativeTabItem[] = [
      <NativeRouterView />
    </NativeNavigator>
    <NativeTabBar v-if="showTabs" :items="tabs" class="app-tabs" />
+    <div v-if="profilerRecording" class="profiler-badge" aria-live="polite"><i /> Profiling navigation</div>
    <PwaUpdate />
  </div>
 </template>
@@ -0,0 +1,44 @@
+import { reactive, type InjectionKey, type Ref } from "vue";
+
+export interface CompatibilityLabEvent {
+  id: number;
+  timestamp: string;
+  source: string;
+  hook: string;
+  detail?: string;
+}
+
+export interface CompatibilityLabContext {
+  source: string;
+  routeLabel: Readonly<Ref<string>>;
+}
+
+export const demoAppValueKey: InjectionKey<string> = Symbol("demo-app-value");
+export const compatibilityLabContextKey: InjectionKey<CompatibilityLabContext> =
+  Symbol("compatibility-lab-context");
+
+let eventSequence = 0;
+const startedAt = performance.now();
+
+export const compatibilityLab = reactive({
+  events: [] as CompatibilityLabEvent[],
+});
+
+export function recordCompatibilityEvent(
+  source: string,
+  hook: string,
+  detail?: string,
+) {
+  compatibilityLab.events.unshift({
+    id: ++eventSequence,
+    timestamp: `${(performance.now() - startedAt).toFixed(0)} ms`,
+    source,
+    hook,
+    detail,
+  });
+  if (compatibilityLab.events.length > 120) compatibilityLab.events.splice(120);
+}
+
+export function clearCompatibilityEvents() {
+  compatibilityLab.events.splice(0);
+}
@@ -0,0 +1,16 @@
+<script setup lang="ts">
+const requestedAt = Date.now()
+await new Promise((resolve) => window.setTimeout(resolve, 3_000))
+const resolutionTime = Date.now() - requestedAt
+</script>
+
+<template>
+  <article class="lab-probe lab-probe--ready" data-testid="async-data-ready">
+    <span class="lab-probe__icon" aria-hidden="true">✓</span>
+    <div>
+      <strong>Async payload available</strong>
+      <p>Resolved {{ resolutionTime }} ms after this component mounted.</p>
+    </div>
+  </article>
+</template>
+
@@ -0,0 +1,39 @@
+<script setup lang="ts">
+import { inject } from "vue";
+import { useRoute } from "vue-router";
+import {
+  compatibilityLabContextKey,
+  demoAppValueKey,
+  recordCompatibilityEvent,
+} from "../compatibility-lab";
+
+const props = defineProps<{ requestId: number }>();
+const route = useRoute();
+const appValue = inject(demoAppValueKey, "missing app injection");
+const labContext = inject(compatibilityLabContextKey);
+
+recordCompatibilityEvent(
+  "Suspense",
+  "async setup started",
+  `request ${props.requestId}`,
+);
+await new Promise((resolve) => window.setTimeout(resolve, 750));
+recordCompatibilityEvent(
+  "Suspense",
+  "async setup resolved",
+  `request ${props.requestId}`,
+);
+</script>
+
+<template>
+  <article
+    class="compat-probe compat-probe--resolved"
+    data-testid="compat-suspense-ready"
+  >
+    <span class="compat-probe__badge">Suspense resolved</span>
+    <strong>Async request {{ requestId }} complete</strong>
+    <p>{{ appValue }}</p>
+    <p>{{ labContext?.routeLabel.value }}</p>
+    <p>{{ route.fullPath }}</p>
+  </article>
+</template>
@@ -0,0 +1,41 @@
+<script setup lang="ts">
+import {
+  onBeforeMount,
+  onBeforeUnmount,
+  onBeforeUpdate,
+  onMounted,
+  onUnmounted,
+  onUpdated,
+  ref,
+} from "vue";
+import { useRoute } from "vue-router";
+import { recordCompatibilityEvent } from "../compatibility-lab";
+
+const props = defineProps<{
+  instanceName: string;
+  revision: number;
+}>();
+const route = useRoute();
+const localCount = ref(0);
+const record = (hook: string) =>
+  recordCompatibilityEvent(props.instanceName, hook, route.fullPath);
+
+onBeforeMount(() => record("onBeforeMount"));
+onMounted(() => record("onMounted"));
+onBeforeUpdate(() => record("onBeforeUpdate"));
+onUpdated(() => record("onUpdated"));
+onBeforeUnmount(() => record("onBeforeUnmount"));
+onUnmounted(() => record("onUnmounted"));
+</script>
+
+<template>
+  <article class="compat-probe" data-testid="composition-lifecycle-probe">
+    <span class="compat-probe__badge">Composition API</span>
+    <strong>{{ instanceName }}</strong>
+    <p><code>useRoute()</code>: {{ route.fullPath }}</p>
+    <p>Revision {{ revision }} · local count {{ localCount }}</p>
+    <button type="button" @click="localCount += 1">
+      Increment local state
+    </button>
+  </article>
+</template>
@@ -0,0 +1,29 @@
+<script setup lang="ts">
+import { computed, inject } from "vue";
+import { useRoute } from "vue-router";
+import {
+  compatibilityLabContextKey,
+  demoAppValueKey,
+} from "../compatibility-lab";
+
+defineProps<{ location: "route tree" | "teleport" }>();
+
+const route = useRoute();
+const appValue = inject(demoAppValueKey, "missing app injection");
+const labContext = inject(compatibilityLabContextKey);
+const labValue = computed(
+  () => labContext?.routeLabel.value ?? "missing page injection",
+);
+</script>
+
+<template>
+  <article
+    class="compat-probe"
+    :data-testid="`inject-probe-${location.replace(' ', '-')}`"
+  >
+    <span class="compat-probe__badge">provide / inject · {{ location }}</span>
+    <strong>{{ appValue }}</strong>
+    <p>Page injection: {{ labValue }}</p>
+    <p>Scoped route: {{ route.fullPath }}</p>
+  </article>
+</template>
@@ -0,0 +1,36 @@
+<script setup lang="ts">
+import {
+  onActivated,
+  onBeforeMount,
+  onBeforeUnmount,
+  onDeactivated,
+  onMounted,
+  onUnmounted,
+  ref,
+} from "vue";
+import { recordCompatibilityEvent } from "../compatibility-lab";
+
+const props = defineProps<{ name: string }>();
+const count = ref(0);
+const record = (hook: string) =>
+  recordCompatibilityEvent(`KeepAlive ${props.name}`, hook);
+
+onBeforeMount(() => record("onBeforeMount"));
+onMounted(() => record("onMounted"));
+onActivated(() => record("onActivated"));
+onDeactivated(() => record("onDeactivated"));
+onBeforeUnmount(() => record("onBeforeUnmount"));
+onUnmounted(() => record("onUnmounted"));
+</script>
+
+<template>
+  <article
+    class="compat-probe compat-probe--keepalive"
+    :data-testid="`keep-alive-${name}`"
+  >
+    <span class="compat-probe__badge">Kept instance {{ name }}</span>
+    <strong>Counter: {{ count }}</strong>
+    <p>Increment, switch instances, then return to verify preserved state.</p>
+    <button type="button" @click="count += 1">Increment {{ name }}</button>
+  </article>
+</template>
@@ -0,0 +1,56 @@
+<script lang="ts">
+import { defineComponent } from "vue";
+import type { RouteLocationNormalizedLoaded } from "vue-router";
+import { recordCompatibilityEvent } from "../compatibility-lab";
+
+export default defineComponent({
+  name: "CompatibilityOptionsProbe",
+  props: {
+    instanceName: { type: String, required: true },
+    revision: { type: Number, required: true },
+  },
+  data: () => ({ localCount: 0 }),
+  beforeCreate() {
+    recordCompatibilityEvent(this.instanceName, "beforeCreate");
+  },
+  created() {
+    recordCompatibilityEvent(this.instanceName, "created", this.routePath());
+  },
+  beforeMount() {
+    recordCompatibilityEvent(this.instanceName, "beforeMount");
+  },
+  mounted() {
+    recordCompatibilityEvent(this.instanceName, "mounted");
+  },
+  beforeUpdate() {
+    recordCompatibilityEvent(this.instanceName, "beforeUpdate");
+  },
+  updated() {
+    recordCompatibilityEvent(this.instanceName, "updated");
+  },
+  beforeUnmount() {
+    recordCompatibilityEvent(this.instanceName, "beforeUnmount");
+  },
+  unmounted() {
+    recordCompatibilityEvent(this.instanceName, "unmounted");
+  },
+  methods: {
+    routePath() {
+      return (this as unknown as { $route: RouteLocationNormalizedLoaded })
+        .$route.fullPath;
+    },
+  },
+});
+</script>
+
+<template>
+  <article class="compat-probe" data-testid="options-lifecycle-probe">
+    <span class="compat-probe__badge">Options API</span>
+    <strong>{{ instanceName }}</strong>
+    <p><code>$route</code>: {{ routePath() }}</p>
+    <p>Revision {{ revision }} · local count {{ localCount }}</p>
+    <button type="button" @click="localCount += 1">
+      Increment local state
+    </button>
+  </article>
+</template>
@@ -1,18 +1,83 @@
 <script setup lang="ts">
+import { onBeforeUnmount, ref, watch } from 'vue'
 import { useRegisterSW } from 'virtual:pwa-register/vue'
 import { useNativeRouter } from '@native-vue-router/core'
+import { recordPwaUpdateState } from '../pwa'

 const native = useNativeRouter()
-const { needRefresh, updateServiceWorker } = useRegisterSW()
+const reloadPending = ref(false)
+let registration: ServiceWorkerRegistration | undefined
+let checkTimer: number | undefined
+let reloading = false
+let checking = false
+
+function reloadWhenIdle() {
+  if (!reloadPending.value || native.transaction.value || reloading) return
+  reloading = true
+  window.location.reload()
+}
+
+async function checkForUpdate() {
+  if (!registration || checking || document.visibilityState === 'hidden' || !navigator.onLine) return
+  checking = true
+  recordPwaUpdateState('checking', true)
+  try {
+    await registration.update()
+    if (!reloadPending.value) recordPwaUpdateState('current')
+  } catch {
+    recordPwaUpdateState('error')
+  } finally {
+    checking = false
+  }
+}
+
+const { needRefresh, updateServiceWorker } = useRegisterSW({
+  immediate: true,
+  onRegisteredSW(_workerUrl, workerRegistration) {
+    registration = workerRegistration
+    void checkForUpdate()
+    if (checkTimer !== undefined) window.clearInterval(checkTimer)
+    checkTimer = window.setInterval(() => void checkForUpdate(), 60_000)
+  },
+  onNeedRefresh() {
+    recordPwaUpdateState('ready')
+  },
+  onNeedReload() {
+    recordPwaUpdateState('ready')
+    reloadPending.value = true
+    reloadWhenIdle()
+  },
+  onRegisterError() {
+    recordPwaUpdateState('error')
+  },
+})
+
+function checkWhenActive() {
+  if (document.visibilityState === 'visible') void checkForUpdate()
+}
+
+window.addEventListener('focus', checkWhenActive)
+window.addEventListener('online', checkWhenActive)
+document.addEventListener('visibilitychange', checkWhenActive)
+watch(() => native.transaction.value, reloadWhenIdle, { flush: 'post' })

 function update() {
+  reloadPending.value = true
  if (!native.transaction.value) void updateServiceWorker(true)
+  reloadWhenIdle()
 }
+
+onBeforeUnmount(() => {
+  if (checkTimer !== undefined) window.clearInterval(checkTimer)
+  window.removeEventListener('focus', checkWhenActive)
+  window.removeEventListener('online', checkWhenActive)
+  document.removeEventListener('visibilitychange', checkWhenActive)
+})
 </script>

 <template>
-  <aside v-if="needRefresh" class="update-toast" role="status">
-    <span>A fresh build is ready.</span>
-    <button type="button" :disabled="Boolean(native.transaction.value)" @click="update">Update</button>
+  <aside v-if="needRefresh || reloadPending" class="update-toast" role="status">
+    <span>{{ native.transaction.value ? 'A fresh build will open after this gesture.' : 'A fresh build is ready.' }}</span>
+    <button v-if="needRefresh" type="button" :disabled="Boolean(native.transaction.value)" @click="update">Update</button>
  </aside>
 </template>
@@ -1,103 +1,207 @@
-import { computed, reactive, readonly, ref } from 'vue'
+import { computed, reactive, readonly, ref } from "vue";

 export interface Person {
-  id: string
-  name: string
-  handle: string
-  color: string
-  online: boolean
-  bio: string
+  id: string;
+  name: string;
+  handle: string;
+  color: string;
+  online: boolean;
+  bio: string;
 }

 export interface Message {
-  id: string
-  personId: string
-  body: string
-  sentAt: number
-  mine: boolean
-  status: 'sent' | 'delivered' | 'failed'
+  id: string;
+  personId: string;
+  body: string;
+  sentAt: number;
+  mine: boolean;
+  status: "sent" | "delivered" | "failed";
 }

 export interface Conversation {
-  id: string
-  personId: string
-  unread: number
-  pinned?: boolean
-  messages: Message[]
+  id: string;
+  personId: string;
+  unread: number;
+  pinned?: boolean;
+  messages: Message[];
 }

 const people: Person[] = [
-  { id: 'maya', name: 'Maya Chen', handle: '@mayac', color: '#ff7a8a', online: true, bio: 'Product designer · Sydney to everywhere.' },
-  { id: 'noah', name: 'Noah Williams', handle: '@noahw', color: '#4f9cff', online: true, bio: 'Film, tiny cameras, and very long walks.' },
-  { id: 'sofia', name: 'Sofia Rossi', handle: '@sofiar', color: '#9d67ff', online: false, bio: 'Making typefaces and better pasta.' },
-  { id: 'liam', name: 'Liam Park', handle: '@liamp', color: '#35c7a0', online: true, bio: 'Engineer. Climber. Questionable DJ.' },
-  { id: 'amara', name: 'Amara Okafor', handle: '@amarao', color: '#f4ad42', online: false, bio: 'Architecture and cities after dark.' },
-]
+  {
+    id: "maya",
+    name: "Maya Chen",
+    handle: "@mayac",
+    color: "#ff7a8a",
+    online: true,
+    bio: "Product designer · Sydney to everywhere.",
+  },
+  {
+    id: "noah",
+    name: "Noah Williams",
+    handle: "@noahw",
+    color: "#4f9cff",
+    online: true,
+    bio: "Film, tiny cameras, and very long walks.",
+  },
+  {
+    id: "sofia",
+    name: "Sofia Rossi",
+    handle: "@sofiar",
+    color: "#9d67ff",
+    online: false,
+    bio: "Making typefaces and better pasta.",
+  },
+  {
+    id: "liam",
+    name: "Liam Park",
+    handle: "@liamp",
+    color: "#35c7a0",
+    online: true,
+    bio: "Engineer. Climber. Questionable DJ.",
+  },
+  {
+    id: "amara",
+    name: "Amara Okafor",
+    handle: "@amarao",
+    color: "#f4ad42",
+    online: false,
+    bio: "Architecture and cities after dark.",
+  },
+];

-const timestamp = Date.now()
+const timestamp = Date.now();
 const seedConversations: Conversation[] = [
  {
-    id: 'maya', personId: 'maya', unread: 2, pinned: true,
+    id: "maya",
+    personId: "maya",
+    unread: 2,
+    pinned: true,
    messages: [
-      { id: 'm1', personId: 'maya', body: 'That transition feels ridiculously smooth ✨', sentAt: timestamp - 840_000, mine: false, status: 'delivered' },
-      { id: 'm2', personId: 'maya', body: 'Try holding it halfway, then let go slowly.', sentAt: timestamp - 780_000, mine: false, status: 'delivered' },
+      {
+        id: "m1",
+        personId: "maya",
+        body: "That transition feels ridiculously smooth ✨",
+        sentAt: timestamp - 840_000,
+        mine: false,
+        status: "delivered",
+      },
+      {
+        id: "m2",
+        personId: "maya",
+        body: "Try holding it halfway, then let go slowly.",
+        sentAt: timestamp - 780_000,
+        mine: false,
+        status: "delivered",
+      },
    ],
  },
  {
-    id: 'noah', personId: 'noah', unread: 0,
+    id: "noah",
+    personId: "noah",
+    unread: 0,
    messages: [
-      { id: 'n1', personId: 'noah', body: 'Uploaded the photos from yesterday.', sentAt: timestamp - 4_200_000, mine: false, status: 'delivered' },
-      { id: 'n2', personId: 'noah', body: 'The grain is perfect.', sentAt: timestamp - 4_000_000, mine: true, status: 'delivered' },
+      {
+        id: "n1",
+        personId: "noah",
+        body: "Uploaded the photos from yesterday.",
+        sentAt: timestamp - 4_200_000,
+        mine: false,
+        status: "delivered",
+      },
+      {
+        id: "n2",
+        personId: "noah",
+        body: "The grain is perfect.",
+        sentAt: timestamp - 4_000_000,
+        mine: true,
+        status: "delivered",
+      },
    ],
  },
  {
-    id: 'sofia', personId: 'sofia', unread: 1,
-    messages: [{ id: 's1', personId: 'sofia', body: 'Coffee at the new place tomorrow?', sentAt: timestamp - 18_000_000, mine: false, status: 'delivered' }],
+    id: "sofia",
+    personId: "sofia",
+    unread: 1,
+    messages: [
+      {
+        id: "s1",
+        personId: "sofia",
+        body: "Coffee at the new place tomorrow?",
+        sentAt: timestamp - 18_000_000,
+        mine: false,
+        status: "delivered",
+      },
+    ],
  },
  {
-    id: 'liam', personId: 'liam', unread: 0,
-    messages: [{ id: 'l1', personId: 'liam', body: 'The build is green. Ship it.', sentAt: timestamp - 86_000_000, mine: false, status: 'delivered' }],
+    id: "liam",
+    personId: "liam",
+    unread: 0,
+    messages: [
+      {
+        id: "l1",
+        personId: "liam",
+        body: "The build is green. Ship it.",
+        sentAt: timestamp - 86_000_000,
+        mine: false,
+        status: "delivered",
+      },
+    ],
  },
  {
-    id: 'amara', personId: 'amara', unread: 0,
-    messages: [{ id: 'a1', personId: 'amara', body: 'This city never really goes quiet.', sentAt: timestamp - 172_000_000, mine: false, status: 'delivered' }],
+    id: "amara",
+    personId: "amara",
+    unread: 0,
+    messages: [
+      {
+        id: "a1",
+        personId: "amara",
+        body: "This city never really goes quiet.",
+        sentAt: timestamp - 172_000_000,
+        mine: false,
+        status: "delivered",
      },
-]
+    ],
+  },
+];

-const conversations = ref<Conversation[]>(structuredClone(seedConversations))
-const ready = ref(false)
-const offline = ref(!navigator.onLine)
-const settings = reactive({ simulatedLatency: 180, simulateFailures: false })
+const conversations = ref<Conversation[]>(structuredClone(seedConversations));
+const ready = ref(false);
+const offline = ref(!navigator.onLine);
+const settings = reactive({ simulatedLatency: 180, simulateFailures: false });

 function openDatabase() {
  return new Promise<IDBDatabase>((resolve, reject) => {
-    const request = indexedDB.open('native-vue-messenger', 1)
-    request.onupgradeneeded = () => request.result.createObjectStore('state')
-    request.onsuccess = () => resolve(request.result)
-    request.onerror = () => reject(request.error)
-  })
+    const request = indexedDB.open("native-vue-messenger", 1);
+    request.onupgradeneeded = () => request.result.createObjectStore("state");
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error);
+  });
 }

 async function readStored() {
-  const database = await openDatabase()
+  const database = await openDatabase();
  return await new Promise<Conversation[] | undefined>((resolve, reject) => {
-    const transaction = database.transaction('state', 'readonly')
-    const request = transaction.objectStore('state').get('conversations')
-    request.onsuccess = () => resolve(request.result as Conversation[] | undefined)
-    request.onerror = () => reject(request.error)
-  }).finally(() => database.close())
+    const transaction = database.transaction("state", "readonly");
+    const request = transaction.objectStore("state").get("conversations");
+    request.onsuccess = () =>
+      resolve(request.result as Conversation[] | undefined);
+    request.onerror = () => reject(request.error);
+  }).finally(() => database.close());
 }

 async function persist() {
  try {
-    const database = await openDatabase()
+    const database = await openDatabase();
    await new Promise<void>((resolve, reject) => {
-      const transaction = database.transaction('state', 'readwrite')
-      transaction.objectStore('state').put(structuredClone(conversations.value), 'conversations')
-      transaction.oncomplete = () => resolve()
-      transaction.onerror = () => reject(transaction.error)
-    })
-    database.close()
+      const transaction = database.transaction("state", "readwrite");
+      transaction
+        .objectStore("state")
+        .put(structuredClone(conversations.value), "conversations");
+      transaction.oncomplete = () => resolve();
+      transaction.onerror = () => reject(transaction.error);
+    });
+    database.close();
  } catch {
    // Private browsing and locked-down webviews can reject IndexedDB.
  }
@@ -105,48 +209,58 @@ async function persist() {

 async function initialize() {
  try {
-    const stored = await readStored()
-    if (stored?.length) conversations.value = stored
-    else await persist()
+    const stored = await readStored();
+    if (stored?.length) conversations.value = stored;
+    else await persist();
  } finally {
-    ready.value = true
+    ready.value = true;
  }
 }

-window.addEventListener('online', () => { offline.value = false })
-window.addEventListener('offline', () => { offline.value = true })
-void initialize()
+window.addEventListener("online", () => {
+  offline.value = false;
+});
+window.addEventListener("offline", () => {
+  offline.value = true;
+});
+void initialize();

 export function useDemoStore() {
-  const conversationFor = (id: string) => computed(() => conversations.value.find((conversation) => conversation.id === id))
-  const personFor = (id: string) => people.find((person) => person.id === id)
+  const conversationFor = (id: string) =>
+    computed(() =>
+      conversations.value.find((conversation) => conversation.id === id),
+    );
+  const personFor = (id: string) => people.find((person) => person.id === id);
  const markRead = (id: string) => {
-    const conversation = conversations.value.find((item) => item.id === id)
-    if (conversation) conversation.unread = 0
-    void persist()
-  }
+    const conversation = conversations.value.find((item) => item.id === id);
+    if (conversation) conversation.unread = 0;
+    void persist();
+  };
  const sendMessage = async (id: string, body: string) => {
-    const conversation = conversations.value.find((item) => item.id === id)
-    if (!conversation || !body.trim()) return false
+    const conversation = conversations.value.find((item) => item.id === id);
+    if (!conversation || !body.trim()) return false;
    const message: Message = {
      id: crypto.randomUUID(),
      personId: id,
      body: body.trim(),
      sentAt: Date.now(),
      mine: true,
-      status: 'sent',
-    }
-    conversation.messages.push(message)
-    await persist()
-    await new Promise((resolve) => window.setTimeout(resolve, settings.simulatedLatency))
-    message.status = settings.simulateFailures || offline.value ? 'failed' : 'delivered'
-    await persist()
-    return message.status === 'delivered'
-  }
+      status: "sent",
+    };
+    conversation.messages.push(message);
+    await persist();
+    await new Promise((resolve) =>
+      window.setTimeout(resolve, settings.simulatedLatency),
+    );
+    message.status =
+      settings.simulateFailures || offline.value ? "failed" : "delivered";
+    await persist();
+    return message.status === "delivered";
+  };
  const reset = async () => {
-    conversations.value = structuredClone(seedConversations)
-    await persist()
-  }
+    conversations.value = structuredClone(seedConversations);
+    await persist();
+  };
  return {
    people: readonly(ref(people)),
    conversations: readonly(conversations),
@@ -158,14 +272,14 @@ export function useDemoStore() {
    markRead,
    sendMessage,
    reset,
-  }
+  };
 }

 export function relativeTime(value: number) {
-  const minutes = Math.floor((Date.now() - value) / 60_000)
-  if (minutes < 1) return 'now'
-  if (minutes < 60) return `${minutes}m`
-  const hours = Math.floor(minutes / 60)
-  if (hours < 24) return `${hours}h`
-  return `${Math.floor(hours / 24)}d`
+  const minutes = Math.floor((Date.now() - value) / 60_000);
+  if (minutes < 1) return "now";
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h`;
+  return `${Math.floor(hours / 24)}d`;
 }
@@ -0,0 +1,50 @@
+import { readonly, reactive } from "vue";
+
+function createGuardState() {
+  return reactive({
+    blockEntry: false,
+    checks: 0,
+    status: "idle" as "idle" | "checking" | "allowed" | "blocked",
+  });
+}
+
+const storyState = createGuardState();
+const labState = createGuardState();
+
+export const storyEntryGuard = readonly(storyState);
+export const runtimeLabGuard = readonly(labState);
+
+export function setStoryEntryBlocked(blocked: boolean) {
+  storyState.blockEntry = blocked;
+  if (storyState.status !== "checking") storyState.status = "idle";
+}
+
+async function evaluate(state: ReturnType<typeof createGuardState>) {
+  state.checks += 1;
+  state.status = "checking";
+  await new Promise((resolve) => window.setTimeout(resolve, 320));
+  const allowed = !state.blockEntry;
+  state.status = allowed ? "allowed" : "blocked";
+  return allowed;
+}
+
+/** Dynamic guard used to reject a sibling that may already be cached. */
+export function evaluateStoryEntry() {
+  storyState.checks += 1;
+  if (!storyState.blockEntry) {
+    storyState.status = "allowed";
+    return true;
+  }
+  storyState.status = "checking";
+  return new Promise<boolean>((resolve) => {
+    window.setTimeout(() => {
+      storyState.status = "blocked";
+      resolve(false);
+    }, 320);
+  });
+}
+
+/** Always-allowing asynchronous guard for the deeper stress-lab route. */
+export function evaluateRuntimeLabEntry() {
+  return evaluate(labState);
+}
@@ -1,29 +1,34 @@
-import { createApp } from 'vue'
-import { createNativeRouter } from '@native-vue-router/core'
-import { createCapacitorAdapter } from '@native-vue-router/capacitor'
-import { createElectronRendererAdapter } from '@native-vue-router/electron'
-import App from './App.vue'
-import { createPwaAdapter } from './pwa'
-import { router } from './router'
-import './style.css'
+import { createApp } from "vue";
+import { createNativeRouter } from "@native-vue-router/core";
+import { createCapacitorAdapter } from "@native-vue-router/capacitor";
+import { createElectronRendererAdapter } from "@native-vue-router/electron";
+import App from "./App.vue";
+import { demoAppValueKey } from "./compatibility-lab";
+import { createPwaAdapter } from "./pwa";
+import { router } from "./router";
+import "./style.css";

-const isElectron = navigator.userAgent.toLowerCase().includes('electron')
-const capacitorPlatform = createCapacitorAdapter({ haptics: true, exitAtRoot: true })
+const isElectron = navigator.userAgent.toLowerCase().includes("electron");
+const capacitorPlatform = createCapacitorAdapter({
+  haptics: true,
+  exitAtRoot: true,
+});
 const platform = isElectron
  ? createElectronRendererAdapter()
-  : capacitorPlatform.name !== 'capacitor-web'
+  : capacitorPlatform.name !== "capacitor-web"
    ? capacitorPlatform
-    : createPwaAdapter()
+    : createPwaAdapter();

 const nativeRouter = createNativeRouter({
  router,
-  cache: { maxInactive: 8 },
+  cache: { maxInactive: 4 },
  platform,
-})
+});

-const app = createApp(App)
-app.use(router)
-app.use(nativeRouter)
+const app = createApp(App);
+app.use(router);
+app.use(nativeRouter);
+app.provide(demoAppValueKey, "Injected from the demo application root");

-await router.isReady()
-app.mount('#app')
+await router.isReady();
+app.mount("#app");
@@ -0,0 +1,74 @@
+import { ref } from "vue";
+import {
+  createNativeNavigationProfiler,
+  type NativeNavigationProfiler,
+  type NativeProfilerReport,
+  type NativeRouterRuntime,
+} from "@native-vue-router/core";
+import { pwaBuildId } from "./pwa";
+
+let profiler: NativeNavigationProfiler | undefined;
+export const profilerRecording = ref(false);
+export const profilerHasCapture = ref(false);
+
+function instance(runtime: NativeRouterRuntime) {
+  profiler ??= createNativeNavigationProfiler(runtime, {
+    metadata: { app: "nvr-messenger-demo", build: pwaBuildId },
+  });
+  return profiler;
+}
+
+export function startDemoProfile(runtime: NativeRouterRuntime) {
+  const active = instance(runtime);
+  active.start();
+  profilerRecording.value = true;
+  profilerHasCapture.value = true;
+}
+
+export function stopDemoProfile(runtime: NativeRouterRuntime) {
+  const report = instance(runtime).stop();
+  profilerRecording.value = false;
+  return report;
+}
+
+export function snapshotDemoProfile(runtime: NativeRouterRuntime) {
+  return instance(runtime).snapshot();
+}
+
+export async function shareDemoProfile(
+  runtime: NativeRouterRuntime,
+  report?: NativeProfilerReport,
+) {
+  const active = instance(runtime);
+  const current =
+    report ??
+    (profilerRecording.value ? stopDemoProfile(runtime) : active.snapshot());
+  const json = active.toJSON(current);
+  const stamp = new Date()
+    .toISOString()
+    .replaceAll(":", "-")
+    .replaceAll(".", "-");
+  const filename = `native-vue-router-profile-${stamp}.json`;
+  const file = new File([json], filename, { type: "application/json" });
+  const shareNavigator = navigator as Navigator & {
+    canShare?: (data: ShareData) => boolean;
+    share?: (data: ShareData) => Promise<void>;
+  };
+
+  if (shareNavigator.share && shareNavigator.canShare?.({ files: [file] })) {
+    await shareNavigator.share({
+      title: "Native Vue Router performance profile",
+      text: "Frame pacing and navigation diagnostics. Route params and query values are omitted.",
+      files: [file],
+    });
+    return { report: current, method: "shared" as const };
+  }
+
+  const url = URL.createObjectURL(file);
+  const link = document.createElement("a");
+  link.href = url;
+  link.download = filename;
+  link.click();
+  window.setTimeout(() => URL.revokeObjectURL(url), 1_000);
+  return { report: current, method: "downloaded" as const };
+}
@@ -1,46 +1,77 @@
-import { reactive, readonly } from 'vue'
-import type { NativePlatformAdapter } from '@native-vue-router/core'
+import { reactive, readonly } from "vue";
+import type { NativePlatformAdapter } from "@native-vue-router/core";

 interface StandaloneNavigator extends Navigator {
-  standalone?: boolean
+  standalone?: boolean;
 }

-type ServiceWorkerState = 'unsupported' | 'installing' | 'ready'
+type ServiceWorkerState = "unsupported" | "installing" | "ready";
+export type PwaUpdateState =
+  "idle" | "checking" | "current" | "ready" | "error";
+
+declare const __NVR_BUILD_ID__: string;
+
+export const pwaBuildId = __NVR_BUILD_ID__;

 const state = reactive({
  ios: false,
  standalone: false,
  edgeGuard: false,
  edgeClaims: 0,
-  serviceWorker: 'installing' as ServiceWorkerState,
-})
+  serviceWorker: "installing" as ServiceWorkerState,
+  updateState: "idle" as PwaUpdateState,
+  updateChecks: 0,
+});

-export const pwaEnvironment = readonly(state)
+export const pwaEnvironment = readonly(state);
+
+export function recordPwaUpdateState(
+  updateState: PwaUpdateState,
+  checked = false,
+) {
+  state.updateState = updateState;
+  if (checked) state.updateChecks += 1;
+  document.documentElement.dataset.pwaUpdateState = state.updateState;
+  document.documentElement.dataset.pwaUpdateChecks = String(state.updateChecks);
+}

 export function isIOSWebKit() {
-  const navigatorWithTouch = navigator as Navigator & { maxTouchPoints?: number }
-  return /iPad|iPhone|iPod/.test(navigator.userAgent)
-    || (/Macintosh/.test(navigator.userAgent) && (navigatorWithTouch.maxTouchPoints ?? 0) > 1)
+  const navigatorWithTouch = navigator as Navigator & {
+    maxTouchPoints?: number;
+  };
+  return (
+    /iPad|iPhone|iPod/.test(navigator.userAgent) ||
+    (/Macintosh/.test(navigator.userAgent) &&
+      (navigatorWithTouch.maxTouchPoints ?? 0) > 1)
+  );
 }

 export function isStandalonePwa() {
-  return Boolean((navigator as StandaloneNavigator).standalone)
-    || window.matchMedia('(display-mode: standalone)').matches
-    || window.matchMedia('(display-mode: fullscreen)').matches
+  return (
+    Boolean((navigator as StandaloneNavigator).standalone) ||
+    window.matchMedia("(display-mode: standalone)").matches ||
+    window.matchMedia("(display-mode: fullscreen)").matches
+  );
 }

 function updateEnvironment() {
-  state.ios = isIOSWebKit()
-  state.standalone = isStandalonePwa()
-  state.edgeGuard = state.ios && state.standalone
-  document.documentElement.dataset.pwaPlatform = state.ios ? 'ios' : 'other'
-  document.documentElement.dataset.pwaDisplayMode = state.standalone ? 'standalone' : 'browser'
-  document.documentElement.dataset.pwaEdgeGuard = state.edgeGuard ? 'active' : 'inactive'
-  document.documentElement.dataset.pwaEdgeClaims = String(state.edgeClaims)
+  state.ios = isIOSWebKit();
+  state.standalone = isStandalonePwa();
+  state.edgeGuard = state.ios && state.standalone;
+  document.documentElement.dataset.pwaPlatform = state.ios ? "ios" : "other";
+  document.documentElement.dataset.pwaDisplayMode = state.standalone
+    ? "standalone"
+    : "browser";
+  document.documentElement.dataset.pwaEdgeGuard = state.edgeGuard
+    ? "active"
+    : "inactive";
+  document.documentElement.dataset.pwaEdgeClaims = String(state.edgeClaims);
+  document.documentElement.dataset.pwaUpdateState = state.updateState;
+  document.documentElement.dataset.pwaUpdateChecks = String(state.updateChecks);
 }

 export interface PwaAdapterOptions {
-  edgeWidth?: number
+  edgeWidth?: number;
 }

 /**
@@ -50,65 +81,104 @@ export interface PwaAdapterOptions {
 * Safari does not expose WKWebView's native gesture switch to web content,
 * so this is deliberately scoped to standalone mode and reinforced by CSS.
 */
-export function createPwaAdapter(options: PwaAdapterOptions = {}): NativePlatformAdapter {
-  const edgeWidth = options.edgeWidth ?? 32
+export function createPwaAdapter(
+  options: PwaAdapterOptions = {},
+): NativePlatformAdapter {
+  const edgeWidth = options.edgeWidth ?? 32;
  return {
-    name: 'pwa',
+    name: "pwa",
    install() {
-      updateEnvironment()
-      const displayMode = window.matchMedia('(display-mode: standalone)')
-      const update = () => updateEnvironment()
-      displayMode.addEventListener('change', update)
-      document.addEventListener('visibilitychange', update)
+      updateEnvironment();
+      const displayMode = window.matchMedia("(display-mode: standalone)");
+      const update = () => updateEnvironment();
+      displayMode.addEventListener("change", update);
+      document.addEventListener("visibilitychange", update);

-      if (!('serviceWorker' in navigator)) state.serviceWorker = 'unsupported'
+      if (!("serviceWorker" in navigator)) state.serviceWorker = "unsupported";
      else {
-        state.serviceWorker = navigator.serviceWorker.controller ? 'ready' : 'installing'
-        void navigator.serviceWorker.ready.then(() => { state.serviceWorker = 'ready' })
-        navigator.serviceWorker.addEventListener('controllerchange', updateServiceWorkerState)
+        state.serviceWorker = navigator.serviceWorker.controller
+          ? "ready"
+          : "installing";
+        void navigator.serviceWorker.ready.then(() => {
+          state.serviceWorker = "ready";
+        });
+        navigator.serviceWorker.addEventListener(
+          "controllerchange",
+          updateServiceWorkerState,
+        );
      }

-      let reservedTouch: number | null = null
+      let reservedTouch: number | null = null;
      const touchAtLeadingEdge = (event: TouchEvent) => {
-        if (!state.edgeGuard || event.touches.length !== 1) return undefined
-        if (!(event.target instanceof Element) || !event.target.closest('.nvr-navigator')) return undefined
-        const touch = event.touches[0]
-        const rtl = getComputedStyle(document.documentElement).direction === 'rtl'
-        const atEdge = rtl ? window.innerWidth - touch.clientX <= edgeWidth : touch.clientX <= edgeWidth
-        return atEdge ? touch : undefined
-      }
+        if (!state.edgeGuard || event.touches.length !== 1) return undefined;
+        if (
+          !(event.target instanceof Element) ||
+          !event.target.closest(".nvr-navigator")
+        )
+          return undefined;
+        const touch = event.touches[0];
+        const rtl =
+          getComputedStyle(document.documentElement).direction === "rtl";
+        const atEdge = rtl
+          ? window.innerWidth - touch.clientX <= edgeWidth
+          : touch.clientX <= edgeWidth;
+        return atEdge ? touch : undefined;
+      };
      const reserveEdge = (event: TouchEvent) => {
-        const touch = touchAtLeadingEdge(event)
-        if (!touch) return
-        reservedTouch = touch.identifier
-        state.edgeClaims += 1
-        document.documentElement.dataset.pwaEdgeClaims = String(state.edgeClaims)
-        event.preventDefault()
-      }
+        const touch = touchAtLeadingEdge(event);
+        if (!touch) return;
+        reservedTouch = touch.identifier;
+        state.edgeClaims += 1;
+        document.documentElement.dataset.pwaEdgeClaims = String(
+          state.edgeClaims,
+        );
+        event.preventDefault();
+      };
      const holdEdge = (event: TouchEvent) => {
-        if (reservedTouch === null) return
-        if ([...event.touches].some((touch) => touch.identifier === reservedTouch)) event.preventDefault()
-      }
-      const releaseEdge = () => { reservedTouch = null }
+        if (reservedTouch === null) return;
+        if (
+          [...event.touches].some((touch) => touch.identifier === reservedTouch)
+        )
+          event.preventDefault();
+      };
+      const releaseEdge = () => {
+        reservedTouch = null;
+      };

-      document.addEventListener('touchstart', reserveEdge, { capture: true, passive: false })
-      document.addEventListener('touchmove', holdEdge, { capture: true, passive: false })
-      document.addEventListener('touchend', releaseEdge, { capture: true, passive: true })
-      document.addEventListener('touchcancel', releaseEdge, { capture: true, passive: true })
+      document.addEventListener("touchstart", reserveEdge, {
+        capture: true,
+        passive: false,
+      });
+      document.addEventListener("touchmove", holdEdge, {
+        capture: true,
+        passive: false,
+      });
+      document.addEventListener("touchend", releaseEdge, {
+        capture: true,
+        passive: true,
+      });
+      document.addEventListener("touchcancel", releaseEdge, {
+        capture: true,
+        passive: true,
+      });

      return () => {
-        displayMode.removeEventListener('change', update)
-        document.removeEventListener('visibilitychange', update)
-        if ('serviceWorker' in navigator) navigator.serviceWorker.removeEventListener('controllerchange', updateServiceWorkerState)
-        document.removeEventListener('touchstart', reserveEdge, true)
-        document.removeEventListener('touchmove', holdEdge, true)
-        document.removeEventListener('touchend', releaseEdge, true)
-        document.removeEventListener('touchcancel', releaseEdge, true)
-      }
+        displayMode.removeEventListener("change", update);
+        document.removeEventListener("visibilitychange", update);
+        if ("serviceWorker" in navigator)
+          navigator.serviceWorker.removeEventListener(
+            "controllerchange",
+            updateServiceWorkerState,
+          );
+        document.removeEventListener("touchstart", reserveEdge, true);
+        document.removeEventListener("touchmove", holdEdge, true);
+        document.removeEventListener("touchend", releaseEdge, true);
+        document.removeEventListener("touchcancel", releaseEdge, true);
+      };
    },
-  }
+  };
 }

 function updateServiceWorkerState() {
-  state.serviceWorker = 'ready'
+  state.serviceWorker = "ready";
 }
@@ -1,39 +1,141 @@
-import { createRouter, createWebHashHistory, createWebHistory, type RouteRecordRaw } from 'vue-router'
+import {
+  createRouter,
+  createWebHashHistory,
+  createWebHistory,
+  type RouteRecordRaw,
+} from "vue-router";
+import { evaluateRuntimeLabEntry, evaluateStoryEntry } from "./guard-state";

 const routes: RouteRecordRaw[] = [
-  { path: '/', redirect: '/inbox' },
+  { path: "/", redirect: "/inbox" },
  {
-    path: '/inbox', name: 'inbox', component: () => import('./views/InboxView.vue'),
-    meta: { tab: true, native: { siblingGroup: 'primary', siblingOrder: 0, siblingHistory: 'replace', gesture: 'full' } },
+    path: "/inbox",
+    name: "inbox",
+    component: () => import("./views/InboxView.vue"),
+    meta: {
+      tab: true,
+      native: {
+        siblingGroup: "primary",
+        siblingOrder: 0,
+        siblingHistory: "replace",
+        gesture: "full",
+      },
+    },
  },
  {
-    path: '/stories', name: 'stories', component: () => import('./views/StoriesView.vue'),
-    meta: { tab: true, native: { siblingGroup: 'primary', siblingOrder: 1, siblingHistory: 'replace', gesture: 'full' } },
+    path: "/stories",
+    name: "stories",
+    component: () => import("./views/StoriesView.vue"),
+    beforeEnter: evaluateStoryEntry,
+    meta: {
+      tab: true,
+      native: {
+        siblingGroup: "primary",
+        siblingOrder: 1,
+        siblingHistory: "replace",
+        gesture: "full",
+      },
+    },
  },
  {
-    path: '/profile', name: 'profile', component: () => import('./views/ProfileView.vue'),
-    meta: { tab: true, native: { siblingGroup: 'primary', siblingOrder: 2, siblingHistory: 'replace', gesture: 'full' } },
+    path: "/profile",
+    name: "profile",
+    component: () => import("./views/ProfileView.vue"),
+    meta: {
+      tab: true,
+      native: {
+        siblingGroup: "primary",
+        siblingOrder: 2,
+        siblingHistory: "replace",
+        gesture: "full",
+      },
+    },
  },
  {
-    path: '/chat/:id', name: 'chat', component: () => import('./views/ChatView.vue'),
-    meta: { native: { presentation: 'push', parent: '/inbox', gesture: 'edge' } },
+    path: "/profile/runtime-lab",
+    name: "runtime-lab",
+    component: () => import("./views/RuntimeLabView.vue"),
+    beforeEnter: evaluateRuntimeLabEntry,
+    meta: {
+      tab: true,
+      native: {
+        siblingGroup: "primary",
+        siblingOrder: 3,
+        siblingHistory: "push",
+        presentation: "slide",
+        parent: "/profile",
+        gesture: "full",
+      },
+    },
  },
  {
-    path: '/chat/:id/details', name: 'chat-details', component: () => import('./views/ContactView.vue'),
-    meta: { native: { presentation: 'push', parent: (route) => `/chat/${String(route.params.id)}`, gesture: 'edge' } },
+    path: "/chat/:id",
+    name: "chat",
+    component: () => import("./views/ChatView.vue"),
+    meta: {
+      native: { presentation: "push", parent: "/inbox", gesture: "edge" },
+    },
  },
  {
-    path: '/compose', name: 'compose', component: () => import('./views/ComposeView.vue'),
-    meta: { native: { presentation: 'sheet', parent: '/inbox', gesture: 'full' } },
+    path: "/chat/:id/details",
+    name: "chat-details",
+    component: () => import("./views/ContactView.vue"),
+    meta: {
+      native: {
+        presentation: "push",
+        parent: (route) => `/chat/${String(route.params.id)}`,
+        gesture: "edge",
+      },
+    },
  },
  {
-    path: '/settings', name: 'settings', component: () => import('./views/SettingsView.vue'),
-    meta: { native: { presentation: 'push', parent: '/profile', gesture: 'edge' } },
+    path: "/compose",
+    name: "compose",
+    component: () => import("./views/ComposeView.vue"),
+    meta: {
+      native: { presentation: "sheet", parent: "/inbox", gesture: "full" },
    },
-]
+  },
+  {
+    path: "/settings",
+    name: "settings",
+    component: () => import("./views/SettingsView.vue"),
+    meta: {
+      native: { presentation: "push", parent: "/profile", gesture: "edge" },
+    },
+  },
+  {
+    path: "/profile/vue-lab/:sample",
+    name: "vue-compatibility",
+    component: () => import("./views/VueCompatibilityView.vue"),
+    meta: {
+      native: { presentation: "push", parent: "/profile", gesture: "edge" },
+    },
+  },
+  {
+    path: "/profile/vue-lab/:sample/away",
+    name: "vue-compatibility-away",
+    component: () => import("./views/VueCompatibilityAwayView.vue"),
+    meta: {
+      native: {
+        presentation: "push",
+        parent: (route) => ({
+          name: "vue-compatibility",
+          params: { sample: route.params.sample },
+          query: route.query,
+          hash: route.hash,
+        }),
+        gesture: "edge",
+      },
+    },
+  },
+];

 export const router = createRouter({
-  history: window.location.protocol === 'file:' ? createWebHashHistory() : createWebHistory(),
+  history:
+    window.location.protocol === "file:"
+      ? createWebHashHistory()
+      : createWebHistory(),
  routes,
  scrollBehavior: () => ({ top: 0 }),
-})
+});
@@ -1,37 +1,66 @@
 <script setup lang="ts">
-import { ref } from 'vue'
-import { NativeDismissGesture, useNativeRouter } from '@native-vue-router/core'
-import AppAvatar from '../components/AppAvatar.vue'
-import { useDemoStore } from '../data'
+import { computed, ref } from "vue";
+import { NativeSheet, useNativeRouter } from "@native-vue-router/core";
+import AppAvatar from "../components/AppAvatar.vue";
+import { useDemoStore } from "../data";

-const native = useNativeRouter()
-const store = useDemoStore()
-const query = ref('')
+const native = useNativeRouter();
+const store = useDemoStore();
+const query = ref("");
+const sheetBreakpoint = ref(0.62);
+const snapEnabled = ref(true);
+const sheetBreakpoints = computed(() =>
+  snapEnabled.value ? [0.38, 0.62, 1] : [],
+);

 async function choose(id: string) {
-  await native.cancelInteractive()
-  await native.replace(`/chat/${id}`, { presentation: 'push' })
+  await native.cancelInteractive();
+  await native.replace(`/chat/${id}`, { presentation: "push" });
 }
 </script>

 <template>
-  <NativeDismissGesture as="main" class="screen sheet-screen">
-    <div class="sheet-handle" aria-hidden="true" />
+  <NativeSheet
+    v-model="sheetBreakpoint"
+    class="compose-sheet"
+    aria-label="New message"
+    :breakpoints="sheetBreakpoints"
+    :initial-breakpoint="0.62"
+  >
+    <main class="compose-sheet-content">
      <header class="sheet-header">
        <button type="button" @click="native.dismiss()">Cancel</button>
+        <div>
          <h1>New message</h1>
-      <span />
+          <small data-testid="sheet-size">
+            {{ snapEnabled ? `${Math.round(sheetBreakpoint * 100)}%` : "Auto" }}
+          </small>
+        </div>
+        <button type="button" @click="snapEnabled = !snapEnabled">
+          {{ snapEnabled ? "Fit content" : "Use snap points" }}
+        </button>
      </header>
      <label class="search-field compose-search">
        <span>To:</span>
        <input v-model="query" autofocus placeholder="Search people" />
      </label>
      <div class="conversation-list">
-      <button v-for="person in store.people.value.filter((item) => item.name.toLowerCase().includes(query.toLowerCase()))" :key="person.id" class="conversation-row" @click="choose(person.id)">
+        <button
+          v-for="person in store.people.value.filter((item) =>
+            item.name.toLowerCase().includes(query.toLowerCase()),
+          )"
+          :key="person.id"
+          class="conversation-row"
+          @click="choose(person.id)"
+        >
          <AppAvatar :person="person" />
-        <div class="conversation-copy"><strong>{{ person.name }}</strong><p>{{ person.handle }}</p></div>
+          <div class="conversation-copy">
+            <strong>{{ person.name }}</strong>
+            <p>{{ person.handle }}</p>
+          </div>
          <span class="chevron">›</span>
        </button>
      </div>
-  </NativeDismissGesture>
+    </main>
+  </NativeSheet>
 </template>
@@ -1,6 +1,13 @@
 <script setup lang="ts">
-import { NativeLink } from '@native-vue-router/core'
-import AppHeader from '../components/AppHeader.vue'
+import { NativeLink, useNativeRouter } from "@native-vue-router/core";
+import AppHeader from "../components/AppHeader.vue";
+import { setStoryEntryBlocked, storyEntryGuard } from "../guard-state";
+
+const native = useNativeRouter();
+
+function toggleStoryGuard() {
+  setStoryEntryBlocked(!storyEntryGuard.blockEntry);
+}
 </script>

 <template>
@@ -17,9 +24,35 @@ import AppHeader from '../components/AppHeader.vue'
      </div>
    </section>
    <section class="settings-list">
-      <NativeLink to="/settings"><span>⚙︎</span><strong>Navigation lab</strong><i>›</i></NativeLink>
-      <a href="https://github.com" target="_blank" rel="noreferrer"><span>⌘</span><strong>Project source</strong><i>↗</i></a>
-      <button type="button"><span>◐</span><strong>Appearance</strong><i>System</i></button>
+      <a
+        href="/profile/runtime-lab"
+        @click.prevent="native.sibling('/profile/runtime-lab')"
+        ><span>⌁</span><strong>Runtime stress lab</strong><i>›</i></a
+      >
+      <button
+        type="button"
+        aria-label="Block Stories re-entry"
+        :aria-pressed="storyEntryGuard.blockEntry"
+        @click="toggleStoryGuard"
+      >
+        <span>⌽</span><strong>Block cached Stories re-entry</strong
+        ><i data-testid="story-guard-status">{{
+          storyEntryGuard.blockEntry ? storyEntryGuard.status : "Off"
+        }}</i>
+      </button>
+      <NativeLink to="/settings"
+        ><span>⚙︎</span><strong>Navigation lab</strong><i>›</i></NativeLink
+      >
+      <NativeLink to="/profile/vue-lab/alpha?mode=manual#route-state"
+        ><span>Vue</span><strong>Vue compatibility lab</strong
+        ><i>›</i></NativeLink
+      >
+      <a href="https://github.com" target="_blank" rel="noreferrer"
+        ><span>⌘</span><strong>Project source</strong><i>↗</i></a
+      >
+      <button type="button">
+        <span>◐</span><strong>Appearance</strong><i>System</i>
+      </button>
    </section>
  </main>
 </template>
@@ -0,0 +1,66 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import { useNativeViewActiveEffect } from '@native-vue-router/core'
+import AppHeader from '../components/AppHeader.vue'
+import AsyncLabData from '../components/AsyncLabData.vue'
+import { runtimeLabGuard } from '../guard-state'
+
+const mountedSeconds = ref(0)
+const mountedAt = Date.now()
+const mountId = crypto.randomUUID()
+
+useNativeViewActiveEffect(() => {
+  const update = () => {
+    mountedSeconds.value = Math.floor((Date.now() - mountedAt) / 1_000)
+  }
+  update()
+  const timer = window.setInterval(update, 200)
+  return () => window.clearInterval(timer)
+})
+</script>
+
+<template>
+  <main class="screen screen--tabs runtime-lab-screen" data-testid="runtime-lab-view" :data-mount-id="mountId">
+    <AppHeader title="Runtime stress lab" subtitle="A cached push-history sibling" back />
+
+    <section class="lab-intro lab-intro--timer">
+      <span>{{ mountedSeconds }}</span>
+      <div>
+        <strong>Seconds mounted</strong>
+        <p
+          data-testid="mounted-seconds"
+          :data-seconds="mountedSeconds"
+        >Elapsed mount time is preserved, while interval work pauses whenever this view is inactive.</p>
+      </div>
+    </section>
+
+    <section class="settings-group">
+      <h2>Suspense boundary</h2>
+      <Suspense :timeout="0">
+        <AsyncLabData />
+        <template #fallback>
+          <article class="lab-probe lab-probe--loading" data-testid="async-data-loading" aria-live="polite">
+            <span class="lab-spinner" aria-hidden="true" />
+            <div>
+              <strong>Waiting for async payload</strong>
+              <p>Data becomes available one second after the child mounts.</p>
+            </div>
+          </article>
+        </template>
+      </Suspense>
+    </section>
+
+    <section class="settings-group">
+      <h2>Guard and history state</h2>
+      <div>
+        <span><strong>Entry guard</strong><small>Asynchronous check #{{ runtimeLabGuard.checks }}</small></span>
+        <b data-testid="lab-guard-status" :class="{ offline: runtimeLabGuard.status === 'blocked' }">{{ runtimeLabGuard.status }}</b>
+      </div>
+      <div>
+        <span><strong>Sibling history</strong><small>This route pushes instead of replacing Profile</small></span>
+        <b>push</b>
+      </div>
+      <p>Use Back to return to Profile. Because this is a pushed sibling, it is unmounted after its exit animation; replaced primary siblings remain lazily cached instead.</p>
+    </section>
+  </main>
+</template>
@@ -1,9 +1,48 @@
 <script setup lang="ts">
+import { ref } from 'vue'
+import { useNativeRouter } from '@native-vue-router/core'
 import AppHeader from '../components/AppHeader.vue'
 import { useDemoStore } from '../data'
-import { pwaEnvironment } from '../pwa'
+import {
+  profilerHasCapture,
+  profilerRecording,
+  shareDemoProfile,
+  startDemoProfile,
+  stopDemoProfile,
+} from '../navigation-profiler'
+import { pwaBuildId, pwaEnvironment } from '../pwa'

 const store = useDemoStore()
+const native = useNativeRouter()
+const unloadResult = ref('Unload cached Stories')
+const profileStatus = ref(profilerRecording.value ? 'Recording navigation now' : 'Ready to record')
+
+function describeProfile(report: ReturnType<typeof stopDemoProfile>) {
+  return `${report.transactions.length} navigations · ${report.summary.droppedFrames} dropped frames · ${report.summary.p95FrameMs} ms p95`
+}
+
+function startProfile() {
+  startDemoProfile(native)
+  profileStatus.value = 'Recording. Leave this page, reproduce the jank, then return here.'
+}
+
+function stopProfile() {
+  profileStatus.value = describeProfile(stopDemoProfile(native))
+}
+
+async function exportProfile() {
+  try {
+    const result = await shareDemoProfile(native)
+    profileStatus.value = `${describeProfile(result.report)} · ${result.method}`
+  } catch (error) {
+    if ((error as DOMException)?.name !== 'AbortError') profileStatus.value = 'Profile export failed'
+  }
+}
+
+function unloadStories() {
+  const count = native.unload('/stories')
+  unloadResult.value = count ? `Unloaded ${count} Stories view` : 'Stories is not cached'
+}
 </script>

 <template>
@@ -17,10 +56,30 @@ const store = useDemoStore()
      <h2>PWA environment</h2>
      <div><span><strong>Display mode</strong><small>Home Screen installation state</small></span><b :class="{ offline: !pwaEnvironment.standalone }">{{ pwaEnvironment.standalone ? 'Standalone' : 'Browser tab' }}</b></div>
      <div><span><strong>Offline worker</strong><small>Cached application shell</small></span><b :class="{ offline: pwaEnvironment.serviceWorker !== 'ready' }">{{ pwaEnvironment.serviceWorker }}</b></div>
+      <div><span><strong>App build</strong><small>{{ pwaBuildId }}</small></span><b :class="{ offline: pwaEnvironment.updateState === 'error' }">{{ pwaEnvironment.updateState }} · {{ pwaEnvironment.updateChecks }} checks</b></div>
      <div><span><strong>iOS edge ownership</strong><small>Leading-edge touches claimed by this app: {{ pwaEnvironment.edgeClaims }}</small></span><b :class="{ offline: !pwaEnvironment.edgeGuard }">{{ pwaEnvironment.edgeGuard ? 'App reserved' : pwaEnvironment.ios ? 'Install required' : 'Not iOS' }}</b></div>
      <p v-if="pwaEnvironment.ios && !pwaEnvironment.standalone">In Safari, choose Share → Add to Home Screen, then launch the new icon. Edge interception is intentionally disabled inside a normal browser tab.</p>
      <p v-else-if="pwaEnvironment.ios">The leading edge is reserved before WebKit navigation begins. Open a conversation and drag from the extreme left edge to verify the live back preview.</p>
    </section>
+    <section class="settings-group">
+      <h2>Frame pacing profiler</h2>
+      <div><span><strong>{{ profilerRecording ? 'Recording' : 'Profiler idle' }}</strong><small data-testid="profile-status">{{ profileStatus }}</small></span><b :class="{ offline: !profilerRecording }">{{ profilerRecording ? 'LIVE' : 'OFF' }}</b></div>
+      <p>Start here, reproduce the choppy navigation, return here, then stop and export. The JSON includes rAF frame intervals and navigation phases but omits route params, query values, and application data.</p>
+    </section>
+    <div class="profiler-controls">
+      <button type="button" data-testid="profile-start" :disabled="profilerRecording" @click="startProfile">Start profiling</button>
+      <button type="button" data-testid="profile-stop" :disabled="!profilerRecording" @click="stopProfile">Stop</button>
+      <button type="button" data-testid="profile-export" :disabled="!profilerHasCapture" @click="exportProfile">Share JSON</button>
+    </div>
+    <section class="settings-group">
+      <h2>Native view cache</h2>
+      <div><span><strong>Mounted views</strong><small>{{ native.cacheStats.value.inactive }} inactive of {{ native.cacheStats.value.maxInactive }} allowed</small></span><b data-testid="cache-mounted">{{ native.cacheStats.value.mounted }}</b></div>
+      <div><span><strong>Route descriptors</strong><small>{{ native.cacheStats.value.evicted }} currently evicted</small></span><b>{{ native.cacheStats.value.descriptors }}</b></div>
+      <div><span><strong>Total evictions</strong><small>{{ native.cacheStats.value.lastEviction?.reason ?? 'No eviction yet' }}</small></span><b data-testid="cache-evictions">{{ native.cacheStats.value.totalEvictions }}</b></div>
+      <p>Sibling tabs are created on first visit, then retained. Back-stack screens stay warm only while they remain useful as a predictive-back target.</p>
+    </section>
+    <button class="reset-button reset-button--neutral" type="button" @click="native.trimCache()">Trim inactive view cache</button>
+    <button class="reset-button reset-button--neutral" data-testid="unload-stories" type="button" @click="unloadStories">{{ unloadResult }}</button>
    <section class="settings-group">
      <h2>Simulation</h2>
      <label><span><strong>Network latency</strong><small>{{ store.settings.simulatedLatency }} ms</small></span><input v-model.number="store.settings.simulatedLatency" type="range" min="0" max="1200" step="20" /></label>
@@ -1,9 +1,25 @@
 <script setup lang="ts">
+import { ref } from 'vue'
+import { useNativeViewActiveEffect } from '@native-vue-router/core'
 import AppAvatar from '../components/AppAvatar.vue'
 import AppHeader from '../components/AppHeader.vue'
 import { useDemoStore } from '../data'

 const store = useDemoStore()
+const mountId = crypto.randomUUID()
+const mountedAt = Date.now()
+const mountedSeconds = ref(0)
+const activeTicks = ref(0)
+
+useNativeViewActiveEffect(() => {
+  const update = () => {
+    mountedSeconds.value = Math.floor((Date.now() - mountedAt) / 1_000)
+    activeTicks.value += 1
+  }
+  update()
+  const timer = window.setInterval(update, 200)
+  return () => window.clearInterval(timer)
+})
 const gradients = [
  'linear-gradient(155deg, #f4a261, #d64e7d 48%, #5427a8)',
  'linear-gradient(155deg, #44c6e9, #4378db 48%, #1b245d)',
@@ -13,7 +29,13 @@ const gradients = [
 </script>

 <template>
-  <main class="screen screen--tabs">
+  <main
+    class="screen screen--tabs"
+    data-testid="stories-view"
+    :data-mount-id="mountId"
+    :data-mounted-seconds="mountedSeconds"
+    :data-active-ticks="activeTicks"
+  >
    <AppHeader title="Stories" subtitle="Moments from your circle" large />
    <section class="story-grid">
      <article v-for="(person, index) in store.people.value.slice(0, 4)" :key="person.id" class="story-card" :style="{ background: gradients[index] }">
@@ -26,6 +48,6 @@ const gradients = [
        <span class="story-card__mark">{{ ['✦', '◌', '△', '◇'][index] }}</span>
      </article>
    </section>
-    <p class="gesture-tip">Swipe horizontally anywhere to move between primary routes.</p>
+    <p class="gesture-tip">Mounted {{ mountedSeconds }}s · active work {{ activeTicks }} ticks. The tick loop pauses while this sibling is cached.</p>
  </main>
 </template>
@@ -0,0 +1,103 @@
+<script setup lang="ts">
+import { computed, ref } from "vue";
+import { useNativeRouter } from "@native-vue-router/core";
+import { useRoute } from "vue-router";
+import AppHeader from "../components/AppHeader.vue";
+import {
+  compatibilityLab,
+  recordCompatibilityEvent,
+} from "../compatibility-lab";
+
+const route = useRoute();
+const native = useNativeRouter();
+const unloadStatus = ref("Lab remains cached");
+const labLocation = computed(() => ({
+  name: "vue-compatibility",
+  params: { sample: route.params.sample },
+  query: route.query,
+  hash: route.hash,
+}));
+
+function unloadLab() {
+  const count = native.unload(labLocation.value);
+  unloadStatus.value = count
+    ? "Lab view evicted; Back will create a new instance"
+    : "No matching inactive lab view was mounted";
+  recordCompatibilityEvent("Away screen", "native.unload", `${count} view(s)`);
+}
+
+async function unloadAndReturn() {
+  unloadLab();
+  await native.pop();
+}
+</script>
+
+<template>
+  <main
+    class="screen compatibility-screen"
+    data-testid="vue-compatibility-away"
+  >
+    <AppHeader
+      title="Cached-route checkpoint"
+      subtitle="The compatibility lab is behind this view"
+      back
+    />
+
+    <section class="lab-intro compat-intro">
+      <span>↩</span>
+      <div>
+        <strong>Inspect native cache behavior</strong>
+        <p>
+          The previous lab instance is inactive but still mounted until you
+          explicitly unload it.
+        </p>
+      </div>
+    </section>
+
+    <section class="settings-group">
+      <h2>Inactive route controls</h2>
+      <div>
+        <span
+          ><strong>Compatibility lab</strong
+          ><small>{{ unloadStatus }}</small></span
+        ><b>behind</b>
+      </div>
+      <p>
+        Use normal Back to observe native activate/show without Vue remount
+        hooks. Use “Unload and return” to observe beforeUnmount/unmounted
+        followed by a fresh component instance.
+      </p>
+    </section>
+    <div class="compat-controls">
+      <button type="button" data-testid="compat-unload-lab" @click="unloadLab">
+        Unload cached lab
+      </button>
+      <button
+        type="button"
+        data-testid="compat-unload-return"
+        @click="unloadAndReturn"
+      >
+        Unload and return
+      </button>
+    </div>
+
+    <section class="settings-group compat-event-section">
+      <div class="compat-event-heading">
+        <span
+          ><strong>Shared lifecycle journal</strong
+          ><small>Events survive route eviction</small></span
+        >
+      </div>
+      <ol class="compat-event-log" data-testid="compat-away-event-log">
+        <li v-for="event in compatibilityLab.events" :key="event.id">
+          <time>{{ event.timestamp }}</time>
+          <span
+            ><strong>{{ event.source }}</strong
+            ><code>{{ event.hook }}</code></span
+          >
+          <small>{{ event.detail }}</small>
+        </li>
+      </ol>
+    </section>
+  </main>
+</template>
@@ -0,0 +1,427 @@
+<script setup lang="ts">
+import {
+  computed,
+  onBeforeUnmount,
+  onMounted,
+  onUnmounted,
+  provide,
+  ref,
+} from "vue";
+import {
+  onNativeViewActivate,
+  onNativeViewDeactivate,
+  onNativeViewEvict,
+  onNativeViewHide,
+  onNativeViewShow,
+  useNativeRouter,
+  useNativeViewLifecycle,
+} from "@native-vue-router/core";
+import { useRoute } from "vue-router";
+import AppHeader from "../components/AppHeader.vue";
+import CompatibilityAsyncProbe from "../components/CompatibilityAsyncProbe.vue";
+import CompatibilityCompositionProbe from "../components/CompatibilityCompositionProbe.vue";
+import CompatibilityInjectProbe from "../components/CompatibilityInjectProbe.vue";
+import CompatibilityKeepAliveProbe from "../components/CompatibilityKeepAliveProbe.vue";
+import CompatibilityOptionsProbe from "../components/CompatibilityOptionsProbe.vue";
+import {
+  clearCompatibilityEvents,
+  compatibilityLab,
+  compatibilityLabContextKey,
+  recordCompatibilityEvent,
+} from "../compatibility-lab";
+
+const route = useRoute();
+const native = useNativeRouter();
+const nativeLifecycle = useNativeViewLifecycle();
+const instanceId = Math.random().toString(36).slice(2, 7);
+const revision = ref(0);
+const probesMounted = ref(true);
+const keepAliveVariant = ref<"A" | "B">("A");
+const transitionVisible = ref(true);
+const teleportOpen = ref(false);
+const suspenseRequest = ref(1);
+const routeLabel = computed(() => route.fullPath);
+const nativeVisible = nativeLifecycle.isVisible;
+const nativeActive = nativeLifecycle.isActive;
+const eventCount = computed(() => compatibilityLab.events.length);
+
+provide(compatibilityLabContextKey, {
+  source: `Vue compatibility lab ${instanceId}`,
+  routeLabel,
+});
+
+const recordPageEvent = (hook: string, detail?: string) =>
+  recordCompatibilityEvent(`Lab page ${instanceId}`, hook, detail);
+
+onMounted(() => recordPageEvent("onMounted", route.fullPath));
+onBeforeUnmount(() => recordPageEvent("onBeforeUnmount"));
+onUnmounted(() => recordPageEvent("onUnmounted"));
+onNativeViewActivate(() => recordPageEvent("native activate"));
+onNativeViewDeactivate(() => recordPageEvent("native deactivate"));
+onNativeViewShow(() => recordPageEvent("native show"));
+onNativeViewHide(() => recordPageEvent("native hide"));
+onNativeViewEvict((reason) => recordPageEvent("native evict", String(reason)));
+
+function updateProbes() {
+  revision.value += 1;
+  recordPageEvent("revision changed", String(revision.value));
+}
+
+function toggleProbeMount() {
+  probesMounted.value = !probesMounted.value;
+  recordPageEvent(probesMounted.value ? "probes inserted" : "probes removed");
+}
+
+function switchKeptInstance() {
+  keepAliveVariant.value = keepAliveVariant.value === "A" ? "B" : "A";
+}
+
+function recordTransition(hook: string) {
+  recordCompatibilityEvent("Transition", hook);
+}
+
+function reloadSuspense() {
+  suspenseRequest.value += 1;
+}
+
+function pushAlternateRoute() {
+  const sample = route.params.sample === "alpha" ? "beta" : "alpha";
+  void native.push({
+    name: "vue-compatibility",
+    params: { sample },
+    query: { mode: "parameter", revision: revision.value },
+    hash: "#route-state",
+  });
+}
+
+function replaceQueryAndHash() {
+  void native.replace(
+    {
+      name: "vue-compatibility",
+      params: { sample: route.params.sample },
+      query: { mode: "replaced", tick: Date.now().toString().slice(-5) },
+      hash: "#event-log",
+    },
+    { presentation: "fade" },
+  );
+}
+
+function openAwayRoute() {
+  void native.push({
+    name: "vue-compatibility-away",
+    params: { sample: route.params.sample },
+    query: route.query,
+    hash: route.hash,
+  });
+}
+</script>
+
+<template>
+  <main
+    class="screen compatibility-screen"
+    data-testid="vue-compatibility-view"
+    :data-instance-id="instanceId"
+  >
+    <AppHeader
+      title="Vue compatibility"
+      subtitle="Native component laboratory"
+      back
+    >
+      <span class="compat-header-state" :class="{ active: nativeActive }">{{
+        nativeActive ? "active" : nativeVisible ? "transitioning" : "cached"
+      }}</span>
+    </AppHeader>
+
+    <section class="lab-intro compat-intro">
+      <span>Vue</span>
+      <div>
+        <strong>Exercise real framework behavior</strong>
+        <p>
+          Every control below runs inside a routed, cached NativeRouterView
+          entry.
+        </p>
+      </div>
+    </section>
+
+    <section
+      id="route-state"
+      class="settings-group compat-route-state"
+      data-testid="compat-route-state"
+    >
+      <h2>Scoped route state</h2>
+      <div>
+        <span
+          ><strong>Full path</strong
+          ><small>useRoute() and Options API $route</small></span
+        ><code data-testid="compat-full-path">{{ route.fullPath }}</code>
+      </div>
+      <div>
+        <span
+          ><strong>Named route</strong
+          ><small>Matched record identity</small></span
+        ><code>{{ String(route.name) }}</code>
+      </div>
+      <div>
+        <span><strong>Param</strong><small>route.params.sample</small></span
+        ><code data-testid="compat-param">{{ route.params.sample }}</code>
+      </div>
+      <div>
+        <span><strong>Query</strong><small>route.query</small></span
+        ><code data-testid="compat-query">{{
+          JSON.stringify(route.query)
+        }}</code>
+      </div>
+      <div>
+        <span><strong>Hash</strong><small>route.hash</small></span
+        ><code data-testid="compat-hash">{{ route.hash || "(empty)" }}</code>
+      </div>
+      <div>
+        <span><strong>Matched</strong><small>route.matched</small></span
+        ><code>{{
+          route.matched.map((record) => String(record.name)).join(" → ")
+        }}</code>
+      </div>
+    </section>
+    <div class="compat-controls compat-controls--three">
+      <button
+        type="button"
+        data-testid="compat-change-param"
+        @click="pushAlternateRoute"
+      >
+        Push alternate param
+      </button>
+      <button
+        type="button"
+        data-testid="compat-change-query"
+        @click="replaceQueryAndHash"
+      >
+        Replace query + hash
+      </button>
+      <button
+        type="button"
+        data-testid="compat-open-away"
+        @click="openAwayRoute"
+      >
+        Cache this view
+      </button>
+    </div>
+
+    <section class="settings-group">
+      <h2>provide() / inject()</h2>
+      <CompatibilityInjectProbe location="route tree" />
+      <p>
+        The same probe is rendered inside the Teleport below to verify
+        logical-tree injection and scoped routing.
+      </p>
+    </section>
+
+    <section class="settings-group">
+      <h2>Options and Composition lifecycle</h2>
+      <div>
+        <span
+          ><strong>Shared revision</strong
+          ><small>Changing it triggers beforeUpdate / updated</small></span
+        ><b data-testid="compat-revision">{{ revision }}</b>
+      </div>
+      <div class="compat-inline-actions">
+        <button
+          type="button"
+          data-testid="compat-update-probes"
+          @click="updateProbes"
+        >
+          Update props
+        </button>
+        <button
+          type="button"
+          data-testid="compat-toggle-probes"
+          @click="toggleProbeMount"
+        >
+          {{ probesMounted ? "Unmount probes" : "Mount probes" }}
+        </button>
+      </div>
+      <div v-if="probesMounted" class="compat-probe-grid">
+        <CompatibilityOptionsProbe
+          :instance-name="`Options ${instanceId}`"
+          :revision="revision"
+        />
+        <CompatibilityCompositionProbe
+          :instance-name="`Composition ${instanceId}`"
+          :revision="revision"
+        />
+      </div>
+    </section>
+
+    <section class="settings-group">
+      <h2>KeepAlive</h2>
+      <div>
+        <span
+          ><strong>Current cached child</strong
+          ><small>Switch away and back after incrementing</small></span
+        ><b>{{ keepAliveVariant }}</b>
+      </div>
+      <div class="compat-inline-actions">
+        <button
+          type="button"
+          data-testid="compat-switch-keepalive"
+          @click="switchKeptInstance"
+        >
+          Switch to {{ keepAliveVariant === "A" ? "B" : "A" }}
+        </button>
+      </div>
+      <KeepAlive>
+        <CompatibilityKeepAliveProbe
+          :key="keepAliveVariant"
+          :name="keepAliveVariant"
+        />
+      </KeepAlive>
+    </section>
+
+    <section class="settings-group">
+      <h2>Transition</h2>
+      <div>
+        <span
+          ><strong>CSS transition target</strong
+          ><small>Hooks are recorded in the event journal</small></span
+        ><b>{{ transitionVisible ? "shown" : "removed" }}</b>
+      </div>
+      <div class="compat-inline-actions">
+        <button
+          type="button"
+          data-testid="compat-toggle-transition"
+          @click="transitionVisible = !transitionVisible"
+        >
+          Toggle transition
+        </button>
+      </div>
+      <Transition
+        name="compat-fade"
+        @before-enter="recordTransition('before-enter')"
+        @after-enter="recordTransition('after-enter')"
+        @before-leave="recordTransition('before-leave')"
+        @after-leave="recordTransition('after-leave')"
+      >
+        <article
+          v-if="transitionVisible"
+          class="compat-transition-card"
+          data-testid="compat-transition-card"
+        >
+          Transition child is mounted
+        </article>
+      </Transition>
+    </section>
+
+    <section class="settings-group">
+      <h2>Teleport</h2>
+      <div>
+        <span
+          ><strong>Body-level overlay</strong
+          ><small
+            >Automatically hidden when this native view is inactive</small
+          ></span
+        ><b>{{ teleportOpen ? "armed" : "closed" }}</b>
+      </div>
+      <div class="compat-inline-actions">
+        <button
+          type="button"
+          data-testid="compat-open-teleport"
+          @click="teleportOpen = true"
+        >
+          Open teleported overlay
+        </button>
+      </div>
+    </section>
+
+    <Teleport to="body">
+      <Transition name="compat-fade">
+        <div
+          v-if="teleportOpen && nativeVisible"
+          class="compat-teleport"
+          data-testid="compat-teleport-overlay"
+          @click.self="teleportOpen = false"
+        >
+          <section
+            role="dialog"
+            aria-modal="true"
+            aria-labelledby="compat-teleport-title"
+          >
+            <button
+              type="button"
+              aria-label="Close teleported overlay"
+              @click="teleportOpen = false"
+            >
+              ×
+            </button>
+            <h2 id="compat-teleport-title">Teleported route content</h2>
+            <CompatibilityInjectProbe location="teleport" />
+          </section>
+        </div>
+      </Transition>
+    </Teleport>
+
+    <section class="settings-group">
+      <h2>Suspense</h2>
+      <div>
+        <span
+          ><strong>Async setup request</strong
+          ><small>Fallback remains for 750 ms</small></span
+        ><b>#{{ suspenseRequest }}</b>
+      </div>
+      <div class="compat-inline-actions">
+        <button
+          type="button"
+          data-testid="compat-reload-suspense"
+          @click="reloadSuspense"
+        >
+          Reload async child
+        </button>
+      </div>
+      <Suspense
+        :key="suspenseRequest"
+        :timeout="0"
+        @pending="recordCompatibilityEvent('Suspense', 'pending')"
+        @fallback="recordCompatibilityEvent('Suspense', 'fallback')"
+        @resolve="recordCompatibilityEvent('Suspense', 'resolve')"
+      >
+        <CompatibilityAsyncProbe :request-id="suspenseRequest" />
+        <template #fallback>
+          <article
+            class="compat-probe compat-probe--loading"
+            data-testid="compat-suspense-fallback"
+          >
+            <span class="lab-spinner" />
+            <div>
+              <strong>Suspense fallback</strong>
+              <p>Waiting for async setup…</p>
+            </div>
+          </article>
+        </template>
+      </Suspense>
+    </section>
+
+    <section id="event-log" class="settings-group compat-event-section">
+      <div class="compat-event-heading">
+        <span
+          ><strong>Lifecycle event journal</strong
+          ><small>{{ eventCount }} retained events · newest first</small></span
+        >
+        <button
+          type="button"
+          data-testid="compat-clear-events"
+          @click="clearCompatibilityEvents"
+        >
+          Clear
+        </button>
+      </div>
+      <ol class="compat-event-log" data-testid="compat-event-log">
+        <li v-for="event in compatibilityLab.events" :key="event.id">
+          <time>{{ event.timestamp }}</time>
+          <span
+            ><strong>{{ event.source }}</strong
+            ><code>{{ event.hook }}</code></span
+          >
+          <small>{{ event.detail }}</small>
+        </li>
+      </ol>
+    </section>
+  </main>
+</template>
@@ -61,6 +61,8 @@ function createWindow() {
        { label: 'Back', accelerator: 'Alt+Left', click: () => window.webContents.send('native-vue:back') },
        { label: 'Forward', accelerator: 'Alt+Right', click: () => window.webContents.send('native-vue:forward') },
        { type: 'separator' },
+        { label: 'Trim Navigation Cache', click: () => window.webContents.send('native-vue:memory-pressure') },
+        { type: 'separator' },
        { role: 'reload' },
      ],
    },
@@ -9,4 +9,5 @@ function listener(channel, callback) {
 contextBridge.exposeInMainWorld('nativeVueHost', {
  onBack: (callback) => listener('native-vue:back', callback),
  onForward: (callback) => listener('native-vue:forward', callback),
+  onMemoryPressure: (callback) => listener('native-vue:memory-pressure', callback),
 })
@@ -0,0 +1 @@
+dev-dist
@@ -0,0 +1,25 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, viewport-fit=cover"
+    />
+    <meta name="theme-color" content="#080b12" />
+    <meta name="apple-mobile-web-app-capable" content="yes" />
+    <meta
+      name="apple-mobile-web-app-status-bar-style"
+      content="black-translucent"
+    />
+    <meta name="apple-mobile-web-app-title" content="Origins" />
+    <meta name="format-detection" content="telephone=no" />
+    <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png" />
+    <link rel="icon" href="/favicon.svg" />
+    <title>Routeless Origins Lab</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
@@ -0,0 +1,22 @@
+{
+  "name": "@native-vue-router/origins-demo",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite --config vite.config.ts --host",
+    "build": "vue-tsc -p tsconfig.json --noEmit && vite build --config vite.config.ts",
+    "preview": "vite preview --config vite.config.ts --host 0.0.0.0 --port 5173"
+  },
+  "dependencies": {
+    "@native-vue-router/core-v2": "0.1.0-experimental.0",
+    "vue": "^3.5.39"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^6.0.7",
+    "typescript": "~6.0.2",
+    "vite": "^8.1.1",
+    "vite-plugin-pwa": "^1.1.0",
+    "vue-tsc": "^3.3.5"
+  }
+}
@@ -0,0 +1,78 @@
+<script setup lang="ts">
+import {
+  OriginScene,
+  createOriginScene,
+  originView,
+} from "@native-vue-router/core-v2";
+import { labEvents } from "./lab-state";
+import HubView from "./views/HubView.vue";
+
+/*
+ * This scene is the entire application state for the experiment. There is no
+ * Vue Router installation, route table, URL, or hidden RouterView.
+ */
+const scene = createOriginScene({
+  initial: originView(HubView, undefined, {
+    key: "origins-lab",
+    name: "Origins Lab",
+  }),
+});
+</script>
+
+<template>
+  <div class="demo-shell">
+    <OriginScene :scene="scene" />
+
+    <details class="scene-debug">
+      <summary>
+        <span
+          class="debug-pulse"
+          :class="{ live: scene.operations.value.length }"
+        />
+        {{ scene.nodes.value.length }} node{{
+          scene.nodes.value.length === 1 ? "" : "s"
+        }}
+      </summary>
+      <div class="debug-content" aria-live="polite">
+        <section>
+          <strong>Scene graph</strong>
+          <ol>
+            <li v-for="node in scene.nodes.value" :key="node.key">
+              <span>
+                {{ node.view.name }}
+                <em :class="`node-state node-state--${node.state}`">
+                  {{ node.state }}
+                </em>
+              </span>
+              <code>{{ node.key.split("::").at(-1) }}</code>
+            </li>
+          </ol>
+        </section>
+        <section v-if="scene.operations.value.length">
+          <strong>Animation edges</strong>
+          <div
+            v-for="operation in scene.operations.value"
+            :key="operation.id"
+            class="debug-operation"
+          >
+            <span>{{ operation.choreography.name }}</span>
+            <progress :value="operation.progress" max="1" />
+            <small>
+              {{ operation.phase }} ·
+              {{ Math.round(operation.progress * 100) }}%
+            </small>
+          </div>
+        </section>
+        <section>
+          <strong>Recent Vue lifecycle</strong>
+          <ul class="event-log">
+            <li v-for="event in labEvents.slice(0, 6)" :key="event.id">
+              <time>{{ event.time }}</time>
+              {{ event.message }}
+            </li>
+          </ul>
+        </section>
+      </div>
+    </details>
+  </div>
+</template>
@@ -0,0 +1,15 @@
+<script setup lang="ts">
+defineProps<{
+  label: string;
+  instance: string;
+  status: string;
+}>();
+</script>
+
+<template>
+  <div class="instance-card">
+    <span>{{ label }}</span>
+    <strong>{{ instance }}</strong>
+    <small>{{ status }}</small>
+  </div>
+</template>
@@ -0,0 +1,37 @@
+export interface DemoPhoto {
+  id: string;
+  title: string;
+  location: string;
+  gradient: string;
+  description: string;
+}
+
+export const demoPhotos: readonly DemoPhoto[] = [
+  {
+    id: "ember",
+    title: "Afterglow",
+    location: "Reykjanes · 23:14",
+    gradient:
+      "radial-gradient(circle at 72% 25%, #ffcc8a 0, #ff774d 18%, transparent 43%), linear-gradient(145deg, #622c54, #171526 72%)",
+    description:
+      "A warm focus portal demonstrates scale, blur, opacity, and rounded-corner effects.",
+  },
+  {
+    id: "tide",
+    title: "Low tide",
+    location: "Lofoten · 05:42",
+    gradient:
+      "radial-gradient(circle at 25% 25%, #b8f2ff 0, #3f9eb8 24%, transparent 48%), linear-gradient(160deg, #123b50, #07131f 72%)",
+    description:
+      "Swipe left while this view is present to create the next photo as another origin.",
+  },
+  {
+    id: "moss",
+    title: "Quiet giant",
+    location: "Yakushima · 16:08",
+    gradient:
+      "radial-gradient(circle at 64% 30%, #d9ff9f 0, #608b52 22%, transparent 45%), linear-gradient(145deg, #294235, #091812 74%)",
+    description:
+      "The like button is component-local state. Move forward, then return to see the same retained instance and state.",
+  },
+];
@@ -0,0 +1,49 @@
+import { onBeforeUnmount, onMounted, reactive, ref } from "vue";
+
+export interface LabEvent {
+  id: number;
+  message: string;
+  time: string;
+}
+
+let instanceSequence = 0;
+let eventSequence = 0;
+
+export const labEvents = reactive<LabEvent[]>([]);
+
+export function recordLabEvent(message: string) {
+  labEvents.unshift({
+    id: ++eventSequence,
+    message,
+    time: new Date().toLocaleTimeString([], {
+      hour: "2-digit",
+      minute: "2-digit",
+      second: "2-digit",
+    }),
+  });
+  if (labEvents.length > 18) labEvents.length = 18;
+}
+
+/**
+ * Give every Vue setup execution a visible identity. A scene-edge collapse
+ * and a forward push both retain the ID. A committed back only unmounts the
+ * entry being popped, then reveals the exact previous instance.
+ */
+export function useDemoInstance(label: string) {
+  const instance = `${label.slice(0, 2).toUpperCase()}-${String(
+    ++instanceSequence,
+  ).padStart(2, "0")}`;
+  const status = ref("created");
+  recordLabEvent(`${instance} created`);
+
+  onMounted(() => {
+    status.value = "mounted";
+    recordLabEvent(`${instance} mounted`);
+  });
+  onBeforeUnmount(() => {
+    status.value = "unmounting";
+    recordLabEvent(`${instance} unmounted`);
+  });
+
+  return { instance, status };
+}
@@ -0,0 +1,13 @@
+import { createApp } from "vue";
+import { registerSW } from "virtual:pwa-register";
+import App from "./App.vue";
+import "./style.css";
+
+/*
+ * Registration is deliberately immediate so an installed app becomes
+ * offline-capable during its first session. `autoUpdate` in the Vite plugin
+ * activates a fresh build without requiring a custom update prompt yet.
+ */
+registerSW({ immediate: true });
+
+createApp(App).mount("#app");
@@ -0,0 +1,376 @@
+import { defineOriginChoreography } from "@native-vue-router/core-v2";
+
+const percent = (value: number) => `${(value * 100).toFixed(3)}%`;
+
+/** A bottom-up cover similar to presenting a native media player. */
+export const coverUp = defineOriginChoreography({
+  name: "cover-up",
+  commitThreshold: 0.3,
+  commitVelocity: 0.75,
+  effects: ({ progress }) => ({
+    source: {
+      transform: `translate3d(0, ${percent(progress * -0.035)}, 0) scale(${1 - progress * 0.055})`,
+      opacity: 1 - progress * 0.22,
+      style: { filter: `saturate(${1 - progress * 0.3})` },
+    },
+    target: {
+      transform: `translate3d(0, ${percent(1 - progress)}, 0)`,
+      style: {
+        borderRadius: `${(1 - progress) * 30}px`,
+        boxShadow: `0 -24px 80px rgb(0 0 0 / ${progress * 0.38})`,
+      },
+    },
+  }),
+});
+
+/** Reverse of coverUp. The retained origin instance is revealed underneath. */
+export const coverDown = defineOriginChoreography({
+  name: "cover-down",
+  commitThreshold: 0.28,
+  commitVelocity: 0.72,
+  effects: ({ progress }) => ({
+    source: {
+      transform: `translate3d(0, ${percent(progress)}, 0)`,
+      style: { borderRadius: `${progress * 30}px` },
+    },
+    target: {
+      transform: `translate3d(0, ${percent(-0.035 + progress * 0.035)}, 0) scale(${0.945 + progress * 0.055})`,
+      opacity: 0.78 + progress * 0.22,
+      style: { filter: `saturate(${0.7 + progress * 0.3})` },
+    },
+  }),
+});
+
+/**
+ * A scale-and-focus transition. Filters use local-last CSS composition while
+ * geometry remains independently composable with any ancestor operation.
+ */
+export const focusPortal = defineOriginChoreography({
+  name: "focus-portal",
+  commitThreshold: 0.32,
+  effects: ({ progress }) => ({
+    source: {
+      transform: `scale(${1 - progress * 0.12})`,
+      opacity: 1 - progress * 0.55,
+      style: { filter: `blur(${progress * 8}px)` },
+    },
+    target: {
+      transform: `translate3d(0, ${percent((1 - progress) * 0.08)}, 0) scale(${0.72 + progress * 0.28})`,
+      opacity: progress,
+      style: {
+        borderRadius: `${(1 - progress) * 42}px`,
+        filter: `blur(${(1 - progress) * 3}px)`,
+      },
+    },
+  }),
+});
+
+export const unfocusPortal = defineOriginChoreography({
+  name: "unfocus-portal",
+  commitThreshold: 0.3,
+  effects: ({ progress }) => ({
+    source: {
+      transform: `translate3d(0, ${percent(progress * 0.08)}, 0) scale(${1 - progress * 0.28})`,
+      opacity: 1 - progress,
+      style: {
+        borderRadius: `${progress * 42}px`,
+        filter: `blur(${progress * 3}px)`,
+      },
+    },
+    target: {
+      transform: `scale(${0.88 + progress * 0.12})`,
+      opacity: 0.45 + progress * 0.55,
+      style: { filter: `blur(${(1 - progress) * 8}px)` },
+    },
+  }),
+});
+
+/** A deliberately expressive transition for the four-direction gesture lab. */
+export const cardFlip = defineOriginChoreography({
+  name: "card-flip",
+  commitThreshold: 0.42,
+  effects: ({ progress }) => ({
+    source: {
+      transform: `perspective(900px) rotateY(${-progress * 86}deg) scale(${1 - progress * 0.08})`,
+      opacity: 1 - progress * 0.68,
+      style: { transformOrigin: "left center" },
+    },
+    target: {
+      transform: `perspective(900px) rotateY(${(1 - progress) * 86}deg) scale(${0.92 + progress * 0.08})`,
+      opacity: 0.3 + progress * 0.7,
+      style: { transformOrigin: "right center" },
+    },
+  }),
+});
+
+/**
+ * The frame contribution affects both sides of the edge. If this operation is
+ * chained, descendants inherit the same small vertical arc.
+ */
+export const arcSlide = defineOriginChoreography({
+  name: "arc-slide",
+  commitThreshold: 0.34,
+  commitVelocity: 0.8,
+  effects: ({ progress }) => ({
+    frame: {
+      transform: `translate3d(0, ${-Math.sin(progress * Math.PI) * 9}px, 0)`,
+    },
+    source: {
+      transform: `translate3d(${percent(progress * -0.28)}, 0, 0) rotate(${-progress * 1.5}deg) scale(${1 - progress * 0.035})`,
+      opacity: 1 - progress * 0.22,
+    },
+    target: {
+      transform: `translate3d(${percent(1 - progress)}, 0, 0) rotate(${(1 - progress) * 2.5}deg)`,
+    },
+  }),
+});
+
+export const rise = defineOriginChoreography({
+  name: "rise",
+  commitThreshold: 0.33,
+  effects: ({ progress }) => ({
+    source: {
+      transform: `translate3d(0, ${percent(progress * -0.18)}, 0) scale(${1 - progress * 0.04})`,
+      opacity: 1 - progress * 0.3,
+    },
+    target: {
+      transform: `translate3d(0, ${percent(1 - progress)}, 0)`,
+    },
+  }),
+});
+
+export const fall = defineOriginChoreography({
+  name: "fall",
+  commitThreshold: 0.33,
+  effects: ({ progress }) => ({
+    source: {
+      transform: `translate3d(0, ${percent(progress)}, 0)`,
+    },
+    target: {
+      transform: `translate3d(0, ${percent(-0.18 + progress * 0.18)}, 0) scale(${0.96 + progress * 0.04})`,
+      opacity: 0.7 + progress * 0.3,
+    },
+  }),
+});
+
+/**
+ * A connected presentation rather than a full-screen route replacement.
+ *
+ * At rest the page has moved right by two thirds, leaving its left third
+ * visible in the exposed rail. `persistAtRest` keeps these progress-1 effects
+ * connected after commit instead of parking and hiding the page.
+ */
+export const partialDrawerOpen = defineOriginChoreography({
+  name: "partial-drawer-open",
+  persistAtRest: true,
+  commitThreshold: 0.28,
+  commitVelocity: 0.68,
+  effects: ({ progress }) => ({
+    source: {
+      transform: `translate3d(${percent(progress * (2 / 3))}, 0, 0)`,
+      style: {
+        filter: `brightness(${1 - progress * 0.22})`,
+      },
+    },
+    target: {
+      transform: `translate3d(${percent((progress - 1) * (2 / 3))}, 0, 0)`,
+      opacity: 0.35 + progress * 0.65,
+      style: {
+        boxShadow: `24px 0 70px rgb(0 0 0 / ${progress * 0.36})`,
+      },
+    },
+  }),
+});
+
+/** Reciprocal close motion for the connected two-thirds drawer. */
+export const partialDrawerClose = defineOriginChoreography({
+  name: "partial-drawer-close",
+  commitThreshold: 0.28,
+  commitVelocity: 0.68,
+  effects: ({ progress }) => ({
+    source: {
+      transform: `translate3d(${percent(progress * (-2 / 3))}, 0, 0)`,
+      opacity: 1 - progress * 0.65,
+      style: {
+        boxShadow: `24px 0 70px rgb(0 0 0 / ${(1 - progress) * 0.36})`,
+      },
+    },
+    target: {
+      transform: `translate3d(${percent((1 - progress) * (2 / 3))}, 0, 0)`,
+      style: {
+        filter: `brightness(${0.78 + progress * 0.22})`,
+      },
+    },
+  }),
+});
+
+/**
+ * Reveal a full-screen overlay from above while its actual dialog remains
+ * anchored to the left. The gesture's custom start predicate lives in the
+ * originating view; choreography remains concerned only with movement.
+ */
+export const dropEdgeDialog = defineOriginChoreography({
+  name: "drop-edge-dialog",
+  commitThreshold: 0.24,
+  commitVelocity: 0.62,
+  effects: ({ progress }) => ({
+    source: {
+      transform: `scale(${1 - progress * 0.025})`,
+      opacity: 1 - progress * 0.38,
+      style: {
+        filter: `saturate(${1 - progress * 0.35})`,
+      },
+    },
+    target: {
+      transform: `translate3d(0, ${percent((1 - progress) * -0.018)}, 0)`,
+      opacity: 1,
+      style: {
+        clipPath: `inset(0 0 ${percent(1 - progress)} 0)`,
+        filter: `drop-shadow(0 28px 70px rgb(0 0 0 / ${progress * 0.55}))`,
+      },
+    },
+  }),
+});
+
+/** Reverse the edge dialog upward and reveal its retained origin instance. */
+export const liftEdgeDialog = defineOriginChoreography({
+  name: "lift-edge-dialog",
+  commitThreshold: 0.24,
+  commitVelocity: 0.62,
+  effects: ({ progress }) => ({
+    source: {
+      transform: `translate3d(0, ${percent(progress * -0.018)}, 0)`,
+      opacity: 1,
+      style: {
+        clipPath: `inset(0 0 ${percent(progress)} 0)`,
+      },
+    },
+    target: {
+      transform: `scale(${0.975 + progress * 0.025})`,
+      opacity: 0.62 + progress * 0.38,
+      style: {
+        filter: `saturate(${0.65 + progress * 0.35})`,
+      },
+    },
+  }),
+});
+
+/**
+ * Compact horizontal motion for a nested carousel. Its smaller source travel
+ * keeps the retained slide visible behind the incoming card.
+ */
+export const nestedCarouselForward = defineOriginChoreography({
+  name: "nested-carousel-forward",
+  commitThreshold: 0.3,
+  commitVelocity: 0.7,
+  effects: ({ progress }) => ({
+    source: {
+      transform: `translate3d(${percent(progress * -0.18)}, 0, 0) scale(${1 - progress * 0.045})`,
+      opacity: 1 - progress * 0.35,
+      style: { filter: `saturate(${1 - progress * 0.25})` },
+    },
+    target: {
+      transform: `translate3d(${percent(1 - progress)}, 0, 0)`,
+      style: {
+        borderRadius: `${(1 - progress) * 28}px`,
+        boxShadow: `-24px 0 60px rgb(0 0 0 / ${progress * 0.3})`,
+      },
+    },
+  }),
+});
+
+/** Reverse reveal for the cooperative nested carousel. */
+export const nestedCarouselBack = defineOriginChoreography({
+  name: "nested-carousel-back",
+  commitThreshold: 0.3,
+  commitVelocity: 0.7,
+  effects: ({ progress }) => ({
+    source: {
+      transform: `translate3d(${percent(progress)}, 0, 0)`,
+      style: { borderRadius: `${progress * 28}px` },
+    },
+    target: {
+      transform: `translate3d(${percent(-0.18 + progress * 0.18)}, 0, 0) scale(${0.955 + progress * 0.045})`,
+      opacity: 0.65 + progress * 0.35,
+      style: { filter: `saturate(${0.75 + progress * 0.25})` },
+    },
+  }),
+});
+
+/**
+ * Vertical nested-deck motion with a shared sideways arc. The frame effect
+ * demonstrates that nested scenes retain the same composition semantics.
+ */
+export const nestedDeckForward = defineOriginChoreography({
+  name: "nested-deck-forward",
+  commitThreshold: 0.32,
+  effects: ({ progress }) => ({
+    frame: {
+      transform: `translate3d(${Math.sin(progress * Math.PI) * 10}px, 0, 0)`,
+    },
+    source: {
+      transform: `translate3d(0, ${percent(progress * -0.12)}, 0) rotate(${-progress * 2}deg) scale(${1 - progress * 0.06})`,
+      opacity: 1 - progress * 0.4,
+    },
+    target: {
+      transform: `translate3d(0, ${percent(1 - progress)}, 0) rotate(${(1 - progress) * 3}deg)`,
+    },
+  }),
+});
+
+/** Downward reverse of the nested vertical deck. */
+export const nestedDeckBack = defineOriginChoreography({
+  name: "nested-deck-back",
+  commitThreshold: 0.32,
+  effects: ({ progress }) => ({
+    frame: {
+      transform: `translate3d(${-Math.sin(progress * Math.PI) * 10}px, 0, 0)`,
+    },
+    source: {
+      transform: `translate3d(0, ${percent(progress)}, 0) rotate(${progress * 3}deg)`,
+    },
+    target: {
+      transform: `translate3d(0, ${percent(-0.12 + progress * 0.12)}, 0) rotate(${(1 - progress) * -2}deg) scale(${0.94 + progress * 0.06})`,
+      opacity: 0.6 + progress * 0.4,
+    },
+  }),
+});
+
+/**
+ * Intentionally dramatic cube turn used by the conflict case so it is obvious
+ * when the child scene, rather than the page scene, owns the gesture.
+ */
+export const nestedCubeForward = defineOriginChoreography({
+  name: "nested-cube-forward",
+  commitThreshold: 0.38,
+  effects: ({ progress }) => ({
+    source: {
+      transform: `perspective(720px) translate3d(${percent(progress * -0.5)}, 0, 0) rotateY(${progress * 72}deg)`,
+      opacity: 1 - progress * 0.55,
+      style: { transformOrigin: "right center" },
+    },
+    target: {
+      transform: `perspective(720px) translate3d(${percent((1 - progress) * 0.5)}, 0, 0) rotateY(${(progress - 1) * 72}deg)`,
+      opacity: 0.45 + progress * 0.55,
+      style: { transformOrigin: "left center" },
+    },
+  }),
+});
+
+/** Reverse cube turn for retained slides in the conflict case. */
+export const nestedCubeBack = defineOriginChoreography({
+  name: "nested-cube-back",
+  commitThreshold: 0.38,
+  effects: ({ progress }) => ({
+    source: {
+      transform: `perspective(720px) translate3d(${percent(progress * 0.5)}, 0, 0) rotateY(${-progress * 72}deg)`,
+      opacity: 1 - progress * 0.55,
+      style: { transformOrigin: "left center" },
+    },
+    target: {
+      transform: `perspective(720px) translate3d(${percent((progress - 1) * 0.5)}, 0, 0) rotateY(${(1 - progress) * 72}deg)`,
+      opacity: 0.45 + progress * 0.55,
+      style: { transformOrigin: "right center" },
+    },
+  }),
+});
@@ -0,0 +1,65 @@
+<script setup lang="ts">
+import { nextTick, ref } from "vue";
+import { back, slideRight, useOrigin } from "@native-vue-router/core-v2";
+import InstanceCard from "../components/InstanceCard.vue";
+import { useDemoInstance } from "../lab-state";
+
+const origin = useOrigin();
+const identity = useDemoInstance("Chat");
+const draft = ref("");
+const messages = ref([
+  "This page deliberately owns no edge recognizer.",
+  "Try swiping right. Nothing should happen.",
+]);
+
+function goBack() {
+  if (origin.context.value.canGoBack) void origin.perform(back(slideRight));
+}
+
+async function send() {
+  const message = draft.value.trim();
+  if (!message) return;
+  messages.value.push(message);
+  draft.value = "";
+  await nextTick();
+}
+</script>
+
+<template>
+  <!--
+    No gesture binding is used here. Gesture absence is the policy, rather
+    than a global back gesture followed by an exception.
+  -->
+  <div class="chat-view">
+    <header class="chat-header">
+      <button type="button" @click="goBack">←</button>
+      <div class="chat-avatar">M</div>
+      <div>
+        <strong>Maya</strong>
+        <span>online</span>
+      </div>
+      <span class="chat-lock">edge locked</span>
+    </header>
+
+    <main class="messages">
+      <div
+        v-for="(message, index) in messages"
+        :key="`${index}-${message}`"
+        class="message"
+        :class="{ 'message--mine': index > 1 }"
+      >
+        {{ message }}
+      </div>
+      <InstanceCard
+        label="Chat instance"
+        :instance="identity.instance"
+        :status="identity.status.value"
+      />
+    </main>
+
+    <form class="composer" @submit.prevent="send">
+      <input v-model="draft" placeholder="Write something…" />
+      <button type="submit">Send</button>
+    </form>
+  </div>
+</template>
@@ -0,0 +1,116 @@
+<script setup lang="ts">
+import {
+  above,
+  back,
+  gesture,
+  OriginGestureSurface,
+  originView,
+  useOrigin,
+} from "@native-vue-router/core-v2";
+import InstanceCard from "../components/InstanceCard.vue";
+import { useDemoInstance } from "../lab-state";
+import { cardFlip, rise, unfocusPortal } from "../motions";
+import DirectionResultView from "./DirectionResultView.vue";
+
+const origin = useOrigin();
+const identity = useDemoInstance("Direction");
+
+const eastView = () =>
+  originView(
+    DirectionResultView,
+    {
+      direction: "east",
+      heading: "Horizontal declarations can own a full-page flip.",
+      accent: "#38d8ff",
+      createdBy: identity.instance,
+    },
+    { key: "direction-east", name: "East Result" },
+  );
+const openEast = () => above(eastView(), cardFlip);
+
+const northView = () =>
+  originView(
+    DirectionResultView,
+    {
+      direction: "north",
+      heading: "The same origin can create a completely different view upward.",
+      accent: "#b9ff66",
+      createdBy: identity.instance,
+    },
+    { key: "direction-north", name: "North Result" },
+  );
+const openNorth = () => above(northView(), rise);
+
+const flipGesture = gesture.to
+  .left()
+  .navigate(() => above(eastView()))
+  .animate(cardFlip);
+const riseGesture = gesture.to
+  .up()
+  .navigate(() => above(northView()))
+  .animate(rise);
+const backGesture = gesture.from
+  .left("clamp(24px, 8%, 64px)")
+  .to.right()
+  .navigate((context) => (context.canGoBack ? back() : null))
+  .animate(unfocusPortal);
+const gestures = [flipGesture, riseGesture, backGesture] as const;
+
+function perform(action: ReturnType<typeof openEast>) {
+  void origin.perform(action);
+}
+</script>
+
+<template>
+  <OriginGestureSurface
+    as="main"
+    class="lab-page direction-view"
+    :gestures="gestures"
+  >
+    <div class="eyebrow">Lab 02 · Direction matrix</div>
+    <h1>One component. Three explicit choices.</h1>
+    <p>
+      Swipe left for a perspective flip, swipe up for a rising cover, or use the
+      left edge to go back. None of these gestures exist outside this view.
+    </p>
+
+    <div class="direction-compass">
+      <button
+        type="button"
+        data-origin-gesture="ignore"
+        class="compass-action compass-action--up"
+        @click="perform(openNorth())"
+      >
+        <span>↑</span>
+        <strong>Rise</strong>
+        <small>target above</small>
+      </button>
+      <div class="compass-core">
+        <span>origin</span>
+        <strong>{{ identity.instance }}</strong>
+      </div>
+      <button
+        type="button"
+        data-origin-gesture="ignore"
+        class="compass-action compass-action--left"
+        @click="perform(openEast())"
+      >
+        <span>←</span>
+        <strong>Flip left</strong>
+        <small>custom perspective</small>
+      </button>
+    </div>
+
+    <InstanceCard
+      label="Direction view"
+      :instance="identity.instance"
+      :status="identity.status.value"
+    />
+    <div class="gesture-map">
+      <span>↑ full-surface target</span>
+      <span>← full-surface target</span>
+      <span>left edge → history back</span>
+    </div>
+    <div class="edge-marker edge-marker--left">back edge</div>
+  </OriginGestureSurface>
+</template>
@@ -0,0 +1,87 @@
+<script setup lang="ts">
+import {
+  OriginGesture,
+  back,
+  gesture,
+  slideRight,
+  useOrigin,
+  type OriginContext,
+} from "@native-vue-router/core-v2";
+import InstanceCard from "../components/InstanceCard.vue";
+import { useDemoInstance } from "../lab-state";
+import { fall } from "../motions";
+
+const props = defineProps<{
+  direction: "east" | "north";
+  heading: string;
+  accent: string;
+  createdBy?: string;
+}>();
+
+const origin = useOrigin();
+const identity = useDemoInstance(props.direction === "east" ? "East" : "North");
+const goBack = (context: OriginContext) => {
+  if (!context.canGoBack) return null;
+  return back(props.direction === "north" ? fall : slideRight);
+};
+
+const returnGesture =
+  props.direction === "east"
+    ? gesture.from
+        .left("clamp(24px, 8%, 64px)")
+        .to.right()
+        .navigate((context) => (context.canGoBack ? back() : null))
+        .animate(slideRight)
+    : gesture.to
+        .down()
+        .navigate((context) => (context.canGoBack ? back() : null))
+        .animate(fall);
+
+function backWithButton() {
+  const action = goBack(origin.context.value);
+  if (action) void origin.perform(action);
+}
+</script>
+
+<template>
+  <OriginGesture
+    class="lab-page direction-result"
+    :class="`direction-result--${direction}`"
+    :style="{ '--result-accent': accent }"
+    :gesture="returnGesture"
+  >
+    <div class="result-orbit" />
+    <div class="eyebrow">Resolved from {{ direction }}</div>
+    <h1>{{ heading }}</h1>
+    <p>
+      This component was created by <strong>{{ createdBy }}</strong
+      >. Its own setup has now produced <strong>{{ identity.instance }}</strong
+      >.
+    </p>
+    <InstanceCard
+      label="Result instance"
+      :instance="identity.instance"
+      :status="identity.status.value"
+    />
+    <button
+      class="primary-action"
+      type="button"
+      data-origin-gesture="ignore"
+      @click="backWithButton"
+    >
+      Return to the retained direction instance
+    </button>
+    <div
+      class="gesture-hint"
+      :class="{ 'gesture-hint--back': direction === 'east' }"
+    >
+      <template v-if="direction === 'north'"
+        >Swipe down to return <span>↓</span></template
+      >
+      <template v-else><span>←</span> Swipe from the left edge</template>
+    </div>
+    <div v-if="direction === 'east'" class="edge-marker edge-marker--left">
+      back edge
+    </div>
+  </OriginGesture>
+</template>
@@ -0,0 +1,116 @@
+<script setup lang="ts">
+import { ref } from "vue";
+import {
+  OriginGesture,
+  back,
+  gesture,
+  useOrigin,
+  type OriginContext,
+} from "@native-vue-router/core-v2";
+import InstanceCard from "../components/InstanceCard.vue";
+import { useDemoInstance } from "../lab-state";
+import { liftEdgeDialog } from "../motions";
+
+defineProps<{
+  openedBy?: string;
+  predicate?: string;
+}>();
+
+const origin = useOrigin();
+const identity = useDemoInstance("Dialog");
+const selected = ref("Motion");
+
+const dismiss = (context: OriginContext) =>
+  context.canGoBack ? back(liftEdgeDialog) : null;
+
+const dismissGesture = gesture.to
+  .up()
+  .navigate((context) => (context.canGoBack ? back() : null))
+  .animate(liftEdgeDialog);
+
+function close() {
+  const action = dismiss(origin.context.value);
+  if (action) void origin.perform(action);
+}
+</script>
+
+<template>
+  <OriginGesture class="edge-dialog-overlay" :gesture="dismissGesture">
+    <button
+      class="edge-dialog-backdrop"
+      type="button"
+      data-origin-gesture="ignore"
+      aria-label="Close edge dialog"
+      @click="close"
+    />
+
+    <section
+      class="edge-dialog"
+      role="dialog"
+      aria-modal="true"
+      aria-labelledby="edge-dialog-title"
+    >
+      <header>
+        <div>
+          <div class="eyebrow">Custom-origin dialog</div>
+          <h1 id="edge-dialog-title">Dropped from the top.</h1>
+        </div>
+        <button
+          type="button"
+          data-origin-gesture="ignore"
+          aria-label="Close dialog"
+          @click="close"
+        >
+          ×
+        </button>
+      </header>
+
+      <p>
+        The target is a normal scene component. Its content is anchored left,
+        while the operation moves the target frame from top to bottom.
+      </p>
+
+      <dl class="dialog-facts">
+        <div>
+          <dt>Admitted by</dt>
+          <dd>{{ predicate }}</dd>
+        </div>
+        <div>
+          <dt>Origin instance</dt>
+          <dd>{{ openedBy }}</dd>
+        </div>
+        <div>
+          <dt>Placement</dt>
+          <dd>above</dd>
+        </div>
+      </dl>
+
+      <fieldset>
+        <legend>Dialog-local state</legend>
+        <button
+          v-for="option in ['Motion', 'Gesture', 'Scene']"
+          :key="option"
+          type="button"
+          data-origin-gesture="ignore"
+          :class="{ selected: selected === option }"
+          @click="selected = option"
+        >
+          {{ option }}
+        </button>
+      </fieldset>
+
+      <InstanceCard
+        label="Dialog instance"
+        :instance="identity.instance"
+        :status="identity.status.value"
+      />
+
+      <footer>
+        <strong>Swipe up anywhere on the panel to dismiss.</strong>
+        <small
+          >The reverse operation reveals the retained origin instance.</small
+        >
+      </footer>
+    </section>
+  </OriginGesture>
+</template>
@@ -0,0 +1,125 @@
+<script setup lang="ts">
+import {
+  above,
+  back,
+  gesture,
+  OriginGestureSurface,
+  originView,
+  useOrigin,
+  type OriginContext,
+} from "@native-vue-router/core-v2";
+import InstanceCard from "../components/InstanceCard.vue";
+import { useDemoInstance } from "../lab-state";
+import { dropEdgeDialog, unfocusPortal } from "../motions";
+import EdgeDialogView from "./EdgeDialogView.vue";
+
+const origin = useOrigin();
+const identity = useDemoInstance("Predicate");
+
+/*
+ * This is deliberately not the built-in `edge` option. A down gesture's
+ * built-in edge would be the top edge, while this lab wants down movement to
+ * begin at the left edge. The predicate can describe that cross-axis rule—or
+ * any safe area, shape, percentage, or exclusion zone the application needs.
+ */
+function dialogEdgeWidth(host: HTMLElement) {
+  return Math.min(72, Math.max(36, host.clientWidth * 0.08));
+}
+
+const dialogView = () =>
+  originView(
+    EdgeDialogView,
+    {
+      openedBy: identity.instance,
+      predicate: "x ≤ clamp(36px, 8%, 72px)",
+    },
+    { key: "edge-dialog", name: "Edge Dialog" },
+  );
+
+const openDialog = () => above(dialogView(), dropEdgeDialog);
+
+const goBack = (context: OriginContext) =>
+  context.canGoBack ? back(unfocusPortal) : null;
+
+const dialogGesture = gesture.from
+  .when(({ point, host }) => point.localX <= dialogEdgeWidth(host))
+  .to.down()
+  .navigate(() => above(dialogView()))
+  .animate(dropEdgeDialog);
+
+/*
+ * The same physical left edge also supports a conventional rightward back
+ * gesture. Both recognizers see pointer-down; their axis checks decide which
+ * one captures once movement becomes unambiguous.
+ */
+const backGesture = gesture.from
+  .left("clamp(36px, 8%, 72px)")
+  .to.right()
+  .navigate((context) => (context.canGoBack ? back() : null))
+  .animate(unfocusPortal);
+
+const gestures = [dialogGesture, backGesture] as const;
+
+function backWithButton() {
+  const action = goBack(origin.context.value);
+  if (action) void origin.perform(action);
+}
+</script>
+
+<template>
+  <OriginGestureSurface
+    as="main"
+    class="lab-page predicate-view"
+    :gestures="gestures"
+  >
+    <button
+      class="view-back"
+      type="button"
+      data-origin-gesture="ignore"
+      @click="backWithButton"
+    >
+      ← Labs
+    </button>
+
+    <div class="predicate-copy">
+      <div class="eyebrow">Lab 06 · Predicate edge</div>
+      <h1>Direction and starting edge are independent.</h1>
+      <p>
+        Begin inside the illuminated left rail and drag <strong>down</strong>. A
+        custom predicate admits the pointer; the normal direction recognizer
+        still handles axis capture, progress, velocity, and release.
+      </p>
+
+      <div class="predicate-code">
+        <span>start predicate</span>
+        <code>x ≤ clamp(36px, 8%, 72px)</code>
+        <small>movement: down · built-in edge: intentionally omitted</small>
+      </div>
+
+      <InstanceCard
+        label="Predicate origin"
+        :instance="identity.instance"
+        :status="identity.status.value"
+      />
+
+      <button
+        class="primary-action"
+        type="button"
+        data-origin-gesture="ignore"
+        @click="origin.perform(openDialog())"
+      >
+        Open accessibly without dragging
+      </button>
+    </div>
+
+    <div class="predicate-edge" aria-hidden="true">
+      <span>custom left-edge predicate</span>
+      <div class="predicate-arrow">↓</div>
+      <small>start here · pull down</small>
+    </div>
+
+    <div class="predicate-axis-note">
+      A rightward drag on this same rail still performs edge-back.
+    </div>
+  </OriginGestureSurface>
+</template>
@@ -0,0 +1,87 @@
+<script setup lang="ts">
+import {
+  above,
+  back,
+  gesture,
+  OriginGestureSurface,
+  originView,
+  slideLeft,
+  slideRight,
+  useOrigin,
+  type OriginContext,
+} from "@native-vue-router/core-v2";
+import InstanceCard from "../components/InstanceCard.vue";
+import { useDemoInstance } from "../lab-state";
+import SecondView from "./SecondView.vue";
+
+const origin = useOrigin();
+const identity = useDemoInstance("X");
+
+const secondView = () =>
+  originView(
+    SecondView,
+    {
+      openedAt: new Date().toLocaleTimeString(),
+      createdBy: identity.instance,
+    },
+    { key: "second", name: "Second" },
+  );
+const createSecond = () => above(secondView(), slideLeft);
+
+const goBack = (context: OriginContext) =>
+  context.canGoBack ? back(slideRight) : null;
+
+const forwardGesture = gesture
+  .to.left()
+  .navigate(() => above(secondView()))
+  .animate(slideLeft);
+const backGesture = gesture
+  .to.right()
+  .navigate((context) => (context.canGoBack ? back() : null))
+  .animate(slideRight);
+const gestures = [forwardGesture, backGesture] as const;
+
+function backWithButton() {
+  const action = goBack(origin.context.value);
+  if (action) void origin.perform(action);
+}
+</script>
+
+<template>
+  <OriginGestureSurface
+    as="main"
+    class="lab-page chain-view view-one"
+    :gestures="gestures"
+  >
+    <button
+      class="view-back"
+      type="button"
+      data-origin-gesture="ignore"
+      @click="backWithButton"
+    >
+      ← Labs
+    </button>
+    <div class="eyebrow">Chain stress test · Origin X</div>
+    <h1>Every component starts its own movement.</h1>
+    <p>
+      Drag this screen left. Release it, then immediately drag the blue screen
+      while this spring is still settling. Keep going to build a four-node
+      scene.
+    </p>
+    <InstanceCard
+      label="X Vue instance"
+      :instance="identity.instance"
+      :status="identity.status.value"
+    />
+    <button
+      class="primary-action"
+      data-origin-gesture="ignore"
+      type="button"
+      @click="origin.perform(createSecond())"
+    >
+      Open Y without a gesture
+    </button>
+    <div class="gesture-hint">Swipe left <span>→</span></div>
+    <div class="edge-marker edge-marker--left">back edge</div>
+  </OriginGestureSurface>
+</template>
@@ -0,0 +1,63 @@
+<script setup lang="ts">
+import {
+  OriginGesture,
+  back,
+  gesture,
+  slideRight,
+  useOrigin,
+  type OriginContext,
+} from "@native-vue-router/core-v2";
+import InstanceCard from "../components/InstanceCard.vue";
+import { useDemoInstance } from "../lab-state";
+
+defineProps<{ chain?: string }>();
+
+const origin = useOrigin();
+const identity = useDemoInstance("Omega");
+const goBack = (context: OriginContext) =>
+  context.canGoBack ? back(slideRight) : null;
+
+const backGesture = gesture
+  // .from.left("clamp(24px, 8%, 64px)")
+  // .from.left("20%")
+  .to.right()
+  .navigate((context) => (context.canGoBack ? back() : null))
+  .animate(slideRight);
+
+function backWithButton() {
+  const action = goBack(origin.context.value);
+  if (action) void origin.perform(action);
+}
+</script>
+
+<template>
+  <OriginGesture class="lab-page chain-view view-four" :gesture="backGesture">
+    <div class="eyebrow">Chain stress test · Origin Ω</div>
+    <h1>Four independently mounted components. Three live edges.</h1>
+    <p>
+      If you moved quickly enough, the inspector showed X, Y, Z, and Ω at once.
+      Each component stayed a flat sibling while inherited transforms composed
+      mathematically.
+    </p>
+    <div class="proof">
+      Reported ancestry <strong>{{ chain }}</strong>
+    </div>
+    <InstanceCard
+      label="Ω Vue instance"
+      :instance="identity.instance"
+      :status="identity.status.value"
+    />
+    <button
+      class="primary-action"
+      type="button"
+      data-origin-gesture="ignore"
+      @click="backWithButton"
+    >
+      Return to the retained Z instance
+    </button>
+    <div class="gesture-hint gesture-hint--back">
+      <span>←</span> Or swipe from the left edge
+    </div>
+    <div class="edge-marker edge-marker--left">back edge</div>
+  </OriginGesture>
+</template>
@@ -0,0 +1,88 @@
+<script setup lang="ts">
+import {
+  OriginGesture,
+  above,
+  back,
+  gesture,
+  originView,
+  useOrigin,
+  type OriginContext,
+} from "@native-vue-router/core-v2";
+import InstanceCard from "../components/InstanceCard.vue";
+import { demoPhotos, type DemoPhoto } from "../gallery-data";
+import { useDemoInstance } from "../lab-state";
+import { focusPortal, unfocusPortal } from "../motions";
+import PhotoDetailView from "./PhotoDetailView.vue";
+
+const origin = useOrigin();
+const identity = useDemoInstance("Gallery");
+
+const photoAction = (photo: DemoPhoto, index: number) =>
+  above(
+    originView(
+      PhotoDetailView,
+      { photo, index },
+      { key: `photo-${photo.id}`, name: photo.title },
+    ),
+    focusPortal,
+  );
+
+const goBack = (context: OriginContext) =>
+  context.canGoBack ? back(unfocusPortal) : null;
+
+const backGesture = gesture.from
+  .left("clamp(24px, 8%, 64px)")
+  .to.right()
+  .navigate((context) => (context.canGoBack ? back() : null))
+  .animate(unfocusPortal);
+
+function backWithButton() {
+  const action = goBack(origin.context.value);
+  if (action) void origin.perform(action);
+}
+</script>
+
+<template>
+  <OriginGesture class="lab-page gallery-view" :gesture="backGesture">
+    <header class="section-header">
+      <div>
+        <button
+          class="view-back"
+          type="button"
+          data-origin-gesture="ignore"
+          @click="backWithButton"
+        >
+          ← Labs
+        </button>
+        <div class="eyebrow">Lab 03 · Focus gallery</div>
+        <h1>Events can originate motion without being gestures.</h1>
+        <p>
+          Select a card to run the same scene primitive programmatically. Once
+          inside, the destination declares its own traversal gestures.
+        </p>
+      </div>
+      <InstanceCard
+        label="Gallery instance"
+        :instance="identity.instance"
+        :status="identity.status.value"
+      />
+    </header>
+
+    <div class="photo-grid">
+      <button
+        v-for="(photo, index) in demoPhotos"
+        :key="photo.id"
+        type="button"
+        data-origin-gesture="ignore"
+        class="photo-card"
+        :style="{ background: photo.gradient }"
+        @click="origin.perform(photoAction(photo, index))"
+      >
+        <span>{{ String(index + 1).padStart(2, "0") }}</span>
+        <strong>{{ photo.title }}</strong>
+        <small>{{ photo.location }}</small>
+      </button>
+    </div>
+    <div class="edge-marker edge-marker--left">back edge</div>
+  </OriginGesture>
+</template>
@@ -0,0 +1,201 @@
+<script setup lang="ts">
+import {
+  OriginGesture,
+  above,
+  gesture,
+  originView,
+  slideLeft,
+  useOrigin,
+  type OriginChoreography,
+} from "@native-vue-router/core-v2";
+import InstanceCard from "../components/InstanceCard.vue";
+import { useDemoInstance } from "../lab-state";
+import { coverUp, focusPortal } from "../motions";
+import ChatView from "./ChatView.vue";
+import DirectionLabView from "./DirectionLabView.vue";
+import EdgePredicateView from "./EdgePredicateView.vue";
+import FirstView from "./FirstView.vue";
+import GalleryView from "./GalleryView.vue";
+import NestedScenesView from "./NestedScenesView.vue";
+import PaymentDetailsView from "./PaymentDetailsView.vue";
+import PartialDrawerPageView from "./PartialDrawerPageView.vue";
+import PlayerView from "./PlayerView.vue";
+
+const origin = useOrigin();
+const identity = useDemoInstance("Hub");
+
+function viewFor(component: Parameters<typeof originView>[0], name: string) {
+  return originView(component, undefined, {
+    key: name.toLowerCase().replaceAll(" ", "-"),
+    name,
+  });
+}
+
+function actionFor(
+  component: Parameters<typeof originView>[0],
+  name: string,
+  choreography: OriginChoreography,
+) {
+  return above(viewFor(component, name), choreography);
+}
+
+/*
+ * No `.from` is declared: every eligible pointer-down on the Hub can become
+ * this leftward gesture once movement passes the direction lock.
+ */
+const enterChainGesture = gesture.to
+  .left()
+  // .complete(
+  //   ({ progress, velocity }) =>
+  //     progress >= 0.3 || (progress >= 0.05 && velocity >= 0.8),
+  // )
+  .navigate(() => above(viewFor(FirstView, "Chain X")))
+  .animate(slideLeft);
+
+const openChain = () => actionFor(FirstView, "Chain X", slideLeft);
+const openDirections = () =>
+  actionFor(DirectionLabView, "Direction Lab", focusPortal);
+const openGallery = () => actionFor(GalleryView, "Gallery", focusPortal);
+const openPlayer = () => actionFor(PlayerView, "Player", coverUp);
+const openChat = () => actionFor(ChatView, "Locked Chat", slideLeft);
+const openPredicate = () =>
+  actionFor(EdgePredicateView, "Predicate Edge", focusPortal);
+const openNestedScenes = () =>
+  actionFor(NestedScenesView, "Nested Scenes", focusPortal);
+const openCheckout = () =>
+  actionFor(PaymentDetailsView, "Payment Details", slideLeft);
+const openPartialDrawer = () =>
+  actionFor(PartialDrawerPageView, "Partial Drawer", focusPortal);
+
+const labs = [
+  {
+    number: "01",
+    title: "Concurrent chain",
+    description: "Swipe through X→Y→Z→Ω before the preceding springs settle.",
+    tags: ["4 live nodes", "frame composition"],
+    action: openChain,
+    accent: "violet",
+  },
+  {
+    number: "02",
+    title: "Direction matrix",
+    description:
+      "One component declares horizontal, vertical, and edge-only behavior.",
+    tags: ["multi-axis", "custom flip"],
+    action: openDirections,
+    accent: "cyan",
+  },
+  {
+    number: "03",
+    title: "Focus gallery",
+    description:
+      "Programmatic card selection and gesture-driven photo traversal.",
+    tags: ["portal", "local state"],
+    action: openGallery,
+    accent: "amber",
+  },
+  {
+    number: "04",
+    title: "Native player",
+    description:
+      "A vertical cover with media state and intentionally no back edge.",
+    tags: ["vertical dismiss", "gesture policy"],
+    action: openPlayer,
+    accent: "green",
+  },
+  {
+    number: "05",
+    title: "Locked chat",
+    description:
+      "A Snapchat-style page that exposes only an explicit back button.",
+    tags: ["blocked edge", "form state"],
+    action: openChat,
+    accent: "rose",
+  },
+  {
+    number: "06",
+    title: "Predicate edge",
+    description: "Swipe down from a dynamic left-edge region to drop a dialog.",
+    tags: ["custom hit test", "axis arbitration"],
+    action: openPredicate,
+    accent: "lime",
+  },
+  {
+    number: "07",
+    title: "Nested scenes",
+    description:
+      "Carousels and decks with local history—including deliberate gesture conflicts.",
+    tags: ["carousel", "nested ownership"],
+    action: openNestedScenes,
+    accent: "blue",
+  },
+  {
+    number: "08",
+    title: "Replace checkout",
+    description:
+      "Confirm a mock payment, replace its mounted entry, then test where back returns.",
+    tags: ["atomic replace", "history rewrite"],
+    action: openCheckout,
+    accent: "teal",
+  },
+  {
+    number: "09",
+    title: "Partial drawer",
+    description:
+      "Push a connected drawer two-thirds across while the live source occupies the final third.",
+    tags: ["persistent effects", "partial view"],
+    action: openPartialDrawer,
+    accent: "orange",
+  },
+] as const;
+</script>
+
+<template>
+  <OriginGesture class="lab-page hub-view" :gesture="enterChainGesture">
+    <keep-alive>
+      <header class="hub-header">
+        <div>
+          <div class="eyebrow">Routeless origins · interactive field guide</div>
+          <h1>A navigation engine made of component-owned movement.</h1>
+          <p>
+            No route table decides what this screen can do. Every lab below
+            creates its target, chooses its choreography, and declares its own
+            gesture policy.
+          </p>
+        </div>
+        <InstanceCard
+          label="Hub instance"
+          :instance="identity.instance"
+          :status="identity.status.value"
+        />
+      </header>
+
+      <main class="lab-grid">
+        <button
+          v-for="lab in labs"
+          :key="lab.number"
+          type="button"
+          data-origin-gesture="ignore"
+          class="lab-card"
+          :class="`lab-card--${lab.accent}`"
+          @click="origin.perform(lab.action())"
+        >
+          <span class="lab-number">{{ lab.number }}</span>
+          <span class="lab-copy">
+            <strong>{{ lab.title }}</strong>
+            <small>{{ lab.description }}</small>
+          </span>
+          <span class="tag-row">
+            <em v-for="tag in lab.tags" :key="tag">{{ tag }}</em>
+          </span>
+          <span class="lab-arrow">↗</span>
+        </button>
+      </main>
+
+      <footer class="hub-footer">
+        <span>Tip: swipe anywhere left to enter the chain stress test.</span>
+        <span>The inspector in the corner exposes live nodes and edges.</span>
+      </footer>
+    </keep-alive>
+  </OriginGesture>
+</template>
@@ -0,0 +1,166 @@
+<script setup lang="ts">
+import { ref } from "vue";
+import {
+  back,
+  forward,
+  gesture,
+  OriginGestureSurface,
+  useOrigin,
+  type OriginChoreography,
+  type OriginGestureDirectedBuilder,
+  type OriginView,
+} from "@native-vue-router/core-v2";
+import InstanceCard from "../components/InstanceCard.vue";
+import { useDemoInstance } from "../lab-state";
+import {
+  nestedCarouselBack,
+  nestedCarouselForward,
+  nestedCubeBack,
+  nestedCubeForward,
+  nestedDeckBack,
+  nestedDeckForward,
+} from "../motions";
+
+type NestedSceneKind = "cooperative" | "vertical" | "conflict";
+
+const props = defineProps<{
+  kind: NestedSceneKind;
+  index: number;
+  total: number;
+  eyebrow: string;
+  title: string;
+  description: string;
+  accent: string;
+  next?: () => OriginView;
+}>();
+
+const origin = useOrigin();
+const identity = useDemoInstance(`Nested ${props.kind} ${props.index + 1}`);
+const localLikes = ref(0);
+
+const vertical = props.kind === "vertical";
+const forwardMotion: OriginChoreography = vertical
+  ? nestedDeckForward
+  : props.kind === "conflict"
+    ? nestedCubeForward
+    : nestedCarouselForward;
+const backMotion: OriginChoreography = vertical
+  ? nestedDeckBack
+  : props.kind === "conflict"
+    ? nestedCubeBack
+    : nestedCarouselBack;
+
+/*
+ * Cooperative cases deliberately leave the outer page's first 44 pixels
+ * untouched. The conflict case starts anywhere, so its pointer-down handler
+ * stops propagation before it knows whether `back()` is available.
+ */
+function movementBuilder(
+  direction: "forward" | "back",
+): OriginGestureDirectedBuilder {
+  const to = vertical
+    ? direction === "forward"
+      ? "up"
+      : "down"
+    : direction === "forward"
+      ? "left"
+      : "right";
+  const start =
+    props.kind === "conflict"
+      ? gesture.to
+      : gesture.from.when(({ point, bounds }) => {
+          const parentRail = Math.min(52, Math.max(22, bounds.width * 0.12));
+          return point.localX > parentRail;
+        }).to;
+  return start[to]();
+}
+
+const forwardGesture = movementBuilder("forward")
+  .navigate(() => {
+    const target = props.next?.();
+    return target ? forward(target) : null;
+  })
+  .animate(forwardMotion);
+
+const backGesture = movementBuilder("back")
+  .navigate((context) => (context.canGoBack ? back() : null))
+  .animate(backMotion);
+
+const gestures = [forwardGesture, backGesture] as const;
+
+function nextWithButton() {
+  const target = props.next?.();
+  if (target) void origin.perform(forward(target, forwardMotion));
+}
+
+function backWithButton() {
+  if (origin.context.value.canGoBack) void origin.perform(back(backMotion));
+}
+</script>
+
+<template>
+  <OriginGestureSurface
+    as="article"
+    class="nested-slide"
+    :class="`nested-slide--${kind}`"
+    :data-nested-kind="kind"
+    :data-nested-index="index"
+    :style="{ '--nested-accent': accent }"
+    :gestures="gestures"
+  >
+    <div class="nested-slide__orb" aria-hidden="true" />
+
+    <header>
+      <span>{{ eyebrow }}</span>
+      <strong>{{ index + 1 }} / {{ total }}</strong>
+    </header>
+
+    <div class="nested-slide__copy">
+      <h3>{{ title }}</h3>
+      <p>{{ description }}</p>
+    </div>
+
+    <div class="nested-slide__state">
+      <InstanceCard
+        label="Nested instance"
+        :instance="identity.instance"
+        :status="identity.status.value"
+      />
+      <button
+        type="button"
+        data-origin-gesture="ignore"
+        @click="localLikes += 1"
+      >
+        Local state · {{ localLikes }}
+      </button>
+    </div>
+
+    <footer>
+      <button
+        type="button"
+        data-origin-gesture="ignore"
+        :disabled="!origin.canGoBack.value"
+        @click="backWithButton"
+      >
+        {{ vertical ? "↓ Previous" : "← Previous" }}
+      </button>
+
+      <div class="nested-slide__dots" aria-label="Slide position">
+        <span
+          v-for="dot in total"
+          :key="dot"
+          :class="{ active: dot === index + 1 }"
+        />
+      </div>
+
+      <button
+        type="button"
+        data-origin-gesture="ignore"
+        :disabled="!next"
+        @click="nextWithButton"
+      >
+        {{ vertical ? "Next ↑" : "Next →" }}
+      </button>
+    </footer>
+  </OriginGestureSurface>
+</template>
@@ -0,0 +1,276 @@
+<script setup lang="ts">
+import {
+  OriginGesture,
+  OriginScene,
+  back,
+  createOriginScene,
+  gesture,
+  originView,
+  useOrigin,
+  type OriginView,
+} from "@native-vue-router/core-v2";
+import { useDemoInstance } from "../lab-state";
+import { unfocusPortal } from "../motions";
+import NestedSceneSlide from "./NestedSceneSlide.vue";
+
+type NestedSceneKind = "cooperative" | "vertical" | "conflict";
+
+interface SlideCopy {
+  eyebrow: string;
+  title: string;
+  description: string;
+  accent: string;
+}
+
+const slideSets: Record<NestedSceneKind, readonly SlideCopy[]> = {
+  cooperative: [
+    {
+      eyebrow: "Cooperative carousel",
+      title: "A scene inside a page",
+      description:
+        "Swipe left away from the glowing pass-through rail. The target mounts only inside this clipped carousel.",
+      accent: "#76dcff",
+    },
+    {
+      eyebrow: "Retained nested history",
+      title: "Slide one is still mounted",
+      description:
+        "Increment local state, move again, then return. The same nested Vue instances are revealed.",
+      accent: "#a78bfa",
+    },
+    {
+      eyebrow: "Independent operation graph",
+      title: "Three carousel instances",
+      description:
+        "This history belongs to the carousel scene. The outer page remains one mounted application entry.",
+      accent: "#65f2b1",
+    },
+  ],
+  vertical: [
+    {
+      eyebrow: "Vertical nested deck",
+      title: "Pull upward inside this card",
+      description:
+        "The deck uses vertical progress, rotation, and a shared sideways frame arc.",
+      accent: "#ffbd70",
+    },
+    {
+      eyebrow: "Orthogonal choreography",
+      title: "The page still owns its left rail",
+      description:
+        "Pull down to reveal the retained card, or begin on its pass-through rail and swipe right to leave the lab.",
+      accent: "#ff7f9f",
+    },
+    {
+      eyebrow: "Nested composition",
+      title: "Frames remain local",
+      description:
+        "Transforms compose exactly like the full-screen scene, but measurements come from this smaller viewport.",
+      accent: "#ffe079",
+    },
+  ],
+  conflict: [
+    {
+      eyebrow: "Intentional conflict",
+      title: "This child claims every pointer-down",
+      description:
+        "Try the page's rightward back gesture over this card. The child sees it first, even though nested back is unavailable.",
+      accent: "#ff5f78",
+    },
+    {
+      eyebrow: "Child-owned back",
+      title: "Now rightward swipe works here",
+      description:
+        "After moving forward, the exact same gesture can resolve nested back, producing the cube reversal.",
+      accent: "#ff8d4d",
+    },
+  ],
+};
+
+function nestedView(kind: NestedSceneKind, index: number): OriginView {
+  const slides = slideSets[kind];
+  const copy = slides[index]!;
+  return originView(
+    NestedSceneSlide,
+    {
+      kind,
+      index,
+      total: slides.length,
+      ...copy,
+      next:
+        index + 1 < slides.length
+          ? (): OriginView => nestedView(kind, index + 1)
+          : undefined,
+    },
+    {
+      key: `${kind}-slide-${index + 1}`,
+      name: `${kind} slide ${index + 1}`,
+    },
+  );
+}
+
+function nestedScene(kind: NestedSceneKind) {
+  return createOriginScene({ initial: nestedView(kind, 0) });
+}
+
+interface NestedCase {
+  kind: NestedSceneKind;
+  status: "supported" | "supported-with-policy" | "known-conflict";
+  title: string;
+  summary: string;
+  expected: string;
+  issue: string;
+  scene: ReturnType<typeof createOriginScene>;
+}
+
+const cases: readonly NestedCase[] = [
+  {
+    kind: "cooperative",
+    status: "supported-with-policy",
+    title: "Reserved-edge carousel",
+    summary:
+      "Horizontal nested history with a start predicate that leaves a clamp(22px, 12%, 52px) rail for its parent.",
+    expected:
+      "Swipe left or right beyond the rail; swipe right from the card's rail to trigger parent back.",
+    issue:
+      "The parent/child agreement is spatial policy written by the developer, not automatic arbitration.",
+    scene: nestedScene("cooperative"),
+  },
+  {
+    kind: "vertical",
+    status: "supported",
+    title: "Vertical component deck",
+    summary:
+      "A second nested scene uses upward/downward gestures and an entirely different frame animation.",
+    expected:
+      "Swipe up for the next card, down for retained back, and swipe right from its rail for parent back.",
+    issue:
+      "Its touch-action prevents page scrolling while a touch begins over the deck, which is appropriate here but must be intentional.",
+    scene: nestedScene("vertical"),
+  },
+  {
+    kind: "conflict",
+    status: "known-conflict",
+    title: "Greedy child recognizer",
+    summary:
+      "The cube carousel deliberately uses `.to.left()` and `.to.right()` without a `.from` constraint.",
+    expected: "Nested forward/back works and remains clipped to the card.",
+    issue:
+      "On slide one, parent back fails everywhere over this card: the child stops pointer-down propagation before `.navigate()` returns null.",
+    scene: nestedScene("conflict"),
+  },
+];
+
+const origin = useOrigin();
+const identity = useDemoInstance("Nested scenes");
+
+const pageBackGesture = gesture.to
+  .right()
+  .complete(
+    ({ distance, bounds, progress, velocity }) =>
+      distance >= bounds.width * 0.08 || progress >= 0.22 || velocity >= 0.65,
+  )
+  .navigate((context) => (context.canGoBack ? back() : null))
+  .animate(unfocusPortal);
+
+function backWithButton() {
+  if (origin.context.value.canGoBack) void origin.perform(back(unfocusPortal));
+}
+</script>
+
+<template>
+  <OriginGesture class="lab-page nested-scenes-view" :gesture="pageBackGesture">
+    <button
+      class="view-back"
+      type="button"
+      data-origin-gesture="ignore"
+      @click="backWithButton"
+    >
+      ← Labs
+    </button>
+
+    <header class="nested-scenes-header">
+      <div>
+        <div class="eyebrow">Lab 07 · Nested origin scenes</div>
+        <h1>Components can own smaller worlds.</h1>
+        <p>
+          Each card below contains a completely independent
+          <code>OriginScene</code>. Its views, history, gestures, measurements,
+          and animations stay inside that card while this page remains the outer
+          origin.
+        </p>
+      </div>
+      <div class="nested-page-instance">
+        <span>Outer page instance</span>
+        <strong>{{ identity.instance }}</strong>
+        <small>rightward 8% → page back</small>
+      </div>
+    </header>
+
+    <main class="nested-case-grid">
+      <section
+        v-for="item in cases"
+        :key="item.kind"
+        class="nested-case"
+        :class="`nested-case--${item.kind}`"
+      >
+        <header>
+          <span class="nested-case__status" :class="item.status">
+            {{ item.status.replaceAll("-", " ") }}
+          </span>
+          <h2>{{ item.title }}</h2>
+          <p>{{ item.summary }}</p>
+        </header>
+
+        <div class="nested-stage-shell">
+          <OriginScene class="nested-stage" :scene="item.scene" />
+          <div class="nested-stage-edge" aria-hidden="true">
+            {{
+              item.kind === "conflict"
+                ? "parent blocked"
+                : "parent pass-through"
+            }}
+          </div>
+        </div>
+
+        <div class="nested-case__diagnostics">
+          <span>
+            {{ item.scene.nodes.value.length }} nested node{{
+              item.scene.nodes.value.length === 1 ? "" : "s"
+            }}
+          </span>
+          <span>
+            {{ item.scene.operations.value.length }} live edge{{
+              item.scene.operations.value.length === 1 ? "" : "s"
+            }}
+          </span>
+        </div>
+
+        <dl>
+          <div>
+            <dt>Expected</dt>
+            <dd>{{ item.expected }}</dd>
+          </div>
+          <div>
+            <dt>
+              {{ item.kind === "conflict" ? "Predicted failure" : "Caveat" }}
+            </dt>
+            <dd>{{ item.issue }}</dd>
+          </div>
+        </dl>
+      </section>
+    </main>
+
+    <footer class="nested-scenes-footer">
+      <strong>Ownership today is decided at pointer-down.</strong>
+      <span>
+        A future gesture arena could delay that decision and let a parent claim
+        the sequence when a child declines navigation.
+      </span>
+    </footer>
+
+    <div class="nested-page-gesture">
+      Parent gesture: swipe right outside a child, or from a cooperative rail
+    </div>
+  </OriginGesture>
+</template>
@@ -0,0 +1,74 @@
+<script setup lang="ts">
+import {
+  OriginGesture,
+  back,
+  gesture,
+  slideRight,
+  useOrigin,
+} from "@native-vue-router/core-v2";
+import InstanceCard from "../components/InstanceCard.vue";
+import { useDemoInstance } from "../lab-state";
+
+defineProps<{
+  orderReference: string;
+  replacedInstance: string;
+}>();
+
+const origin = useOrigin();
+const identity = useDemoInstance("Confirmation");
+
+const returnGesture = gesture.from
+  .left("clamp(24px, 8%, 64px)")
+  .to.right()
+  .navigate((context) => (context.canGoBack ? back() : null))
+  .animate(slideRight);
+
+function returnToLabs() {
+  if (origin.context.value.canGoBack) void origin.perform(back(slideRight));
+}
+</script>
+
+<template>
+  <OriginGesture
+    class="checkout-view confirmation-view"
+    :gesture="returnGesture"
+  >
+    <section class="confirmation-card">
+      <div class="confirmation-mark" aria-hidden="true">✓</div>
+      <div class="eyebrow">Payment complete</div>
+      <h1>Order confirmed.</h1>
+      <p>
+        The Payment Details node <code>{{ replacedInstance }}</code> has been
+        removed. Back now resolves the retained Hub instance directly.
+      </p>
+      <dl>
+        <div>
+          <dt>Order</dt>
+          <dd>{{ orderReference }}</dd>
+        </div>
+        <div>
+          <dt>History depth</dt>
+          <dd>{{ origin.context.value.history.length }}</dd>
+        </div>
+        <div>
+          <dt>Previous view</dt>
+          <dd>{{ origin.context.value.previous?.name ?? "None" }}</dd>
+        </div>
+      </dl>
+      <InstanceCard
+        label="Confirmation instance"
+        :instance="identity.instance"
+        :status="identity.status.value"
+      />
+      <button
+        class="confirmation-action"
+        type="button"
+        data-origin-gesture="ignore"
+        @click="returnToLabs"
+      >
+        Back to labs
+      </button>
+      <small>Try the left-edge back gesture too.</small>
+    </section>
+  </OriginGesture>
+</template>
@@ -0,0 +1,99 @@
+<script setup lang="ts">
+import {
+  OriginGestureSurface,
+  back,
+  forward,
+  gesture,
+  originView,
+  slideRight,
+  useOrigin,
+} from "@native-vue-router/core-v2";
+import InstanceCard from "../components/InstanceCard.vue";
+import { useDemoInstance } from "../lab-state";
+import { partialDrawerOpen } from "../motions";
+import PartialDrawerView from "./PartialDrawerView.vue";
+
+const origin = useOrigin();
+const identity = useDemoInstance("Drawer page");
+
+const drawerView = () =>
+  originView(
+    PartialDrawerView,
+    { openedFrom: identity.instance },
+    { key: "partial-drawer", name: "Two-thirds Drawer" },
+  );
+
+const openDrawerGesture = gesture.from
+  .left("clamp(32px, 10%, 88px)")
+  .to.right()
+  .navigate(() => forward(drawerView()))
+  .animate(partialDrawerOpen);
+
+const gestures = [openDrawerGesture] as const;
+
+function openDrawer() {
+  void origin.perform(forward(drawerView(), partialDrawerOpen));
+}
+
+function returnToLabs() {
+  if (origin.context.value.canGoBack) void origin.perform(back(slideRight));
+}
+</script>
+
+<template>
+  <OriginGestureSurface
+    as="main"
+    class="partial-origin-view"
+    :gestures="gestures"
+  >
+    <!--
+      This rail is the left third of the full page. Once the whole page moves
+      right by 2/3, this exact live DOM remains visible in the final third.
+    -->
+    <aside class="partial-origin-rail">
+      <div class="partial-brand">OV</div>
+      <nav aria-label="Example navigation">
+        <button type="button" data-origin-gesture="ignore">Inbox</button>
+        <button type="button" data-origin-gesture="ignore">Projects</button>
+        <button type="button" data-origin-gesture="ignore">Archive</button>
+      </nav>
+      <InstanceCard
+        label="Page instance"
+        :instance="identity.instance"
+        :status="identity.status.value"
+      />
+    </aside>
+
+    <section class="partial-origin-content">
+      <header>
+        <button
+          type="button"
+          data-origin-gesture="ignore"
+          aria-label="Return to labs"
+          @click="returnToLabs"
+        >
+          ← Labs
+        </button>
+        <span>Connected presentation</span>
+      </header>
+
+      <div class="partial-origin-copy">
+        <div class="eyebrow">Partial route lab</div>
+        <h1>Keep one third of this page on screen.</h1>
+        <p>
+          Drag right from the left edge. The drawer becomes a real history
+          entry, while this same mounted page remains translated and visible.
+        </p>
+        <button
+          class="primary-action"
+          type="button"
+          data-origin-gesture="ignore"
+          @click="openDrawer"
+        >
+          Open two-thirds drawer
+        </button>
+        <div class="gesture-hint"><span>→</span> Pull from the left edge</div>
+      </div>
+    </section>
+  </OriginGestureSurface>
+</template>
@@ -0,0 +1,84 @@
+<script setup lang="ts">
+import {
+  OriginGesture,
+  back,
+  gesture,
+  useOrigin,
+} from "@native-vue-router/core-v2";
+import InstanceCard from "../components/InstanceCard.vue";
+import { useDemoInstance } from "../lab-state";
+import { partialDrawerClose } from "../motions";
+
+defineProps<{ openedFrom: string }>();
+
+const origin = useOrigin();
+const identity = useDemoInstance("Drawer");
+
+const closeGesture = gesture.to
+  .left()
+  .navigate((context) => (context.canGoBack ? back() : null))
+  .animate(partialDrawerClose);
+
+function closeDrawer() {
+  if (origin.context.value.canGoBack)
+    void origin.perform(back(partialDrawerClose));
+}
+</script>
+
+<template>
+  <OriginGesture class="partial-drawer-layer" :gesture="closeGesture">
+    <aside class="partial-drawer-panel">
+      <header>
+        <div>
+          <div class="eyebrow">Two-thirds destination</div>
+          <h1>Workspace</h1>
+        </div>
+        <button
+          type="button"
+          data-origin-gesture="ignore"
+          aria-label="Close drawer"
+          @click="closeDrawer"
+        >
+          ×
+        </button>
+      </header>
+
+      <p>
+        This drawer is its own Vue view and history entry. It did not copy,
+        teleport, or remount the page visible beside it.
+      </p>
+
+      <div class="partial-drawer-list">
+        <button type="button" data-origin-gesture="ignore">
+          <span>01</span>
+          Recent activity
+        </button>
+        <button type="button" data-origin-gesture="ignore">
+          <span>02</span>
+          Shared with me
+        </button>
+        <button type="button" data-origin-gesture="ignore">
+          <span>03</span>
+          Offline files
+        </button>
+      </div>
+
+      <InstanceCard
+        label="Drawer instance"
+        :instance="identity.instance"
+        :status="identity.status.value"
+      />
+      <small>
+        Opened over {{ openedFrom }} · swipe left or tap the exposed third to
+        close.
+      </small>
+    </aside>
+
+    <button
+      class="partial-drawer-backdrop"
+      type="button"
+      aria-label="Close drawer from exposed page"
+      @click="closeDrawer"
+    />
+  </OriginGesture>
+</template>
@@ -0,0 +1,156 @@
+<script setup lang="ts">
+import { ref } from "vue";
+import {
+  OriginGestureSurface,
+  back,
+  gesture,
+  originView,
+  replace,
+  slideLeft,
+  slideRight,
+  useOrigin,
+} from "@native-vue-router/core-v2";
+import InstanceCard from "../components/InstanceCard.vue";
+import { useDemoInstance } from "../lab-state";
+import OrderConfirmationView from "./OrderConfirmationView.vue";
+
+const origin = useOrigin();
+const identity = useDemoInstance("Payment");
+const cardholder = ref("Ada Lovelace");
+const lastFour = ref("4242");
+const processing = ref(false);
+
+function confirmationView() {
+  return originView(
+    OrderConfirmationView,
+    {
+      orderReference: `NVO-${Math.floor(Date.now() / 1000)
+        .toString()
+        .slice(-6)}`,
+      replacedInstance: identity.instance,
+    },
+    { key: "order-confirmation", name: "Order Confirmation" },
+  );
+}
+
+const confirmGesture = gesture.to
+  .left()
+  .navigate(() => replace(confirmationView()))
+  .animate(slideLeft);
+
+const backGesture = gesture.from
+  .left("clamp(24px, 8%, 64px)")
+  .to.right()
+  .navigate((context) => (context.canGoBack ? back() : null))
+  .animate(slideRight);
+
+const gestures = [confirmGesture, backGesture] as const;
+
+function returnToLabs() {
+  if (origin.context.value.canGoBack) void origin.perform(back(slideRight));
+}
+
+async function pay() {
+  if (processing.value) return;
+  processing.value = true;
+
+  // `replace` is one atomic scene operation. Payment Details stays mounted
+  // throughout the animation and is removed only after the commit completes.
+  await origin.perform(replace(confirmationView(), slideLeft));
+}
+</script>
+
+<template>
+  <OriginGestureSurface
+    as="main"
+    class="checkout-view payment-view"
+    :gestures="gestures"
+  >
+    <header class="checkout-toolbar">
+      <button
+        type="button"
+        data-origin-gesture="ignore"
+        aria-label="Return to labs"
+        @click="returnToLabs"
+      >
+        ←
+      </button>
+      <span>Secure checkout</span>
+      <span class="checkout-step">Step 2 of 2</span>
+    </header>
+
+    <section class="checkout-layout">
+      <div class="checkout-copy">
+        <div class="eyebrow">Replace-history lab</div>
+        <h1>Payment details</h1>
+        <p>
+          Completing this mock payment replaces this mounted entry. The
+          confirmation page will point straight back to the Hub.
+        </p>
+        <InstanceCard
+          label="Payment instance"
+          :instance="identity.instance"
+          :status="identity.status.value"
+        />
+      </div>
+
+      <form class="payment-card" @submit.prevent="pay">
+        <div class="order-line">
+          <span>Origin Pro</span>
+          <strong>$48.00</strong>
+        </div>
+
+        <label>
+          Cardholder
+          <input
+            v-model="cardholder"
+            data-origin-gesture="ignore"
+            autocomplete="cc-name"
+          />
+        </label>
+        <label>
+          Card number
+          <span class="card-number">
+            <b>•••• •••• ••••</b>
+            <input
+              v-model="lastFour"
+              data-origin-gesture="ignore"
+              inputmode="numeric"
+              maxlength="4"
+              autocomplete="cc-number"
+            />
+          </span>
+        </label>
+        <div class="payment-row">
+          <label>
+            Expiry
+            <input
+              data-origin-gesture="ignore"
+              value="08 / 29"
+              autocomplete="cc-exp"
+            />
+          </label>
+          <label>
+            CVC
+            <input
+              data-origin-gesture="ignore"
+              value="123"
+              maxlength="4"
+              autocomplete="cc-csc"
+            />
+          </label>
+        </div>
+
+        <button
+          class="pay-button"
+          type="submit"
+          data-origin-gesture="ignore"
+          :disabled="processing"
+        >
+          {{ processing ? "Confirming…" : "Pay $48.00" }}
+        </button>
+        <small>Or swipe left anywhere outside the form controls.</small>
+      </form>
+    </section>
+  </OriginGestureSurface>
+</template>
@@ -0,0 +1,114 @@
+<script setup lang="ts">
+import { computed, getCurrentInstance, ref, type Component } from "vue";
+import {
+  above,
+  back,
+  gesture,
+  OriginGestureSurface,
+  originView,
+  slideRight,
+  useOrigin,
+  type OriginContext,
+} from "@native-vue-router/core-v2";
+import InstanceCard from "../components/InstanceCard.vue";
+import { demoPhotos, type DemoPhoto } from "../gallery-data";
+import { useDemoInstance } from "../lab-state";
+import { arcSlide, coverDown } from "../motions";
+
+const props = defineProps<{ photo: DemoPhoto; index: number }>();
+
+const origin = useOrigin();
+const identity = useDemoInstance(`Photo ${props.index + 1}`);
+const liked = ref(false);
+const ownComponent = getCurrentInstance()?.type as Component;
+const nextPhoto = computed(
+  () => demoPhotos[(props.index + 1) % demoPhotos.length]!,
+);
+
+/*
+ * The target uses the same SFC definition with different props. It is still a
+ * fresh scene node and Vue instance, which makes recipe identity visible.
+ */
+const nextPhotoView = () =>
+  originView(
+    ownComponent,
+    {
+      photo: nextPhoto.value,
+      index: (props.index + 1) % demoPhotos.length,
+    },
+    { key: `photo-${nextPhoto.value.id}`, name: nextPhoto.value.title },
+  );
+const goNext = () => above(nextPhotoView(), arcSlide);
+
+const goBack = (context: OriginContext, vertical = false) =>
+  context.canGoBack ? back(vertical ? coverDown : slideRight) : null;
+
+const nextGesture = gesture.to
+  .left()
+  .navigate(() => above(nextPhotoView()))
+  .animate(arcSlide);
+const dismissGesture = gesture.to
+  .down()
+  .navigate((context) => (context.canGoBack ? back() : null))
+  .animate(coverDown);
+const edgeBackGesture = gesture.from
+  .left("clamp(24px, 8%, 64px)")
+  .to.right()
+  .navigate((context) => (context.canGoBack ? back() : null))
+  .animate(slideRight);
+const gestures = [nextGesture, dismissGesture, edgeBackGesture] as const;
+
+function close() {
+  const action = goBack(origin.context.value, true);
+  if (action) void origin.perform(action);
+}
+</script>
+
+<template>
+  <OriginGestureSurface
+    as="article"
+    class="photo-detail"
+    :style="{ background: photo.gradient }"
+    :gestures="gestures"
+  >
+    <div class="photo-vignette" />
+    <header class="photo-toolbar">
+      <button type="button" data-origin-gesture="ignore" @click="close">
+        ↓ Close
+      </button>
+      <button
+        type="button"
+        data-origin-gesture="ignore"
+        :aria-pressed="liked"
+        @click="liked = !liked"
+      >
+        {{ liked ? "♥ Liked" : "♡ Like" }}
+      </button>
+    </header>
+
+    <main class="photo-copy">
+      <div class="eyebrow">{{ photo.location }}</div>
+      <h1>{{ photo.title }}</h1>
+      <p>{{ photo.description }}</p>
+      <InstanceCard
+        label="Photo instance"
+        :instance="identity.instance"
+        :status="identity.status.value"
+      />
+      <button
+        class="primary-action"
+        type="button"
+        data-origin-gesture="ignore"
+        @click="origin.perform(goNext())"
+      >
+        Next: {{ nextPhoto.title }}
+      </button>
+      <div class="gesture-map">
+        <span>← next photo</span>
+        <span>↓ retained previous instance</span>
+        <span>left edge → retained previous instance</span>
+      </div>
+    </main>
+    <div class="edge-marker edge-marker--left">back edge</div>
+  </OriginGestureSurface>
+</template>
@@ -0,0 +1,105 @@
+<script setup lang="ts">
+import { computed, onBeforeUnmount, ref } from "vue";
+import {
+  OriginGesture,
+  back,
+  gesture,
+  useOrigin,
+  type OriginContext,
+} from "@native-vue-router/core-v2";
+import InstanceCard from "../components/InstanceCard.vue";
+import { useDemoInstance } from "../lab-state";
+import { coverDown } from "../motions";
+
+const origin = useOrigin();
+const identity = useDemoInstance("Player");
+const playing = ref(false);
+const position = ref(38);
+const elapsed = computed(() => `1:${String(position.value).padStart(2, "0")}`);
+const timer = window.setInterval(() => {
+  if (playing.value) position.value = (position.value + 1) % 60;
+}, 1000);
+onBeforeUnmount(() => window.clearInterval(timer));
+
+const dismiss = (context: OriginContext) =>
+  context.canGoBack ? back(coverDown) : null;
+
+const dismissGesture = gesture.to
+  .down()
+  .navigate((context) => (context.canGoBack ? back() : null))
+  .animate(coverDown);
+
+function close() {
+  const action = dismiss(origin.context.value);
+  if (action) void origin.perform(action);
+}
+</script>
+
+<template>
+  <OriginGesture class="player-view" :gesture="dismissGesture">
+    <header class="player-header">
+      <button type="button" data-origin-gesture="ignore" @click="close">
+        ⌄
+      </button>
+      <span>Now playing</span>
+      <button type="button" data-origin-gesture="ignore">•••</button>
+    </header>
+
+    <div class="album-art">
+      <span class="album-ring album-ring--one" />
+      <span class="album-ring album-ring--two" />
+      <span class="album-center">O</span>
+    </div>
+
+    <section class="track-copy">
+      <div>
+        <h1>Independent Frames</h1>
+        <p>The Scene Graph</p>
+      </div>
+      <button
+        type="button"
+        data-origin-gesture="ignore"
+        :aria-pressed="playing"
+        @click="playing = !playing"
+      >
+        {{ playing ? "♥" : "♡" }}
+      </button>
+    </section>
+
+    <label class="timeline">
+      <input
+        v-model="position"
+        data-origin-gesture="ignore"
+        type="range"
+        min="0"
+        max="59"
+      />
+      <span>{{ elapsed }}</span>
+      <span>3:42</span>
+    </label>
+
+    <div class="player-controls">
+      <button type="button" data-origin-gesture="ignore">↶</button>
+      <button
+        class="play-button"
+        type="button"
+        data-origin-gesture="ignore"
+        @click="playing = !playing"
+      >
+        {{ playing ? "Ⅱ" : "▶" }}
+      </button>
+      <button type="button" data-origin-gesture="ignore">↷</button>
+    </div>
+
+    <InstanceCard
+      label="Player instance"
+      :instance="identity.instance"
+      :status="identity.status.value"
+    />
+    <p class="policy-note">
+      Swipe down anywhere to dismiss. Horizontal back is intentionally absent,
+      like a native full-screen player.
+    </p>
+    <div class="drag-handle" />
+  </OriginGesture>
+</template>
@@ -0,0 +1,67 @@
+<script setup lang="ts">
+import {
+  above,
+  back,
+  gesture,
+  OriginGestureSurface,
+  originView,
+  slideLeft,
+  slideRight,
+} from "@native-vue-router/core-v2";
+import InstanceCard from "../components/InstanceCard.vue";
+import { useDemoInstance } from "../lab-state";
+import ThirdView from "./ThirdView.vue";
+
+defineProps<{ openedAt?: string; createdBy?: string }>();
+
+const identity = useDemoInstance("Y");
+const thirdView = () =>
+  originView(
+    ThirdView,
+    { createdBy: identity.instance },
+    { key: "third", name: "Third" },
+  );
+const forwardGesture = gesture.to
+  .left()
+  .navigate(() => above(thirdView()))
+  .animate(slideLeft);
+const backGesture = gesture
+  // .from.left("clamp(24px, 8%, 64px)")
+  // .from.left("20%")
+  .to.right()
+  .navigate((context) => (context.canGoBack ? back() : null))
+  .animate(slideRight);
+const gestures = [forwardGesture, backGesture] as const;
+</script>
+
+<template>
+  <OriginGestureSurface
+    as="main"
+    class="lab-page chain-view view-two"
+    :gestures="gestures"
+  >
+    <div class="eyebrow">Chain stress test · Origin Y</div>
+    <h1>Y can move while X is still moving it.</h1>
+    <p>
+      X→Y supplies Y's inherited coordinate frame. This Y→Z gesture adds a
+      second transform layer inside that frame.
+    </p>
+    <div class="metric-grid">
+      <div>
+        <span>Created by X</span>
+        <strong>{{ createdBy }}</strong>
+      </div>
+      <div>
+        <span>Created at</span>
+        <strong>{{ openedAt ?? "unknown" }}</strong>
+      </div>
+    </div>
+    <InstanceCard
+      label="Y Vue instance"
+      :instance="identity.instance"
+      :status="identity.status.value"
+    />
+    <div class="gesture-hint">Swipe left again <span>→</span></div>
+    <div class="edge-marker edge-marker--left">back edge</div>
+  </OriginGestureSurface>
+</template>
@@ -0,0 +1,60 @@
+<script setup lang="ts">
+import {
+  above,
+  back,
+  gesture,
+  OriginGestureSurface,
+  originView,
+  slideRight,
+} from "@native-vue-router/core-v2";
+import InstanceCard from "../components/InstanceCard.vue";
+import { useDemoInstance } from "../lab-state";
+import { arcSlide } from "../motions";
+import FourthView from "./FourthView.vue";
+
+defineProps<{ createdBy?: string }>();
+
+const identity = useDemoInstance("Z");
+const fourthView = () =>
+  originView(
+    FourthView,
+    { chain: `X → Y → ${identity.instance}` },
+    { key: "fourth", name: "Omega" },
+  );
+const forwardGesture = gesture.to
+  .left()
+  .navigate(() => above(fourthView()))
+  .animate(arcSlide);
+const backGesture = gesture
+  // .from.left("clamp(24px, 8%, 64px)")
+  // .from.left("20%")
+  .to.right()
+  .navigate((context) => (context.canGoBack ? back() : null))
+  .animate(slideRight);
+const gestures = [forwardGesture, backGesture] as const;
+</script>
+
+<template>
+  <OriginGestureSurface
+    as="main"
+    class="lab-page chain-view view-three"
+    :gestures="gestures"
+  >
+    <div class="eyebrow">Chain stress test · Origin Z</div>
+    <h1>Now add an arc while two frames may still be moving.</h1>
+    <p>
+      Z inherits X→Y and Y→Z motion, then originates its own frame contribution.
+      The shared frame lifts both Z and Ω through a small arc.
+    </p>
+    <div class="proof">
+      Created by Y instance <strong>{{ createdBy }}</strong>
+    </div>
+    <InstanceCard
+      label="Z Vue instance"
+      :instance="identity.instance"
+      :status="identity.status.value"
+    />
+    <div class="gesture-hint">Swipe left for Ω <span>→</span></div>
+    <div class="edge-marker edge-marker--left">back edge</div>
+  </OriginGestureSurface>
+</template>
@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.app.json",
+  "compilerOptions": {
+    "tsBuildInfoFile": "../../node_modules/.tmp/origins-demo.tsbuildinfo",
+    "baseUrl": ".",
+    "paths": {
+      "@native-vue-router/core-v2": ["../../packages/core-v2/src/index.ts"]
+    }
+  },
+  "include": ["src/**/*.ts", "src/**/*.vue"]
+}
@@ -0,0 +1,174 @@
+import path from "node:path";
+import vue from "@vitejs/plugin-vue";
+import { defineConfig, type Plugin } from "vite";
+import { VitePWA } from "vite-plugin-pwa";
+
+/**
+ * Recover browsers that visited this hostname while Docker still served Vite's
+ * development mode. Its development worker can retain HTML that imports
+ * `/@vite/client` and `/src/main.ts`; a normal static fallback would return
+ * HTML for those module URLs and leave the visitor on a blank screen.
+ *
+ * This preview-only compatibility endpoint is requested only by that obsolete
+ * shell. It clears the old origin-local worker/cache state and writes the
+ * current production HTML into the document. The production application then
+ * registers the real `/sw.js` worker normally.
+ */
+function legacyDevelopmentWorkerMigration(): Plugin {
+  const migrationSource = `
+void (async () => {
+  if ("serviceWorker" in navigator) {
+    const registrations = await navigator.serviceWorker.getRegistrations();
+    await Promise.all(registrations.map((registration) => registration.unregister()));
+  }
+  if ("caches" in window) {
+    const names = await caches.keys();
+    await Promise.all(names.map((name) => caches.delete(name)));
+  }
+
+  const productionDocument = await fetch(
+    "/index.html?origin-pwa-migration=" + Date.now(),
+    { cache: "no-store" },
+  );
+  const html = await productionDocument.text();
+  document.open();
+  document.write(html);
+  document.close();
+})();
+`;
+
+  return {
+    name: "origins-legacy-development-worker-migration",
+    configurePreviewServer(server) {
+      server.middlewares.use((request, response, next) => {
+        const pathname = new URL(request.url ?? "/", "http://origins.local")
+          .pathname;
+
+        if (pathname === "/@vite/client") {
+          response.statusCode = 200;
+          response.setHeader("Content-Type", "text/javascript; charset=utf-8");
+          response.setHeader("Cache-Control", "no-store");
+          response.end(
+            "// Compatibility stub for the retired Vite dev client.",
+          );
+          return;
+        }
+
+        if (pathname === "/src/main.ts") {
+          response.statusCode = 200;
+          response.setHeader("Content-Type", "text/javascript; charset=utf-8");
+          response.setHeader("Cache-Control", "no-store");
+          response.end(migrationSource);
+          return;
+        }
+
+        next();
+      });
+    },
+  };
+}
+
+export default defineConfig({
+  root: __dirname,
+  base: "./",
+  // Reuse the workspace's existing install icons rather than maintaining a
+  // second set that can silently drift from the main demo.
+  publicDir: path.resolve(__dirname, "../../public"),
+  plugins: [
+    vue(),
+    legacyDevelopmentWorkerMigration(),
+    VitePWA({
+      registerType: "autoUpdate",
+      devOptions: {
+        // The hosted Docker service runs Vite's development server, so its
+        // public HTTPS URL also needs a real manifest and service worker.
+        enabled: true,
+        navigateFallback: "index.html",
+        suppressWarnings: true,
+      },
+      includeAssets: [
+        "favicon.svg",
+        "app-icon.svg",
+        "apple-touch-icon.png",
+        "pwa-192.png",
+        "pwa-512.png",
+      ],
+      manifest: {
+        id: "/",
+        name: "Routeless Origins Lab",
+        short_name: "Origins Lab",
+        description:
+          "Seven interactive labs for a routeless Vue animation and gesture engine.",
+        theme_color: "#080b12",
+        background_color: "#080b12",
+        display: "standalone",
+        scope: "/",
+        start_url: "/",
+        orientation: "any",
+        icons: [
+          {
+            src: "/pwa-192.png",
+            sizes: "192x192",
+            type: "image/png",
+            purpose: "any",
+          },
+          {
+            src: "/pwa-512.png",
+            sizes: "512x512",
+            type: "image/png",
+            purpose: "any",
+          },
+          {
+            src: "/pwa-512.png",
+            sizes: "512x512",
+            type: "image/png",
+            purpose: "maskable",
+          },
+          {
+            src: "/app-icon.svg",
+            sizes: "any",
+            type: "image/svg+xml",
+            purpose: "any",
+          },
+        ],
+      },
+      workbox: {
+        cleanupOutdatedCaches: true,
+        clientsClaim: true,
+        skipWaiting: true,
+        navigateFallback: "/index.html",
+        globPatterns: ["**/*.{js,css,html,svg,png,woff2}"],
+      },
+    }),
+  ],
+  server: {
+    // The development container is reached through this Traefik hostname.
+    // Keeping the allow-list explicit preserves Vite's DNS-rebinding defense.
+    allowedHosts: ["v2.demo.native-router.harvmaster.com"],
+  },
+  preview: {
+    allowedHosts: ["v2.demo.native-router.harvmaster.com"],
+  },
+  resolve: {
+    alias: [
+      {
+        find: /^@native-vue-router\/core-v2\/style\.css$/,
+        replacement: path.resolve(
+          __dirname,
+          "../../packages/core-v2/src/style.css",
+        ),
+      },
+      {
+        find: /^@native-vue-router\/core-v2$/,
+        replacement: path.resolve(
+          __dirname,
+          "../../packages/core-v2/src/index.ts",
+        ),
+      },
+    ],
+  },
+  build: {
+    outDir: path.resolve(__dirname, "dist"),
+    emptyOutDir: true,
+  },
+});
@@ -8,30 +8,55 @@ A forward drag calls `router.resolve()` and Vue Router's public `loadRouteLocati

 Each preview subtree receives a scoped `routeLocationKey`, so `useRoute()` returns preview params even though the global route is not committed. A normal `router.push()` or `replace()` runs only after the gesture chooses to commit. A guard failure cancels the transaction and removes the preview.

+Preview routes can contain ordinary Vue `<Suspense>` boundaries. A route may therefore become a live navigation surface immediately, show its fallback while async child setup continues, and preserve the resolved child when the route later moves into the mounted cache. Route guards remain commit-time authority and can still reject that cached destination on a later entry attempt.
+
 ## Transaction lifecycle

 Transactions move through `interactive`, `committing`, `settling`, and cancellation states. They expose normalized progress and velocity plus `fromKey`, `toKey`, direction, presentation, and optional source geometry.

 The runtime deliberately keeps two ledgers. The navigation stack mirrors committed push/replace/pop semantics and is the only source of predictive-back targets. The view cache owns mounted component instances independently, so a replaced tab can be reused without becoming an accidental back destination.

-Pointer movement changes only a CSS progress variable. Built-in presentations restrict active-frame work to compositor-friendly properties. Release uses distance/velocity intent and a damped spring. Reduced-motion mode settles immediately.
+Pointer movement changes only a CSS progress variable. Built-in presentations restrict active-frame work to compositor-friendly properties. When a destination needs a new component tree, the runtime resolves its lazy route, mounts it, and gives the browser a preparation frame before motion starts; cached destinations skip that wait. Velocity is expressed as normalized route progress per second, so gesture behavior remains consistent across screen sizes. Release uses distance/velocity intent and a damped spring whose settling rate follows the user's flick speed. Reduced-motion mode settles immediately.

 Settling animations are interruptible. A new button navigation or recognized gesture waits only for any in-flight Vue Router guard/history commit, immediately finalizes the old visual transaction, and begins from the newly authoritative route. It never waits for the previous spring to finish. Leading-edge back recognition runs in the navigator capture phase so partially visible component layers cannot steal the physical back edge.

+### Runtime domains
+
+`runtime.ts` is the public transaction coordinator. Its supporting domains live
+under `packages/core/src/runtime`:
+
+- `vue-router-bridge.ts` contains all Vue Router-specific integration: route
+  resolution and loading, commit operations, `afterEach` reconciliation,
+  browser-history completion, and the scoped Options API `$route` bridge.
+- `history-ledger.ts` owns native push, replace, and pop history semantics.
+- `view-store.ts` owns mounted route entries, active state, preview reuse,
+  eviction, underlay protection, and cache statistics.
+- `animation.ts` owns gesture commit policy, view preparation, and spring
+  settling.
+- `presentations.ts` owns built-in and application-defined presentations.
+- `diagnostics.ts` owns runtime diagnostic subscriptions and event emission.
+- `route-entry.ts` owns route-entry construction, labels, timestamps, and
+  sibling direction.
+
+Keeping the Vue Router adapter separate makes the compatibility work visible
+and prevents history, cache, rendering, and animation policy from accumulating
+inside the integration layer.
+
 Component gesture owners stop propagation before a containing navigator can claim the same pointer. Navigator gestures wait for horizontal intent, use pointer capture, respect form controls and `data-native-gesture="ignore"`, and preserve normal vertical scrolling through `touch-action: pan-y`.

 ## Route metadata

 ```ts
 interface NativeRouteOptions {
-  navigator?: string
-  presentation?: 'push' | 'reveal' | 'slide' | 'fade' | 'modal' | 'sheet' | string
-  parent?: RouteLocationRaw | ((route) => RouteLocationRaw)
-  siblingGroup?: string
-  siblingOrder?: number
-  siblingHistory?: 'push' | 'replace'
-  cache?: boolean
-  gesture?: boolean | 'edge' | 'full'
+  navigator?: string;
+  presentation?:
+    "push" | "reveal" | "slide" | "fade" | "modal" | "sheet" | string;
+  parent?: RouteLocationRaw | ((route) => RouteLocationRaw);
+  siblingGroup?: string;
+  siblingOrder?: number;
+  siblingHistory?: "push" | "replace";
+  cache?: boolean | "pin";
+  gesture?: boolean | "edge" | "full";
 }
 ```

@@ -40,19 +65,54 @@ interface NativeRouteOptions {
 ## Custom presentations

 ```ts
-nativeRouter.registerPresentation(definePresentation({
-  name: 'scale-fade',
-  axis: 'x',
+nativeRouter.registerPresentation(
+  definePresentation({
+    name: "scale-fade",
+    axis: "x",
    layerStyle({ role, progress }) {
-    return role === 'to'
+      return role === "to"
        ? { opacity: progress, transform: `scale(${0.92 + progress * 0.08})` }
-      : { opacity: 1 - progress * 0.4 }
+        : { opacity: 1 - progress * 0.4 };
    },
-}))
+  }),
+);
 ```

 Applications can call `beginInteractive()`, `updateInteractive()`, and `finishInteractive()` to drive the same transaction engine from a bespoke recognizer.

 ## Cache semantics

-The active route and recent inactive routes remain mounted. The default limit is eight inactive views per runtime. Older entries keep their route descriptor but are unmounted and lazily restored when revisited. Application data that must survive eviction belongs in an application store.
+The cache is lazy: application startup mounts the current route, not every sibling. A replace-style sibling is created when it is first visited or previewed and can then remain mounted without becoming a browser-back entry. Recent history targets can also stay warm so predictive Back restores component-local state such as a scrolled list immediately.
+
+The default limit is four inactive views per runtime. `cache: false` always unmounts an inactive route, while `cache: 'pin'` exempts it from ordinary LRU and default bulk trimming. A pushed detail route that is popped or dismissed is unmounted after its exit animation unless it is explicitly pinned. If a guard rejects a cached destination, that component tree is evicted because it is no longer a valid navigation target. Older entries keep lightweight route descriptors and are lazily reconstructed if history reaches them again.
+
+Applications can explicitly release an inactive location with `nativeRouter.unload('/stories')`. It returns the number of component instances unmounted, retains history descriptors, and refuses to unload the active route or either side of an in-progress transition. `trimCache()` remains the bulk operation.
+
+This is deliberately not implemented with a single Vue `<KeepAlive>`. An interactive transition must render the current and destination route instances concurrently, while one `<KeepAlive>` outlet normally activates one selected child. Separate temporary wrappers would themselves be removed and lose their caches. The runtime therefore owns the small multi-view cache and exposes equivalent route-aware lifecycle signals:
+
+```ts
+import {
+  onNativeViewActivate,
+  onNativeViewDeactivate,
+  onNativeViewEvict,
+  useNativeViewActiveEffect,
+  useNativeViewLifecycle,
+} from "@native-vue-router/core";
+
+const view = useNativeViewLifecycle();
+
+useNativeViewActiveEffect(() => {
+  const timer = startPolling();
+  return () => stopPolling(timer);
+});
+
+onNativeViewEvict((reason) => saveDraft(view.route.value, reason));
+```
+
+`isActive` means the route is authoritative. `isVisible` also includes either side of an in-progress transition and the visible, inert route beneath a partial sheet. Use `useNativeViewActiveEffect` for polling and other work that should pause in a cached tab, or `useNativeViewVisibleEffect` for work needed during the animation or while painted beneath a sheet. Application data that must survive eviction belongs in an application store.
+
+## Optional performance profiler
+
+`createNativeNavigationProfiler(runtime)` correlates `requestAnimationFrame` intervals with timing-safe runtime events: route loading, cold view preparation, transaction start/commit/end, and eviction. It estimates the device's actual refresh interval instead of assuming 60 Hz, then flags frame gaps larger than 1.5 times that baseline. Reports also include Long Tasks, layout shifts, event timing, and resource timing when the host implements those Performance Observer entry types.
+
+Safari does not currently expose every Chromium performance entry, so rAF cadence and native-router events are the portable ground truth. Visibility changes are retained because backgrounding or the share sheet can throttle rAF and would otherwise resemble dropped frames. Sampling is completely opt-in and capped at 30,000 frames by default. Route labels use record names or declared path patterns, never params or query values.
@@ -0,0 +1,204 @@
+# Engineering Challenges, Vue Router Limitations, and Trade-offs
+
+## The fundamental mismatch
+
+Vue Router is designed around an authoritative current route. A navigation resolves a location, runs guards, updates history, and makes that location current; `<RouterView>` then renders the matching component. That model is correct for normal web navigation.
+
+Interactive native navigation needs a second, provisional route before any of those semantic effects are committed. The destination must be fully rendered beside the source while the user is still free to cancel. Much of the work in Native Vue Router exists to bridge that mismatch without forking Vue Router or relying on its internals.
+
+## Challenge 1: showing two route locations at once
+
+### Limitation
+
+The usual `<RouterView>` follows the global current route. A CSS transition around a normal router view can animate old and new DOM after navigation, but it cannot naturally provide a live, reversible destination before navigation.
+
+### Approach
+
+The runtime resolves and loads the destination, creates a preview entry, and renders explicit router views for both entries using the `route` prop. A scoped `routeLocationKey` is provided inside each entry so descendants using `useRoute()` read the correct route for that surface.
+
+### Trade-off
+
+Two component trees may be live simultaneously. Preview components can mount before commit, so their setup and data loading must tolerate cancellation. Irreversible side effects should be tied to committed application state or view activation, not blindly to component mount.
+
+## Challenge 2: preserving Vue Router authority
+
+### Limitation
+
+It would be simpler to maintain a completely separate navigation stack and update the URL afterward, but that would bypass guards, redirects, route encoding, and existing Vue Router integrations.
+
+### Approach
+
+The preview phase never mutates Vue Router history. Commit uses public Vue Router navigation operations. The runtime then accepts the actual resulting route, including redirects, as authoritative and discards any stale preview.
+
+### Trade-off
+
+The visual runtime must maintain and reconcile a second ledger. This is deliberate duplication of visual/navigation bookkeeping, with explicit invariants to keep the two systems aligned.
+
+## Challenge 3: predictive back and opaque browser history
+
+### Limitation
+
+The browser does not expose a portable array of prior route locations. Calling `router.back()` also does not synchronously reveal the destination. A cold-start deep link may have an external page, another application, or no useful same-app route behind it.
+
+### Approach
+
+The runtime records committed native view keys and uses that ledger for warm-session predictive back. Routes can declare a logical `parent` for cold-start prediction. The actual pop still goes through Vue Router/browser history when a real entry exists.
+
+### Trade-off
+
+Applications must describe route topology where history alone is insufficient. A declared parent is a product-level relationship, not proof that the corresponding browser history entry exists. Synthetic parents use replace semantics when committed.
+
+## Challenge 4: guards, redirects, and asynchronous loading
+
+### Limitation
+
+Lazy modules, route guards, redirects, and browser pops resolve asynchronously. Meanwhile, gesture input and animation frames continue. A response from an old navigation can arrive after a newer interaction has started.
+
+### Approach
+
+Every transaction and begin attempt receives a monotonically increasing identity. Async continuations verify that they still own the current attempt and transaction before mutating state. Guard rejection springs back; redirect results become authoritative; stale previews are removed.
+
+### Trade-off
+
+Only one visual transaction is authoritative at a time. The runtime supports rapid sequential interruption, not multiple independent transitions mutating one navigator concurrently.
+
+## Challenge 5: interruption without a navigation cooldown
+
+### Limitation
+
+The easiest animation model locks input until a transition completes. That creates a visible cooldown and feels unlike a native application. Simply cancelling animation promises is unsafe because Vue Router may already be committing history.
+
+### Approach
+
+Settling motion and semantic navigation are treated separately. A new interaction can interrupt the spring immediately, but it waits for any already-started Vue Router navigation to resolve. The prior transaction is finalized at the route Vue Router accepted, and the new transaction begins from that authoritative state.
+
+Pointer recognizers also detach their local state before awaiting anything. Captured progress, velocity, and transaction ID travel with the old release callback, while a new pointer can start cleanly. Both move and release continuations check ownership before cleanup.
+
+### Trade-off
+
+A route guard or browser-history operation can still impose real latency because semantic navigation cannot safely be cancelled after the platform has begun it. The library removes animation cooldown; it cannot remove application guard or network latency.
+
+## Challenge 6: direction and topology for sibling routes
+
+### Limitation
+
+Vue Router knows route hierarchy and matching, but not that `/inbox`, `/stories`, and `/profile` are ordered pages on a horizontal strip. Browser history order also does not necessarily match visual tab order.
+
+### Approach
+
+The navigator receives its peer route list, while routes declare `siblingOrder` and optional sibling history semantics. Direction is derived from route order. The sibling presentation moves both surfaces one-to-one, rather than placing a new foreground layer over the old one.
+
+### Trade-off
+
+Visual topology must be explicit. Automatic inference from route declaration order would be fragile in modular or dynamically registered route sets.
+
+## Challenge 7: velocity that behaves consistently
+
+### Limitation
+
+Raw pointer velocity in pixels per millisecond changes meaning with viewport size. A fixed-duration animation also ignores whether the user released slowly or flicked decisively.
+
+### Approach
+
+Velocity is normalized by the gesture surface width or height and expressed as route progress per second. It influences both the commit decision and the rate of the damped settling spring. High-speed springs are advanced in small simulation substeps to avoid numerical instability.
+
+### Trade-off
+
+The current spring constants and velocity scaling are shared defaults rather than a fully configurable physics system. Extremely high input is clamped, preserving stability over perfectly reproducing every raw pointer sample.
+
+## Challenge 8: gesture arbitration
+
+### Limitation
+
+A horizontal movement may mean browser back, application back, tab paging, a component action, text selection, or ordinary scrolling. Bubbling alone is insufficient because a partially revealed child layer can steal the physical edge from its navigator.
+
+### Approach
+
+Leading-edge back recognition runs in the navigator's capture phase. Component gestures own non-edge drags by stopping propagation. Recognition waits for a directional threshold, then uses pointer capture. Form controls and explicit ignore regions are excluded, while CSS `touch-action` leaves the perpendicular scroll axis available.
+
+### Trade-off
+
+Applications must design gesture regions intentionally. Highly interactive canvases, maps, carousels, editors, and nested horizontal scrollers should opt out or provide their own arbitration.
+
+## Challenge 9: native edge gestures on the web
+
+### Limitation
+
+Web content cannot set `WKWebView.allowsBackForwardNavigationGestures`. In a normal iOS Safari tab, the browser may reserve an edge sequence before page JavaScript receives enough input to implement its own predictive back.
+
+### Approach
+
+The installed iOS PWA uses a non-passive leading-edge touch guard at capture time and disables horizontal overscroll as far as web content permits. The guard is intentionally inactive in a normal browser tab. Electron disables Chromium overscroll history navigation at the host level. Capacitor supplies the deterministic native container option.
+
+### Trade-off
+
+An installed PWA can provide a strong approximation, not an absolute WebKit-level guarantee. Products that require complete ownership of the native back gesture should use the Capacitor host.
+
+## Challenge 10: view caching without corrupting history
+
+### Limitation
+
+Keeping a tab mounted is a rendering concern; deciding whether Back should visit it is a history concern. Treating one list as both caused stale conversations and replaced tabs to appear as incorrect back targets.
+
+### Approach
+
+The runtime separates the history-key ledger from the mounted-view cache. A replaced sibling is created lazily and can remain reusable without entering the back path. Popped pushed routes and guard-rejected destinations are evicted; history descriptors remain available for reconstruction. Statuses distinguish active, inactive, preview, and evicted entries. Route-aware active/visible effects give cached components a way to suspend work.
+
+### Trade-off
+
+Mounted routes consume memory. The inactive cache is bounded and can be trimmed by the host, while `cache: false` and `cache: 'pin'` make exceptional route policy explicit. Evicted component-local state is not guaranteed to survive. Durable state belongs in Pinia, another store, IndexedDB, or the backend.
+
+Vue's `<KeepAlive>` was not used as the cache owner. One shared wrapper is designed to select a current child, but a predictive gesture renders two route instances concurrently. Creating independent wrappers per temporary route layer would make wrapper lifetime control cache lifetime and complicate deterministic LRU eviction. The trade-off is a small router-owned cache with lifecycle APIs instead of Vue's built-in activated/deactivated hooks.
+
+## Challenge 11: accessibility with concurrent routes
+
+### Limitation
+
+Two visible DOM subtrees can create duplicate landmarks, focus targets, and screen-reader content. A hidden cached route can also accidentally receive pointer or keyboard input.
+
+### Approach
+
+Inactive entries are hidden, `inert`, and `aria-hidden`. Only the active route or interactive pair is presented visually. Back and tab controls remain semantic buttons and links. Reduced-motion preference settles transactions immediately.
+
+### Trade-off
+
+Custom presentations and application overlays must preserve these invariants. Focus transfer at commit may still require application-specific handling for complex screens.
+
+## Challenge 12: reliable PWA updates
+
+### Limitation
+
+Service-worker lifecycle, HTTP caching, Safari foreground behavior, and installed Home Screen state can leave an old application shell active even after a deployment. Reloading immediately is also dangerous during an interactive transaction.
+
+### Approach
+
+Production builds use automatic worker activation and check on registration, focus, foreground resume, reconnection, and a periodic timer. Reload is deferred until the native transaction is idle. The demo exposes a build ID and update-check count, and local development/preview uses conservative cache headers.
+
+### Trade-off
+
+Deployment infrastructure must still avoid long-lived caching for `sw.js` and the HTML shell. A client running code from before the automatic update policy may need one final manual refresh or reinstall; new code cannot retroactively change an old worker's behavior before it is loaded.
+
+## Current limitations
+
+- Client-side DOM navigation is the first-class target; SSR and hydration of a live visual stack are not currently a complete feature.
+- One runtime coordinates one authoritative visual transaction at a time. Independent nested navigation controllers need an explicit ownership design.
+- `navigator` and `siblingGroup` metadata are reserved topology fields; the current `NativeNavigator` still receives its sibling route list explicitly. Likewise, `gesture: false` is the enforced opt-out, while finer `edge`/`full` policy is primarily expressed by navigator and component structure today.
+- Route previews may mount application code that later gets cancelled.
+- Cold-start predictive back requires declared parent topology.
+- Cache eviction does not preserve arbitrary component-local state.
+- The browser cannot guarantee native gesture suppression at the same level as Capacitor or a custom `WKWebView`.
+- Presentation physics are currently library defaults rather than route-by-route configurable tokens.
+- Long sessions keep lightweight route descriptors in the ledger even when their component trees are evicted. Mounted DOM is bounded, but applications with exceptionally large histories may eventually benefit from indexed lookup and descriptor compaction.
+- Native appearance is broader than navigation: slow screen rendering, non-native controls, layout shifts, or inappropriate typography can still break the illusion.
+
+## Summary of deliberate trade-offs
+
+| Decision                                      | Benefit                                              | Cost                                                   |
+| --------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------ |
+| Keep Vue Router authoritative                 | Guards, URLs, redirects, and ecosystem compatibility | Reconciliation complexity                              |
+| Render a preview before commit                | Truly interactive and cancellable navigation         | Two live component trees and preview side effects      |
+| Maintain separate history and view ledgers    | Correct back semantics plus tab caching              | More state and invariants                              |
+| Interrupt springs but finish semantic commits | No animation cooldown without corrupting history     | Guard/history latency can remain                       |
+| Require explicit route topology               | Deterministic parent and sibling behavior            | More route metadata                                    |
+| Bound mounted views                           | Predictable DOM and memory use                       | Component-local state can be evicted                   |
+| Use progressive platform adapters             | One core across PWA, Electron, and Capacitor         | Browser/PWA guarantees remain weaker than native hosts |
@@ -0,0 +1,130 @@
+# How Native Vue Router Works
+
+## Purpose
+
+Native Vue Router adds an interactive visual navigation layer to Vue Router. Its goal is not merely to make route changes slide instead of fade. It is designed so navigation itself can be manipulated: a user can reveal a destination, stop halfway, reverse direction, release with velocity, or begin another navigation before the previous animation has settled.
+
+The library supports four related navigation styles through one transaction engine:
+
+- Edge-driven predictive back, including drag-and-hold.
+- One-to-one paging between ordered sibling routes such as primary tabs.
+- Component-originated navigation, where dragging a row or card reveals its destination.
+- Presented routes such as modals and sheets, including interactive dismissal.
+
+Buttons and links use the same engine as gestures. A tab click, back button, programmatic push, and interactive swipe differ only in how progress is supplied and whether the final commit decision is forced.
+
+## The central idea: semantic state and visual state are different
+
+Vue Router remains the authority for semantic navigation: route matching, URLs, parameters, redirects, guards, lazy route modules, and browser history. Native Vue Router owns temporary visual state: mounted route surfaces, interactive progress, motion, and the relationship between the surface being left and the surface being revealed.
+
+That separation produces two ledgers:
+
+| Ledger              | Owns                                                | Source of truth for                               |
+| ------------------- | --------------------------------------------------- | ------------------------------------------------- |
+| Vue Router          | Current committed route and browser history         | What URL the application is actually on           |
+| Native view runtime | Active, inactive, preview, and evicted view entries | What route surfaces can be rendered during motion |
+
+The ledgers agree at rest. During a gesture they intentionally diverge: Vue Router still reports the committed `from` route while the native runtime also renders an uncommitted `to` route.
+
+## Preview before commit
+
+A forward interaction follows a two-phase process:
+
+1. Resolve the target with Vue Router.
+2. Load its lazy route component without pushing a history entry.
+3. Add a preview entry to the native view ledger.
+4. Render both the committed route and preview route through explicit `<RouterView :route>` instances.
+5. Drive their transforms from normalized gesture progress between `0` and `1`.
+6. On release, decide whether to commit from distance and velocity.
+7. Only then call Vue Router's `push()`, `replace()`, or browser-backed `back()`.
+8. Reconcile the visual ledger with the route Vue Router actually accepted.
+
+If the user reverses the gesture or a navigation guard rejects the target, the preview springs away and is removed. The URL never briefly changes to a route that the user did not commit.
+
+Each preview subtree receives its own scoped Vue Router route injection. As a result, components rendered in the preview see the preview's params and metadata through `useRoute()`, even though the application's global committed route has not changed yet.
+
+## Predictive back
+
+Back navigation is harder than forward navigation because browser history does not expose a reliable, portable list of previous route objects. The runtime therefore maintains its own committed history-key ledger alongside Vue Router.
+
+When a back gesture starts, the runtime locates the preceding native view entry and renders it beneath the current one. The browser URL remains unchanged while the user drags. On commit, the runtime calls Vue Router/browser back and reconciles with the route that actually wins.
+
+A cold-start deep link has no in-memory predecessor. Route metadata can declare a logical `parent`, either as a route location or a function of the current route. That gives the runtime a synthetic predictive-back destination without pretending that a browser history entry exists.
+
+## Transactions
+
+All navigation motion is represented by a `NativeTransaction`. A transaction identifies:
+
+- Its kind: push, pop, sibling, present, or dismiss.
+- The `from` and `to` view keys.
+- Direction and presentation.
+- Normalized progress and velocity.
+- Whether commit uses push or replace semantics.
+- Its lifecycle phase and optional component source geometry.
+
+The important phases are interactive, committing, and settling. During the interactive phase, pointer movement directly controls progress. A release changes the phase and starts a damped spring toward either `0` or `1`.
+
+Velocity is measured as route progress per second rather than pixels per millisecond. A flick therefore behaves consistently on a small phone and a wide desktop window. High release velocity also advances the settling spring faster, so fast intent produces fast completion.
+
+Transactions are interruptible. Starting a new navigation while a spring is settling does not wait for the old visual animation. The runtime waits only for an in-flight Vue Router history or guard decision, finalizes the old transaction at its authoritative endpoint, and begins the next transaction from that route. Transaction IDs prevent delayed pointer, preload, animation, and navigation callbacks from mutating a newer interaction.
+
+## Rendering and presentation
+
+`NativeRouterView` keeps cached route entries as sibling layers. At rest, only the active layer is interactive. A partial sheet also keeps its prior route visible but inert as an underlay. During a transaction, exactly the `from` and `to` entries receive interactive roles.
+
+Built-in presentations include push, reveal, adjacent-page slide, fade, modal, sheet, and no-motion. Sheets retain their presentation after commit so they remain below the device safe top and can use content height or developer-defined snap points while the inert route beneath stays visible. Partial sheets animate their measured surface instead of a transparent viewport-sized wrapper, preserving motion from the first frame and keeping the underlay scale continuous across commit. Their scroll body hands top/down and bottom/up overscroll to sheet resizing while retaining ordinary content scrolling at interior positions. Sibling slide is deliberately different from a stack push: both pages move one screen-width for one screen-width of gesture progress, so the interaction feels like paging a continuous horizontal surface.
+
+The runtime publishes progress as a CSS custom property. Built-in motion is mostly expressed through transforms and opacity, keeping per-frame JavaScript work constant. Applications can register presentations whose layer styles are functions of progress, role, direction, and optional source geometry.
+
+First use has unavoidable setup work—downloading/evaluating a lazy chunk and mounting/layout of its Vue tree—but it does not need to compete with the transition. The runtime completes lazy resolution first, then gives newly mounted destinations a browser preparation frame before advancing progress. Full-surface dimming uses a composited opacity overlay rather than a changing CSS filter so WebKit does not repeatedly rasterize the route subtree.
+
+## Gesture ownership
+
+Gesture recognition uses Pointer Events and waits for clear directional intent before claiming a pointer. Vertical scrolling remains available through `touch-action`, while form controls, editable content, and elements marked with `data-native-gesture="ignore"` are excluded.
+
+Ownership is explicit:
+
+- The application navigator owns the physical leading edge for back navigation.
+- A component gesture link owns drags that begin on that component away from the back edge.
+- A sheet dismissal surface owns downward vertical drags.
+
+Scrollable sheets choose content or sheet ownership from the gesture's initial directional intent and keep that owner until release. A content-owned gesture does not become a sheet gesture merely because it later reaches an edge or reverses; the next gesture can begin at that edge and resize the sheet. This prevents concurrent scrolling and avoids applying distance accumulated by content to sheet geometry.
+
+Pointer capture keeps delivery stable after recognition. Recognizer state is detached synchronously at pointer release, before route loading or animation promises are awaited. This is essential: a delayed callback from one gesture must never erase the state of a newer gesture.
+
+## History and cache are intentionally separate
+
+Primary sibling routes normally replace one another in history. Their component trees can still remain mounted in the view cache. This means returning to a tab can preserve local UI state without making every tab selection a browser-back destination.
+
+Siblings are mounted lazily on their first visit or gesture preview, not all at application startup. The cache has a configurable inactive-view limit and an explicit opt-out/pin policy. Popping a pushed route releases its component tree after the exit animation; a rejected cached guard target is evicted immediately. Older entries retain route descriptors but their component trees are unmounted and restored lazily. Durable application data should live in an application store rather than depending on a route component remaining cached forever.
+
+A normal Vue `<KeepAlive>` is excellent when one outlet selects one child. It is not the cache primitive here because an interactive transition needs two independently addressed route instances to be active at once. Instead, the router owns those sibling view instances and exposes active, visible, cached, and eviction lifecycle signals. This preserves the useful KeepAlive distinction—mounted versus currently active—without coupling navigation history to Vue's single-child activation model.
+
+## Platform behavior
+
+The core runtime is host-neutral. Platform adapters add capabilities that a browser-only router should not own:
+
+- The PWA adapter reserves the leading edge in installed iOS standalone mode as early as web content allows.
+- The Electron adapter disables Chromium overscroll history navigation and bridges host back/forward commands.
+- The Capacitor adapter integrates hardware back, deep links, app lifecycle cancellation, root exit, and haptics.
+
+This is progressive capability, not user-agent imitation. Normal browser tabs still work, but a browser may reserve gestures before JavaScript can claim them. Electron and Capacitor can disable or coordinate host behavior more deterministically.
+
+## Why this pattern is uncommon
+
+There is prior work in mobile web navigation and animated router outlets, so the claim is not that interactive routing has never existed. What is unusual is combining Vue Router compatibility, live destination previews, reversible gestures, native-style history semantics, interruption, and multiple hosts in one reusable runtime.
+
+Several factors make that combination rare:
+
+1. **Web routers are commit-first.** Their normal unit of work is “change the current location, then render it.” Native interaction needs “render the possible destination, let the user manipulate it, then decide whether location changes.”
+2. **The platform does not expose a native navigation controller.** Browser history, DOM rendering, pointer recognition, safe areas, service workers, and host gestures are separate systems with separate lifecycles.
+3. **Two live routes complicate assumptions.** Route injection, focus, accessibility, component side effects, caching, redirects, and scroll ownership all become more difficult when a route is visible but not current.
+4. **Correct interruption is harder than animation.** A polished demo can lock input while a transition runs. A native-feeling library must accept new intent during route loading, guard resolution, history mutation, and spring settling without stale asynchronous work winning.
+5. **Host guarantees differ.** A browser tab cannot promise the same edge ownership as a native `WKWebView`, while Electron and Capacitor can change host settings.
+6. **The implementation cost is disproportionate.** Most web products can accept non-interactive transitions. The additional state machine, testing matrix, memory use, and platform work are justified only when navigation feel is a core product requirement.
+
+Native Vue Router addresses this by treating interactive navigation as its own stateful system while leaving Vue Router authoritative wherever Vue Router is strongest.
+
+## Scope
+
+The library is a client-side navigation runtime, not a replacement for Vue Router and not a native rendering engine. It can closely reproduce native navigation composition and input behavior, but final fidelity still depends on application design, frame performance, platform embedding, typography, safe-area handling, and avoiding expensive work in route components during a gesture.
@@ -2,26 +2,28 @@

 ## PWA and browser

-The demo uses a standalone manifest, Apple Home Screen metadata and PNG icons, safe-area environment variables, and a generated Workbox service worker. Updates are prompted and cannot reload while a gesture is active. The Navigation Lab exposes the live display mode, service-worker state, edge-guard state, and intercepted-touch count.
+The demo uses a standalone manifest, Apple Home Screen metadata and PNG icons, safe-area environment variables, and a generated Workbox service worker. Production builds check for updates on startup, focus, foreground resume, network reconnection, and once per minute. A new worker activates automatically; its page reload is deferred until no gesture transaction is active. The Navigation Lab exposes the build ID, update checks, live display mode, service-worker state, edge-guard state, and intercepted-touch count.

 The normal `npm run dev` server enables the development service worker and listens on local network interfaces; no PWA-specific command is required. iOS still requires the resulting address to be delivered through HTTPS before service-worker and Home Screen behavior is available.

+For a production-style update test, deploy successive `npm run build` outputs at the same HTTPS origin. The service-worker entry file must be served without long-lived HTTP caching; fingerprinted files under `assets/` can remain immutable. An already-installed build that predates the automatic updater may require one final manual refresh or reinstall before it can receive the new update policy.
+
 In an installed iOS Home Screen app, the PWA adapter installs non-passive leading-edge touch listeners before the navigator gesture and applies `overscroll-behavior-x: none`. This gives the application the earliest web-content opportunity to claim the sequence. The guard is disabled in normal Safari tabs so the demo does not unexpectedly override browser navigation.

 Mobile operating systems can reserve gestures before web content receives them. A PWA cannot set `WKWebView.allowsBackForwardNavigationGestures`, so absolute native-level suppression cannot be guaranteed from JavaScript. The full interaction system targets installed PWAs; use the Capacitor host when that native switch must be deterministic. Normal tabs retain links, buttons, history, and non-interactive transitions as their fallback.

 ## Electron

-Call `disableElectronHistoryGestures(app.commandLine)` before `app.whenReady()`. It disables Chromium's `OverscrollHistoryNavigation`, preventing the host from racing the renderer's interactive stack. The included preload bridge maps app commands and Alt+Arrow shortcuts into the renderer adapter without enabling Node integration.
+Call `disableElectronHistoryGestures(app.commandLine)` before `app.whenReady()`. It disables Chromium's `OverscrollHistoryNavigation`, preventing the host from racing the renderer's interactive stack. The included preload bridge maps app commands, memory-pressure notifications, and Alt+Arrow shortcuts into the renderer adapter without enabling Node integration.

 The demo switches to hash history under `file:` so packaged deep navigation never asks the filesystem for route paths.

 ## Capacitor

-`createCapacitorAdapter()` handles Android hardware back, Universal/App Links, launch URLs, pause cancellation, root exit, and native haptic feedback.
+`createCapacitorAdapter()` handles Android hardware back, Universal/App Links, launch URLs, pause cancellation, root exit, and native haptic feedback. It trims inactive views when the native app pauses by default; set `trimCacheOnPause: false` only when the application deliberately prefers warm views over background memory release.

 The checked-in iOS and Android projects use Capacitor 8 and include App, Haptics, Splash Screen, and Status Bar plugins. Rebuild the web bundle before `npx cap sync`.

 ## Accessibility

-Inactive live routes are `inert` and `aria-hidden`. Only the active or interactive pair participates in focus and pointer hit testing. Back and tab controls retain native link/button semantics; reduced-motion users receive immediate transaction settling. Custom presentations must preserve the same focus and inert invariants.
+Inactive live routes are `inert` and `aria-hidden`. Only the active or interactive pair participates in focus and pointer hit testing. A partial sheet's visible underlay is also inert and `aria-hidden`; it remains painted only to provide visual context beneath the sheet backdrop. Back and tab controls retain native link/button semantics; reduced-motion users receive immediate transaction settling. Custom presentations must preserve the same focus and inert invariants.
@@ -0,0 +1,205 @@
+# Core Principles, Scalability, and Flexibility
+
+## Core principles
+
+### 1. Vue Router remains authoritative
+
+Native Vue Router is a visual transaction system around Vue Router, not a competing URL router. Matching, encoding, guards, redirects, and committed history stay with Vue Router. If the two systems disagree after navigation, Vue Router's accepted route wins.
+
+This principle preserves compatibility and gives the runtime a clear recovery rule.
+
+### 2. Preview is not commitment
+
+A destination may be loaded, mounted, and visible without being current. Gesture progress must never imply semantic commitment. The URL, browser history, analytics, and irreversible business actions should change only when the transaction commits.
+
+### 3. Gestures are first-class navigation input
+
+A gesture is not a decorative transition attached after `router.push()`. It begins a navigation candidate, controls its progress, and chooses commit or cancellation. Buttons, links, hardware back, and gestures feed the same runtime so they cannot develop contradictory behavior.
+
+### 4. Navigation must remain interruptible
+
+Users should not wait for visual settling before expressing the next intent. Animations are disposable; committed route decisions are not. New input may interrupt presentation immediately while respecting any semantic operation already in flight.
+
+### 5. Route topology should be explicit
+
+History order, visual sibling order, and logical parentage are different concepts. Applications declare parent and sibling relationships rather than relying on incidental route registration or click history.
+
+### 6. History and rendering are separate concerns
+
+A route can be cached without belonging in the back stack, and a back destination can be reconstructed without remaining mounted. This separation is essential for tabs, sheets, deep links, and bounded memory.
+
+### 7. Async work never owns state forever
+
+Every preload, pointer continuation, route commit, and animation frame is conditional on a current attempt or transaction identity. Stale work becomes a no-op. Cleanup is ownership-aware and cannot erase a newer gesture.
+
+### 8. The active frame should be cheap
+
+Pointer movement updates normalized progress. Rendering derives from that value. Built-in sibling motion uses only adjacent transforms, and JavaScript work per frame does not grow with route count. Route components should avoid layout churn and heavyweight synchronous work during previews.
+
+### 9. Host capabilities are adapters, not conditionals scattered through core
+
+Hardware back, haptics, deep links, WebKit edge behavior, and Electron command-line switches belong at the platform boundary. The transaction model remains the same across hosts.
+
+### 10. Accessibility is a state invariant
+
+Cached and preview DOM must not create duplicate interactive applications. Inactive layers are isolated from focus and assistive technology, controls keep native semantics, and reduced-motion behavior is deterministic.
+
+## Scalability model
+
+The runtime is intended to scale in four different ways: number of routes, session length, application complexity, and number of host platforms.
+
+### Route and DOM scale
+
+Only the active route, previously visited inactive routes, and a transaction preview need mounted component trees. Siblings are not instantiated eagerly at application startup. `maxInactive` bounds the inactive mounted cache; the default is four. Pinned entries are deliberately outside this ordinary budget. Older views are marked evicted and lazily remounted when needed.
+
+During an interaction, animation work concerns two surfaces regardless of total route count:
+
+| Resource                         | Growth behavior                       |
+| -------------------------------- | ------------------------------------- |
+| Animated surfaces                | Constant: `from` and `to`             |
+| Mounted inactive component trees | Bounded by `maxInactive`              |
+| Route descriptors/history keys   | Grows with navigation history         |
+| Per-frame transaction state      | Constant                              |
+| Lazy route code                  | Loaded on first preview or navigation |
+
+The current implementation uses linear searches through view entries for some reconciliation operations. This is appropriate for ordinary application histories and a small mounted cache. If the runtime is used for sessions with thousands of unique committed entries, a key/path index and descriptor compaction would be a sensible evolution without changing the public transaction model.
+
+### Data scale
+
+The view cache is not an application data cache. Large collections, message history, drafts, and durable form state should live outside route component instances. This allows view eviction to remain cheap and makes state available whether a route is reached through a gesture, deep link, background notification, or restored session.
+
+Cached components should also avoid doing active-screen work indefinitely. Route-aware lifecycle effects let polling, animation loops, media, and subscriptions stop while a component is inactive and resume without losing its local render state. Hosts can call `trimCache()` under memory pressure; the Capacitor adapter does so when the app pauses by default.
+
+Preview loading should fetch only what the destination needs to render its initial surface. Applications can use route-level lazy imports, shared stores, request deduplication, and cancellation to avoid duplicating expensive work during a cancelled preview.
+
+### Team and feature scale
+
+Navigation policy is carried by route metadata and small primitives rather than screen-specific animation code. Feature teams can define:
+
+- Presentation and gesture policy on their routes.
+- Logical parents for deep-linked screens.
+- Sibling order and history behavior for peer lists owned by a navigator.
+- Component-owned gesture entry points.
+
+Cross-cutting behavior remains in the runtime. This reduces the risk that every feature implements a slightly different back threshold, history mutation, or animation lock.
+
+For very large applications, route topology should be assembled from typed feature modules and validated in tests. Parent cycles, duplicate sibling ordering, and incompatible nested gesture regions are application configuration errors and should be caught before runtime.
+
+### Platform scale
+
+The `NativePlatformAdapter` interface keeps platform growth additive. A new host can install listeners, provide haptics, or coordinate root exit without changing route matching or presentation code. The existing PWA, Electron, and Capacitor adapters demonstrate three capability levels:
+
+1. Best-effort control from web content.
+2. Desktop host control around a web renderer.
+3. Native mobile container integration.
+
+Platform-specific policy should not leak into route components unless the product experience genuinely differs.
+
+## Flexibility and extension points
+
+### Route metadata
+
+Metadata expresses topology and defaults close to route definitions:
+
+```ts
+{
+  path: '/chat/:id',
+  component: () => import('./ChatView.vue'),
+  meta: {
+    native: {
+      parent: '/inbox',
+      presentation: 'push',
+      gesture: 'edge',
+    },
+  },
+}
+```
+
+Ordered peers are passed to `NativeNavigator`. Their routes use `siblingOrder` to derive direction, while `siblingHistory` decides whether selection replaces or grows history. Metadata supplies defaults, while individual runtime calls can override presentation, direction, replacement, and source geometry. `gesture: false` disables navigator gesture handling for a route; finer ownership remains structural in the current implementation.
+
+### Custom presentations
+
+Presentation definitions receive only the data needed to derive layer styles:
+
+```ts
+nativeRouter.registerPresentation(
+  definePresentation({
+    name: "scale-fade",
+    axis: "x",
+    layerStyle({ role, progress }) {
+      return role === "to"
+        ? { opacity: progress, transform: `scale(${0.94 + progress * 0.06})` }
+        : { opacity: 1 - progress * 0.25 };
+    },
+  }),
+);
+```
+
+A presentation does not decide history or commit. Keeping motion separate from navigation semantics makes new visual styles safer to add.
+
+### Custom recognizers
+
+Applications with a bespoke interaction can call:
+
+- `beginInteractive()` to create and preload a candidate.
+- `updateInteractive()` with normalized progress and velocity.
+- `finishInteractive()` to apply the normal commit decision.
+- `cancelInteractive()` to settle back.
+
+This permits interactions such as a card expansion, trackpad scrub, keyboard-driven preview, or canvas gesture without duplicating the route transaction machinery.
+
+Custom recognizers must follow the same ownership rules: one current transaction, normalized input, stale-callback protection, and explicit cancellation on teardown.
+
+### Visual presets
+
+The core owns behavior and minimum presentation CSS. Higher-level packages can supply tab bars, back controls, motion tokens, typography, and platform-adaptive appearance. Product teams can replace the preset without replacing the transaction runtime.
+
+### Platform adapters
+
+Adapters can install host listeners and optionally provide haptic feedback or root-exit behavior. They should translate host events into runtime operations instead of editing runtime ledgers directly.
+
+## Adoption patterns
+
+The architecture supports incremental use:
+
+1. **Imperative transitions only:** use `push`, `pop`, `sibling`, `present`, and `dismiss` with buttons and links.
+2. **Predictive back:** wrap the route surface in `NativeNavigator` and declare cold-start parents.
+3. **Horizontal route paging:** add ordered sibling routes.
+4. **Component-originated navigation:** wrap selected rows or cards with `NativeGestureLink`.
+5. **Custom product motion:** register presentations or drive transactions from a custom recognizer.
+6. **Host integration:** add the PWA, Electron, or Capacitor adapter according to the guarantees required.
+
+Teams do not need to make every route gesture-driven at once. Route metadata can disable gestures while retaining native runtime navigation.
+
+## Reliability and testing principles
+
+Interactive routing failures are temporal, so tests must assert state during transitions rather than only final URLs. The test suite should preserve these invariants:
+
+- The `from` and `to` routes are both live during a held gesture.
+- The URL does not change before commit.
+- Sibling direction follows declared order.
+- Adjacent siblings remain edge-to-edge at intermediate progress.
+- Navigating to the active route is a strict no-op.
+- A guard rejection removes the preview and restores the source.
+- Back never selects an unrelated cached view.
+- A new click or gesture can interrupt settling.
+- Rapid pointer releases cannot leave an orphaned transaction.
+- Fast, short flicks commit through velocity and settle faster.
+- Modal and sheet presentation is independent of previous history shape.
+- PWA worker activation and update checks remain observable.
+
+Final-state tests alone would miss most of the bugs that make a router feel non-native.
+
+## Evolution rules
+
+Future work should preserve the following boundaries:
+
+- Do not make preview routes authoritative early to simplify animation.
+- Do not infer back targets from the mounted cache.
+- Do not make presentation definitions mutate history.
+- Do not solve platform behavior with host checks scattered through core.
+- Do not introduce input locks as a substitute for correct interruption.
+- Do not let stale async cleanup run without verifying ownership.
+- Do not rely on component mount as proof of committed navigation.
+
+Likely extensions include configurable spring profiles, indexed ledgers for unusually long sessions, stronger focus restoration, explicit multi-navigator ownership, SSR-safe initial stack hydration, and more platform-specific motion presets. Each can be added while retaining the same central model: preview visually, commit semantically, and reconcile authoritatively.
@@ -0,0 +1,140 @@
+# Routeless origins architecture
+
+The v2 experiment lives in `packages/core-v2` and its physical test application
+lives in `apps/origins-demo`.
+
+## State model
+
+The scene contains:
+
+- stable, flat Vue component nodes;
+- linked mounted-instance history entries;
+- temporary directed operation edges.
+
+It does not contain an active route or current view.
+
+For overlapping operations:
+
+```text
+Nodes:       X, Y, Z
+Edges:       X → Y
+             Y → Z
+```
+
+Each edge records its own progress, velocity, outcome, choreography, and
+source/target keys.
+
+## Coordinate composition
+
+Suppose A is X→Y and B is Y→Z:
+
+```text
+visual(X) = A.source
+visual(Y) = A.target × B.source
+visual(Z) = A.target × B.target
+```
+
+An optional frame effect is included on both sides of an edge:
+
+```text
+visual(Y) = A.frame × A.target × B.frame × B.source
+visual(Z) = A.frame × A.target × B.frame × B.target
+```
+
+The implementation emits these operations as one combined transform on each
+flat host. This has the visual semantics of nested coordinate frames without
+reparenting Vue component VNodes.
+
+## Completion
+
+Committing a forward X→Y:
+
+1. Keeps X mounted but marks it parked, inert, and visually hidden.
+2. Places Y in X's former visual graph position.
+3. Removes the X→Y edge.
+4. Leaves any Y→Z edge and all mounted descendants intact.
+
+Committing Y→Z before X→Y is also valid. Z replaces Y as the target of the
+still-running X edge, after which X→Y effectively becomes X→Z. The unit suite
+covers both completion orders.
+
+Committing back from Y to X reveals the existing X node and removes Y. It does
+not construct X again from its recipe. Cancelling a forward edge restores its
+source and removes the newly created target branch; cancelling a back edge
+re-parks its retained target.
+
+Committing a replace from Y to Z creates Z but links it directly to Y's
+previous entry:
+
+```text
+Before: X (parked) ← Y (visible)
+After:  X (parked) ← Z (visible)
+```
+
+Y remains mounted while the operation is interactive and is removed only on
+commit. Cancelling removes Z and restores Y, making replacement one atomic
+operation rather than a visible back followed by a forward push.
+
+### Connected partial presentations
+
+Most committed pushes collapse their temporary operation edge and park the
+retained source. A choreography with `persistAtRest: true` instead keeps its
+progress-`1` effects as a settled coordinate relationship:
+
+```text
+Page (exposed, inert) → Drawer (active)
+```
+
+This supports partial destinations without copying or remounting either Vue
+component. For a two-thirds drawer, the settled source effect translates the
+page right by two thirds, while the target finishes at its identity position.
+The page's left third therefore remains physically visible in the final third
+of the viewport.
+
+Settled relationships are not live operations and are omitted from the public
+operation diagnostics. Beginning back temporarily suspends the relationship
+and lets a reciprocal close choreography start at the same endpoints. A
+cancelled close restores the settled edge; a committed close removes the drawer
+and returns the page to its normal root position.
+
+## Interaction
+
+Gesture recognition is declared within each component through
+`OriginGesture` or `useOriginGesture()`. The injected scene-node key determines
+the origin. Recognition never asks a coordinator which view is active.
+
+The immutable `gesture` builder separates optional pointer-down policy
+(`.from`), movement recognition (`.to`), release policy (`.complete`),
+navigation intent (`.navigate`), and visual choreography (`.animate`). A chain
+that begins at `.to` is valid and admits pointer-down anywhere on its host.
+
+At pointer release, the operation decides synchronously whether it will commit
+or cancel. Its spring may continue afterward. A retained target can therefore
+originate another routine while the preceding spring is still visible.
+
+### Nested scenes
+
+An `OriginScene` may be rendered inside a view owned by another scene. The
+nearest injected node scope makes carousel or deck gestures operate on the
+nested scene, with local measurements and retained history.
+
+Gesture ownership between nested scenes is currently selected at pointer-down.
+An eligible child stops propagation even if its later navigation factory
+declines. Parent fallback therefore requires the child to reserve a
+non-matching `.from` region; automatic delayed arbitration remains future
+gesture-arena work.
+
+## Retained history
+
+Each pushed node stores the key of its mounted previous entry. The chain is
+local to that origin context rather than a URL:
+
+```text
+X (parked) ← Y (parked) ← Z (visible)
+```
+
+Back targets the previous node key directly. A node is unmounted only when a
+committed back operation pops it, a forward operation is cancelled, or the
+current entry is successfully replaced, or the whole scene is destroyed.
+Because the same DOM survives parking, nested scroll positions and
+component-local state survive without `<KeepAlive>`.
@@ -0,0 +1,38 @@
+# Vue Router guard/history experiment
+
+This small app compares the browser's current URL and history position with
+Vue Router's `currentRoute` while a real `beforeResolve` guard is pending.
+
+## Run it
+
+From the repository root:
+
+```sh
+npm --prefix experiments/router-guard-history run dev
+```
+
+Open the URL printed by Vite.
+
+## Suggested tests
+
+### Forward navigation
+
+1. Enable **Pause the next `beforeResolve`**.
+2. Click **Push Alpha**.
+3. While paused, compare **Browser URL** with **router.currentRoute**.
+4. Allow or reject the navigation.
+
+For `router.push()`, both values remain on the outgoing route until the guard
+allows confirmation.
+
+### Back navigation
+
+1. Push **Alpha**, then push **Beta**.
+2. Enable **Pause the next `beforeResolve`**.
+3. Click **Router Back**.
+4. While paused, compare **Browser URL** with **router.currentRoute**.
+5. Reject the navigation and watch the browser restore its previous history
+   entry, or repeat the test and allow it.
+
+The event timeline separately records the raw browser `popstate`, Vue Router
+guards, the URL, `currentRoute`, and the navigation result.
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Vue Router Guard History Experiment</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
@@ -0,0 +1,18 @@
+{
+  "name": "router-guard-history-experiment",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vue-tsc -b && vite build"
+  },
+  "dependencies": {
+    "@vitejs/plugin-vue": "^6.0.7",
+    "typescript": "~6.0.2",
+    "vite": "^8.1.1",
+    "vue": "^3.5.39",
+    "vue-router": "^5.0.6",
+    "vue-tsc": "^3.3.5"
+  }
+}
@@ -0,0 +1,138 @@
+<script setup lang="ts">
+import { computed, ref } from "vue";
+import { RouterView } from "vue-router";
+import { experiment, record } from "./experiment";
+import { router } from "./router";
+
+const renderTick = ref(0);
+const browserUrl = computed(() => {
+  renderTick.value;
+  return `${window.location.pathname}${window.location.search}${window.location.hash}`;
+});
+const historyPosition = computed(() => {
+  renderTick.value;
+  return window.history.state?.position ?? "not available";
+});
+
+function refreshBrowserState() {
+  renderTick.value += 1;
+}
+
+window.addEventListener("popstate", refreshBrowserState);
+router.afterEach(refreshBrowserState);
+
+function navigate(kind: "push" | "replace", target: string) {
+  record(`action: ${kind}(${target})`, router.currentRoute.value.fullPath, {
+    target,
+  });
+  void router[kind](target).then(() => refreshBrowserState());
+}
+
+function back() {
+  record("action: router.back()", router.currentRoute.value.fullPath);
+  router.back();
+}
+
+function settle(allow: boolean) {
+  experiment.pendingGuard?.settle(allow);
+}
+
+function clearLog() {
+  experiment.logs.splice(0);
+}
+</script>
+
+<template>
+  <main>
+    <header>
+      <p class="eyebrow">Vue Router experiment</p>
+      <h1>What changes while <code>beforeResolve</code> is pending?</h1>
+      <p class="intro">
+        Pause the next resolve guard, navigate, and compare the browser URL with
+        Vue Router's authoritative route.
+      </p>
+    </header>
+
+    <section class="status-grid">
+      <div>
+        <span>Browser URL</span>
+        <strong>{{ browserUrl }}</strong>
+      </div>
+      <div>
+        <span>router.currentRoute</span>
+        <strong>{{ router.currentRoute.value.fullPath }}</strong>
+      </div>
+      <div>
+        <span>history.state.position</span>
+        <strong>{{ historyPosition }}</strong>
+      </div>
+    </section>
+
+    <section class="controls">
+      <label class="hold-toggle">
+        <input v-model="experiment.holdNextResolve" type="checkbox" />
+        Pause the next <code>beforeResolve</code>
+      </label>
+
+      <div class="button-row">
+        <button @click="navigate('push', '/home')">Push Home</button>
+        <button @click="navigate('push', '/alpha')">Push Alpha</button>
+        <button @click="navigate('push', '/beta')">Push Beta</button>
+        <button @click="navigate('replace', '/alpha')">Replace Alpha</button>
+        <button class="back" @click="back">Router Back</button>
+      </div>
+
+      <div v-if="experiment.pendingGuard" class="gate">
+        <div>
+          <span>Navigation paused</span>
+          <strong>
+            {{ experiment.pendingGuard.from }} →
+            {{ experiment.pendingGuard.to }}
+          </strong>
+        </div>
+        <button class="allow" @click="settle(true)">Allow navigation</button>
+        <button class="reject" @click="settle(false)">Reject navigation</button>
+      </div>
+    </section>
+
+    <RouterView />
+
+    <section class="log-panel">
+      <div class="log-heading">
+        <div>
+          <p class="eyebrow">Event timeline</p>
+          <h2>Newest event first</h2>
+        </div>
+        <button class="quiet" @click="clearLog">Clear log</button>
+      </div>
+
+      <div class="log-table">
+        <div class="log-row log-labels">
+          <span>Time / event</span>
+          <span>Browser URL</span>
+          <span>Current route</span>
+          <span>Target / result</span>
+        </div>
+        <div v-for="entry in experiment.logs" :key="entry.id" class="log-row">
+          <span
+            ><small>{{ entry.elapsed }}</small
+            >{{ entry.event }}</span
+          >
+          <code>{{ entry.browserUrl }}</code>
+          <code>{{ entry.currentRoute }}</code>
+          <span>
+            <code v-if="entry.target">{{ entry.target }}</code>
+            <small v-if="entry.detail">{{ entry.detail }}</small>
+          </span>
+        </div>
+      </div>
+    </section>
+
+    <aside>
+      <strong>Suggested test</strong>
+      Push Alpha, then Beta. Enable the pause checkbox and click Router Back.
+      While the guard is paused, inspect the two route values and then try both
+      rejection and approval.
+    </aside>
+  </main>
+</template>
@@ -0,0 +1,78 @@
+import { reactive } from "vue";
+import type {
+  NavigationFailure,
+  RouteLocationNormalizedLoaded,
+} from "vue-router";
+
+export interface ExperimentLog {
+  id: number;
+  elapsed: string;
+  event: string;
+  browserUrl: string;
+  currentRoute: string;
+  target?: string;
+  historyPosition?: unknown;
+  detail?: string;
+}
+
+interface PendingGuard {
+  to: string;
+  from: string;
+  settle(allow: boolean): void;
+}
+
+const startedAt = performance.now();
+let sequence = 0;
+
+export const experiment = reactive<{
+  holdNextResolve: boolean;
+  pendingGuard: PendingGuard | null;
+  logs: ExperimentLog[];
+}>({
+  holdNextResolve: false,
+  pendingGuard: null,
+  logs: [],
+});
+
+function browserUrl() {
+  return `${window.location.pathname}${window.location.search}${window.location.hash}`;
+}
+
+export function record(
+  event: string,
+  currentRoute: string,
+  options: { target?: string; detail?: string } = {},
+) {
+  experiment.logs.unshift({
+    id: ++sequence,
+    elapsed: `${(performance.now() - startedAt).toFixed(1)} ms`,
+    event,
+    browserUrl: browserUrl(),
+    currentRoute,
+    target: options.target,
+    historyPosition: window.history.state?.position,
+    detail: options.detail,
+  });
+}
+
+export function waitForDecision(
+  to: RouteLocationNormalizedLoaded,
+  from: RouteLocationNormalizedLoaded,
+) {
+  return new Promise<boolean>((resolve) => {
+    experiment.pendingGuard = {
+      to: to.fullPath,
+      from: from.fullPath,
+      settle(allow) {
+        experiment.pendingGuard = null;
+        resolve(allow);
+      },
+    };
+  });
+}
+
+export function describeFailure(failure?: NavigationFailure | void) {
+  return failure
+    ? `navigation failure type ${String(failure.type)}`
+    : "navigation confirmed";
+}
@@ -0,0 +1,13 @@
+import { createApp } from "vue";
+import App from "./App.vue";
+import { record } from "./experiment";
+import { router } from "./router";
+import "./style.css";
+
+const app = createApp(App);
+app.use(router);
+app.mount("#app");
+
+void router.isReady().then(() => {
+  record("router: ready", router.currentRoute.value.fullPath);
+});
@@ -0,0 +1,71 @@
+import {
+  createRouter,
+  createWebHistory,
+  type RouteRecordRaw,
+} from "vue-router";
+import ExperimentPage from "./views/ExperimentPage.vue";
+import {
+  describeFailure,
+  experiment,
+  record,
+  waitForDecision,
+} from "./experiment";
+
+const routes: RouteRecordRaw[] = [
+  { path: "/", redirect: "/home" },
+  {
+    path: "/home",
+    component: ExperimentPage,
+    props: { title: "Home", color: "#6d5efc" },
+  },
+  {
+    path: "/alpha",
+    component: ExperimentPage,
+    props: { title: "Alpha", color: "#ef5da8" },
+  },
+  {
+    path: "/beta",
+    component: ExperimentPage,
+    props: { title: "Beta", color: "#2bbf8a" },
+  },
+];
+
+export const router = createRouter({
+  history: createWebHistory(),
+  routes,
+});
+
+// This listener sees the raw browser traversal. For a back/forward traversal,
+// compare its URL with router.currentRoute in the event log.
+window.addEventListener("popstate", () => {
+  record("window: popstate", router.currentRoute.value.fullPath);
+});
+
+router.beforeEach((to) => {
+  record("router: beforeEach", router.currentRoute.value.fullPath, {
+    target: to.fullPath,
+  });
+});
+
+router.beforeResolve(async (to, from) => {
+  record("router: beforeResolve entered", router.currentRoute.value.fullPath, {
+    target: to.fullPath,
+  });
+  if (!experiment.holdNextResolve) return;
+
+  experiment.holdNextResolve = false;
+  const allow = await waitForDecision(to, from);
+  record(
+    allow ? "beforeResolve: allowed" : "beforeResolve: rejected",
+    router.currentRoute.value.fullPath,
+    { target: to.fullPath },
+  );
+  return allow || false;
+});
+
+router.afterEach((to, _from, failure) => {
+  record("router: afterEach", router.currentRoute.value.fullPath, {
+    target: to.fullPath,
+    detail: describeFailure(failure),
+  });
+});
@@ -0,0 +1,256 @@
+:root {
+  color: #e8e9f3;
+  background: #11131a;
+  font-family:
+    Inter,
+    ui-sans-serif,
+    system-ui,
+    -apple-system,
+    BlinkMacSystemFont,
+    "Segoe UI",
+    sans-serif;
+  font-synthesis: none;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  min-width: 320px;
+  min-height: 100vh;
+}
+
+button,
+input {
+  font: inherit;
+}
+
+button {
+  border: 1px solid #3b3e4c;
+  border-radius: 0.65rem;
+  padding: 0.7rem 0.95rem;
+  color: #f5f5fa;
+  background: #252834;
+  cursor: pointer;
+}
+
+button:hover {
+  background: #303442;
+}
+
+main {
+  width: min(1180px, calc(100% - 2rem));
+  margin: 0 auto;
+  padding: 3rem 0 5rem;
+}
+
+header {
+  max-width: 760px;
+}
+
+h1,
+h2,
+p {
+  margin-top: 0;
+}
+
+h1 {
+  margin-bottom: 0.75rem;
+  font-size: clamp(2rem, 5vw, 4.25rem);
+  line-height: 0.98;
+  letter-spacing: -0.055em;
+}
+
+h2 {
+  margin-bottom: 0;
+  font-size: 1.1rem;
+}
+
+.eyebrow,
+.status-grid span,
+.gate span,
+.route-page span,
+small {
+  color: #979baa;
+  font-size: 0.72rem;
+  font-weight: 700;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.intro {
+  color: #aeb1be;
+  font-size: 1.05rem;
+}
+
+.status-grid {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 0.75rem;
+  margin: 2rem 0 1rem;
+}
+
+.status-grid div,
+.controls,
+.log-panel,
+aside {
+  border: 1px solid #292c38;
+  border-radius: 1rem;
+  background: #181a22;
+}
+
+.status-grid div {
+  display: grid;
+  gap: 0.35rem;
+  padding: 1rem;
+}
+
+.status-grid strong,
+.gate strong {
+  overflow-wrap: anywhere;
+  font-family: ui-monospace, SFMono-Regular, Consolas, monospace;
+}
+
+.controls {
+  padding: 1rem;
+}
+
+.hold-toggle {
+  display: flex;
+  align-items: center;
+  gap: 0.6rem;
+  margin-bottom: 1rem;
+}
+
+.button-row,
+.gate {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.6rem;
+}
+
+.back {
+  margin-left: auto;
+}
+
+.gate {
+  align-items: center;
+  margin-top: 1rem;
+  padding: 0.85rem;
+  border: 1px solid #d6a53a;
+  border-radius: 0.75rem;
+  background: #2a2418;
+}
+
+.gate div {
+  display: grid;
+  gap: 0.25rem;
+  margin-right: auto;
+}
+
+.allow {
+  background: #176b4f;
+}
+
+.reject {
+  background: #7d2d46;
+}
+
+.route-page {
+  min-height: 170px;
+  display: grid;
+  align-content: center;
+  gap: 0.4rem;
+  margin: 1rem 0;
+  padding: 1.5rem;
+  overflow: hidden;
+  border-radius: 1rem;
+  background:
+    radial-gradient(circle at 90% 20%, var(--route-color), transparent 42%),
+    #1b1d27;
+}
+
+.route-page strong {
+  font-size: 2.5rem;
+}
+
+.log-panel {
+  overflow: hidden;
+}
+
+.log-heading {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 1rem;
+  border-bottom: 1px solid #292c38;
+}
+
+.log-heading .eyebrow {
+  margin-bottom: 0.2rem;
+}
+
+.quiet {
+  padding: 0.45rem 0.7rem;
+  background: transparent;
+}
+
+.log-table {
+  overflow-x: auto;
+}
+
+.log-row {
+  min-width: 850px;
+  display: grid;
+  grid-template-columns: 1.35fr 1fr 1fr 1.4fr;
+  gap: 1rem;
+  padding: 0.7rem 1rem;
+  border-top: 1px solid #232630;
+  font-size: 0.85rem;
+}
+
+.log-row > span {
+  display: grid;
+  align-content: start;
+  gap: 0.25rem;
+}
+
+.log-labels {
+  color: #7f8390;
+  border-top: 0;
+  font-size: 0.72rem;
+  font-weight: 700;
+  text-transform: uppercase;
+}
+
+code {
+  color: #d6cffd;
+  font-family: ui-monospace, SFMono-Regular, Consolas, monospace;
+}
+
+aside {
+  margin-top: 1rem;
+  padding: 1rem;
+  color: #aeb1be;
+  line-height: 1.55;
+}
+
+aside strong {
+  color: #f5f5fa;
+}
+
+@media (max-width: 720px) {
+  main {
+    padding-top: 1.5rem;
+  }
+
+  .status-grid {
+    grid-template-columns: 1fr;
+  }
+
+  .back {
+    margin-left: 0;
+  }
+}
@@ -0,0 +1,13 @@
+<script setup lang="ts">
+defineProps<{
+  title: string;
+  color: string;
+}>();
+</script>
+
+<template>
+  <article class="route-page" :style="{ '--route-color': color }">
+    <span>Rendered route component</span>
+    <strong>{{ title }}</strong>
+  </article>
+</template>
@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.app.json",
+  "compilerOptions": {
+    "tsBuildInfoFile": "../../node_modules/.tmp/router-guard-history.tsbuildinfo"
+  },
+  "include": ["src/**/*.ts", "src/**/*.vue", "vite.config.ts"]
+}
@@ -0,0 +1,6 @@
+import vue from "@vitejs/plugin-vue";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [vue()],
+});
@@ -0,0 +1,46 @@
+# WebKit nested composite-transform frame pacing reproduction
+
+This is a dependency-free reproduction for an iOS WebKit frame-pacing issue involving two nested animation clocks:
+
+- A route-sized parent surface whose `translate3d()` progress is updated by `requestAnimationFrame`.
+- A child with an infinite CSS `rotate()` animation, drawn as a rounded border spinner.
+
+On the originating device, spinner durations within part of the `0.5s`–`1.1s` range produced regular 33–34 ms rAF gaps, while durations outside that band were smooth. The workload per frame is effectively unchanged, making the duration-dependent behavior unexpected.
+
+## Run
+
+Open `index.html` directly. The reproduction is a single, self-contained HTML file and works from a `file://` URL without a server.
+
+To test it through a local HTTP server instead, run this from the repository root:
+
+```sh
+npx vite external/bugs/composite-transform
+```
+
+This directory is independent of the Vue demo and has no build step or runtime dependencies. The CSS, test scene, controls, and measurement code are all in `index.html`, so that file can be attached directly to a browser bug report.
+
+## Protocol
+
+1. Do not scroll or touch the page while a sample is running.
+2. Run **Sweep 0.5–1.1 s** with **rAF-driven** selected and **Spinner enabled** checked.
+3. Repeat with **Static translate3d parent**.
+4. Repeat with **No parent transform**.
+5. Clear **Spinner enabled** and run the sweep as a control.
+
+Each duration runs for 1.8 seconds. In the rAF-parent case, the incoming route moves for 700 ms and then remains stationary for the rest of the measurement.
+
+## Expected
+
+Changing only `animation-duration` should alter angular velocity, not cause a stable 60 Hz page to begin missing display deadlines. The rAF stream should remain close to 16.7 ms throughout the sweep on a 60 Hz device.
+
+## Actual observation in the source application
+
+The problematic sample showed:
+
+- A 16 ms baseline.
+- Repeated 33–34 ms gaps during the route transition.
+- The same gaps continuing while the parent was stationary and the spinner remained visible.
+- Normal pacing after the spinner was removed from the DOM.
+- No route-loading delay, JavaScript long task, or layout shift correlated with the gaps.
+
+The reproduction intentionally contains no Vue, Vue Router, Suspense, application store, network request, or service-worker caching logic in its measured path.
@@ -0,0 +1,288 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Nested transform frame-pacing reproduction</title>
+  <style>
+    :root {
+      color-scheme: dark;
+      font: 15px/1.4 system-ui, sans-serif;
+      background: #0b0d12;
+      color: #f5f7ff;
+    }
+
+    * { box-sizing: border-box; }
+
+    body {
+      max-width: 760px;
+      margin: auto;
+      padding: 24px;
+    }
+
+    h1 { margin-bottom: 8px; font-size: 24px; }
+    p { color: #aeb6ca; }
+
+    .controls {
+      display: grid;
+      gap: 12px;
+      margin: 24px 0;
+      padding: 16px;
+      border: 1px solid #30384c;
+      border-radius: 12px;
+      background: #151923;
+    }
+
+    label {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: 16px;
+    }
+
+    input, select, button {
+      min-height: 40px;
+      padding: 8px 12px;
+      border: 1px solid #3a4359;
+      border-radius: 8px;
+      background: #202637;
+      color: inherit;
+      font: inherit;
+    }
+
+    input { width: 110px; }
+    button { cursor: pointer; }
+    button:disabled { cursor: default; opacity: .5; }
+    .buttons { display: flex; gap: 8px; }
+
+    .viewport {
+      position: relative;
+      height: 300px;
+      overflow: hidden;
+      border: 1px solid #30384c;
+      border-radius: 16px;
+      background: #11141c;
+    }
+
+    .under, .route {
+      position: absolute;
+      inset: 0;
+      padding: 28px;
+    }
+
+    .under {
+      background: linear-gradient(135deg, #171c28, #11141c);
+      color: #8f99b0;
+    }
+
+    .route {
+      transform: translate3d(100%, 0, 0);
+      background: #202637;
+      will-change: transform;
+    }
+
+    .card {
+      display: flex;
+      align-items: center;
+      gap: 14px;
+      margin-top: 24px;
+      padding: 18px;
+      border-radius: 12px;
+      background: #151923;
+    }
+
+    .spinner {
+      width: 34px;
+      height: 34px;
+      flex: none;
+      border: 3px solid #4b5570;
+      border-top-color: #74a5ff;
+      border-radius: 50%;
+      animation: spin var(--spinner-duration, .7s) linear infinite;
+    }
+
+    .spinner.off { animation: none; }
+
+    @keyframes spin {
+      to { transform: rotate(360deg); }
+    }
+
+    table {
+      width: 100%;
+      margin-top: 20px;
+      border-collapse: collapse;
+      font-variant-numeric: tabular-nums;
+    }
+
+    th, td {
+      padding: 8px;
+      border-bottom: 1px solid #30384c;
+      text-align: right;
+    }
+
+    th:first-child, td:first-child { text-align: left; }
+    .bad { color: #ff9e9e; }
+  </style>
+</head>
+<body>
+  <h1>Nested composite-transform frame pacing</h1>
+  <p>
+    A CSS border spinner rotates inside a route whose parent transform is driven by
+    <code>requestAnimationFrame</code>. On iOS WebKit, changing only the spinner duration can
+    cause repeatable 33–34 ms frame gaps.
+  </p>
+
+  <div class="controls">
+    <label>
+      Spinner duration
+      <span><input id="duration" type="number" min="0.1" max="3" step="0.05" value="0.7"> s</span>
+    </label>
+    <label>
+      Parent transform
+      <select id="parent-mode">
+        <option value="moving">rAF-driven</option>
+        <option value="static">Static translate3d</option>
+        <option value="none">None</option>
+      </select>
+    </label>
+    <label>
+      Spinner enabled
+      <input id="spinner-enabled" type="checkbox" checked>
+    </label>
+    <div class="buttons">
+      <button id="run" type="button">Run once</button>
+      <button id="sweep" type="button">Sweep 0.5–1.1 s</button>
+      <button id="stop" type="button" disabled>Stop</button>
+    </div>
+    <output id="status">Ready. Each run measures 1.8 seconds.</output>
+  </div>
+
+  <div class="viewport">
+    <div class="under">Existing route</div>
+    <div id="route" class="route">
+      <strong>Incoming route</strong>
+      <div class="card">
+        <span id="spinner" class="spinner"></span>
+        <span>Waiting for asynchronous data…</span>
+      </div>
+    </div>
+  </div>
+
+  <table>
+    <thead>
+      <tr><th>Spinner</th><th>p95</th><th>Max</th><th>Frames &gt; 30 ms</th></tr>
+    </thead>
+    <tbody id="results"><tr><td colspan="4">No runs yet.</td></tr></tbody>
+  </table>
+
+  <script>
+    const durations = [.5, .6, .7, .8, .9, 1, 1.1]
+    const sampleTime = 1800
+    const route = document.querySelector('#route')
+    const spinner = document.querySelector('#spinner')
+    const duration = document.querySelector('#duration')
+    const parentMode = document.querySelector('#parent-mode')
+    const spinnerEnabled = document.querySelector('#spinner-enabled')
+    const runButton = document.querySelector('#run')
+    const sweepButton = document.querySelector('#sweep')
+    const stopButton = document.querySelector('#stop')
+    const status = document.querySelector('#status')
+    const results = document.querySelector('#results')
+    let token = 0
+    let rows = []
+
+    const percentile = (values, amount) => {
+      const sorted = [...values].sort((a, b) => a - b)
+      return sorted[Math.floor((sorted.length - 1) * amount)] || 0
+    }
+
+    function configure(seconds) {
+      document.documentElement.style.setProperty('--spinner-duration', `${seconds}s`)
+      spinner.classList.toggle('off', !spinnerEnabled.checked)
+      spinner.style.animation = 'none'
+      void spinner.offsetWidth
+      spinner.style.animation = ''
+      route.style.willChange = parentMode.value === 'none' ? 'auto' : 'transform'
+      route.style.transform = parentMode.value === 'moving'
+        ? 'translate3d(100%, 0, 0)'
+        : parentMode.value === 'static' ? 'translate3d(0, 0, 0)' : 'none'
+    }
+
+    function measure(seconds, currentToken) {
+      configure(seconds)
+      status.value = `Measuring ${seconds.toFixed(2)} s…`
+
+      return new Promise(resolve => {
+        let started
+        let previous
+        const deltas = []
+
+        function frame(now) {
+          if (currentToken !== token) return resolve(null)
+          started ??= now
+          previous ??= now
+          const elapsed = now - started
+          if (elapsed > 0) deltas.push(now - previous)
+          previous = now
+
+          if (parentMode.value === 'moving') {
+            const progress = Math.min(1, elapsed / 700)
+            const eased = 1 - Math.pow(1 - progress, 3)
+            route.style.transform = `translate3d(${(1 - eased) * 100}%, 0, 0)`
+          }
+
+          if (elapsed < sampleTime) requestAnimationFrame(frame)
+          else resolve({
+            seconds,
+            p95: percentile(deltas, .95),
+            max: Math.max(...deltas),
+            over30: deltas.filter(value => value > 30).length,
+          })
+        }
+
+        requestAnimationFrame(frame)
+      })
+    }
+
+    function render() {
+      results.innerHTML = rows.map(row => `
+        <tr class="${row.over30 ? 'bad' : ''}">
+          <td>${row.seconds.toFixed(2)} s</td>
+          <td>${row.p95.toFixed(1)} ms</td>
+          <td>${row.max.toFixed(1)} ms</td>
+          <td>${row.over30}</td>
+        </tr>`).join('') || '<tr><td colspan="4">No runs yet.</td></tr>'
+    }
+
+    async function run(values) {
+      const currentToken = ++token
+      rows = []
+      render()
+      runButton.disabled = sweepButton.disabled = true
+      stopButton.disabled = false
+
+      for (const value of values) {
+        const result = await measure(value, currentToken)
+        if (!result) break
+        rows.push(result)
+        render()
+      }
+
+      if (currentToken === token) status.value = 'Finished.'
+      runButton.disabled = sweepButton.disabled = false
+      stopButton.disabled = true
+    }
+
+    runButton.addEventListener('click', () => run([Number(duration.value)]))
+    sweepButton.addEventListener('click', () => run(durations))
+    stopButton.addEventListener('click', () => {
+      token++
+      status.value = 'Stopped.'
+    })
+    duration.addEventListener('input', () => configure(Number(duration.value)))
+    parentMode.addEventListener('change', () => configure(Number(duration.value)))
+    spinnerEnabled.addEventListener('change', () => configure(Number(duration.value)))
+    configure(Number(duration.value))
+  </script>
+</body>
+</html>
@@ -1,8 +1,36 @@
 {
-  "name": "native-vue-router-workspace",
+  "name": "@native-vue-router/core-v2",
  "private": true,
-  "version": "0.1.0",
+  "version": "0.1.0-experimental.0",
+  "description": "Routeless, component-owned scene transitions and gesture recognition for Vue 3.",
  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://git.harvmaster.com/Harvmaster/Native-Router-Vue.git"
+  },
+  "files": [
+    "packages/core-v2/dist",
+    "packages/core-v2/API.md",
+    "packages/core-v2/README.md",
+    "skills/build-with-native-vue-router-v2"
+  ],
+  "main": "./packages/core-v2/dist/index.js",
+  "types": "./packages/core-v2/dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./packages/core-v2/dist/index.d.ts",
+      "import": "./packages/core-v2/dist/index.js"
+    },
+    "./style.css": "./packages/core-v2/dist/style.css",
+    "./package.json": "./package.json"
+  },
+  "sideEffects": [
+    "./packages/core-v2/dist/style.css"
+  ],
+  "peerDependencies": {
+    "vue": "^3.5.0"
+  },
  "workspaces": [
    "packages/*",
    "apps/*"
@@ -10,18 +38,27 @@
  "scripts": {
    "dev": "vite --host",
    "build": "npm run build:packages && vue-tsc -b && vite build",
-    "build:packages": "npm run build --workspace @native-vue-router/core --workspace @native-vue-router/preset-native --workspace @native-vue-router/capacitor --workspace @native-vue-router/electron --if-present",
+    "build:packages": "npm run build --workspace @native-vue-router/core --workspace @native-vue-router/core-v2 --workspace @native-vue-router/preset-native --workspace @native-vue-router/capacitor --workspace @native-vue-router/electron --if-present",
+    "build:v2-demo": "npm run build --workspace @native-vue-router/origins-demo",
+    "dev:v2": "npm run dev --workspace @native-vue-router/origins-demo",
+    "serve:v2": "npm run build:v2-demo && npm run preview --workspace @native-vue-router/origins-demo",
    "test": "vitest run",
    "test:watch": "vitest",
    "test:e2e": "playwright test",
    "preview": "vite preview",
    "electron": "npm run build && electron apps/electron/main.mjs",
-    "cap:sync": "npm run build && npm --prefix apps/capacitor exec cap sync"
+    "cap:sync": "npm run build && npm --prefix apps/capacitor exec cap sync",
+    "format": "prettier --write \"**/*.{js,jsx,ts,tsx,json,css,md}\"",
+    "prepare": "npm run build --workspace packages/core-v2",
+    "test:feel": "NODE_ENV=development vite build --mode development --config packages/core-v2/verify/browser/app/vite.config.mjs && node packages/core-v2/verify/browser/run.mjs"
  },
-  "dependencies": {
+  "devDependencies": {
    "@capacitor/app": "^8.0.0",
+    "@capacitor/android": "^8.0.0",
+    "@capacitor/cli": "^8.0.0",
    "@capacitor/core": "^8.0.0",
    "@capacitor/haptics": "^8.0.0",
+    "@capacitor/ios": "^8.0.0",
    "@capacitor/splash-screen": "^8.0.0",
    "@capacitor/status-bar": "^8.0.0",
    "@lucide/vue": "^1.24.0",
@@ -29,26 +66,22 @@
    "@native-vue-router/core": "0.1.0",
    "@native-vue-router/electron": "0.1.0",
    "@native-vue-router/preset-native": "0.1.0",
-    "@tailwindcss/vite": "^4.3.2",
-    "tailwindcss": "^4.3.2",
-    "tw-animate-css": "^1.4.0",
-    "vite-plugin-pwa": "^1.1.0",
-    "vue": "^3.5.39",
-    "vue-router": "^5.0.6"
-  },
-  "devDependencies": {
-    "@capacitor/android": "^8.0.0",
-    "@capacitor/cli": "^8.0.0",
-    "@capacitor/ios": "^8.0.0",
    "@playwright/test": "^1.55.0",
+    "@tailwindcss/vite": "^4.3.2",
    "@types/node": "^24.13.3",
    "@vitejs/plugin-vue": "^6.0.7",
    "@vue/tsconfig": "^0.9.1",
    "electron": "^43.1.1",
    "happy-dom": "^20.10.6",
+    "prettier": "^3.9.6",
+    "tailwindcss": "^4.3.2",
+    "tw-animate-css": "^1.4.0",
    "typescript": "~6.0.2",
    "vite": "^8.1.1",
+    "vite-plugin-pwa": "^1.1.0",
    "vitest": "^3.2.4",
+    "vue": "^3.5.39",
+    "vue-router": "^5.0.6",
    "vue-tsc": "^3.3.5"
  }
 }
@@ -3,9 +3,18 @@
  "version": "0.1.0",
  "type": "module",
  "license": "MIT",
-  "files": ["dist"],
-  "scripts": { "build": "vite build --config vite.config.ts && vue-tsc -p tsconfig.json --emitDeclarationOnly" },
-  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "vite build --config vite.config.ts && vue-tsc -p tsconfig.json --emitDeclarationOnly"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
  "peerDependencies": {
    "@capacitor/app": "^8.0.0",
    "@capacitor/core": "^8.0.0",
@@ -1,45 +1,66 @@
-import { App } from '@capacitor/app'
-import { Capacitor } from '@capacitor/core'
-import { Haptics, ImpactStyle } from '@capacitor/haptics'
-import type { NativePlatformAdapter, NativeRouterRuntime } from '@native-vue-router/core'
+import { App } from "@capacitor/app";
+import { Capacitor } from "@capacitor/core";
+import { Haptics, ImpactStyle } from "@capacitor/haptics";
+import type {
+  NativePlatformAdapter,
+  NativeRouterRuntime,
+} from "@native-vue-router/core";

 export interface CapacitorAdapterOptions {
-  exitAtRoot?: boolean
-  haptics?: boolean
-  deepLinkPath?: (url: URL) => string
+  exitAtRoot?: boolean;
+  haptics?: boolean;
+  /** Release inactive component trees when the native app backgrounds. Defaults to true. */
+  trimCacheOnPause?: boolean;
+  deepLinkPath?: (url: URL) => string;
 }

-export function createCapacitorAdapter(options: CapacitorAdapterOptions = {}): NativePlatformAdapter {
-  const enabled = Capacitor.isNativePlatform()
+export function createCapacitorAdapter(
+  options: CapacitorAdapterOptions = {},
+): NativePlatformAdapter {
+  const enabled = Capacitor.isNativePlatform();
  return {
-    name: enabled ? `capacitor-${Capacitor.getPlatform()}` : 'capacitor-web',
+    name: enabled ? `capacitor-${Capacitor.getPlatform()}` : "capacitor-web",
    async haptic(event) {
-      if (!enabled || options.haptics === false) return
-      if (event === 'selection') await Haptics.selectionChanged()
-      else await Haptics.impact({ style: event === 'commit' ? ImpactStyle.Light : ImpactStyle.Medium })
+      if (!enabled || options.haptics === false) return;
+      if (event === "selection") await Haptics.selectionChanged();
+      else
+        await Haptics.impact({
+          style: event === "commit" ? ImpactStyle.Light : ImpactStyle.Medium,
+        });
    },
    async install(runtime: NativeRouterRuntime) {
-      if (!enabled) return
+      if (!enabled) return;
      const handles = await Promise.all([
-        App.addListener('backButton', async () => {
-          if (runtime.transaction.value) return await runtime.cancelInteractive()
-          if (runtime.canGoBack.value) return void await runtime.pop()
-          if (options.exitAtRoot !== false) await App.exitApp()
+        App.addListener("backButton", async () => {
+          if (runtime.transaction.value)
+            return await runtime.cancelInteractive();
+          if (runtime.canGoBack.value) return void (await runtime.pop());
+          if (options.exitAtRoot !== false) await App.exitApp();
        }),
-        App.addListener('appUrlOpen', ({ url }) => {
-          const parsed = new URL(url)
-          const path = options.deepLinkPath?.(parsed) ?? `${parsed.pathname}${parsed.search}${parsed.hash}`
-          void runtime.push(path || '/')
+        App.addListener("appUrlOpen", ({ url }) => {
+          const parsed = new URL(url);
+          const path =
+            options.deepLinkPath?.(parsed) ??
+            `${parsed.pathname}${parsed.search}${parsed.hash}`;
+          void runtime.push(path || "/");
        }),
-        App.addListener('pause', () => void runtime.cancelInteractive()),
-      ])
-      const launch = await App.getLaunchUrl()
+        App.addListener("pause", () => {
+          void runtime.cancelInteractive();
+          if (options.trimCacheOnPause !== false)
+            runtime.trimCache({ reason: "memory-pressure" });
+        }),
+      ]);
+      const launch = await App.getLaunchUrl();
      if (launch?.url) {
-        const parsed = new URL(launch.url)
-        const path = options.deepLinkPath?.(parsed) ?? `${parsed.pathname}${parsed.search}${parsed.hash}`
-        if (path) void runtime.replace(path, { presentation: 'none' })
+        const parsed = new URL(launch.url);
+        const path =
+          options.deepLinkPath?.(parsed) ??
+          `${parsed.pathname}${parsed.search}${parsed.hash}`;
+        if (path) void runtime.replace(path, { presentation: "none" });
      }
-      return () => { void Promise.all(handles.map((handle) => handle.remove())) }
+      return () => {
+        void Promise.all(handles.map((handle) => handle.remove()));
+      };
    },
-  }
+  };
 }
@@ -1,10 +1,22 @@
-import { defineConfig } from 'vite'
-import { resolve } from 'node:path'
+import { defineConfig } from "vite";
+import { resolve } from "node:path";

 export default defineConfig({
  build: {
-    outDir: 'dist', emptyOutDir: true,
-    lib: { entry: resolve(__dirname, 'src/index.ts'), formats: ['es'], fileName: 'index' },
-    rollupOptions: { external: ['@capacitor/app', '@capacitor/core', '@capacitor/haptics', '@native-vue-router/core'] },
+    outDir: "dist",
+    emptyOutDir: true,
+    lib: {
+      entry: resolve(__dirname, "src/index.ts"),
+      formats: ["es"],
+      fileName: "index",
    },
-})
+    rollupOptions: {
+      external: [
+        "@capacitor/app",
+        "@capacitor/core",
+        "@capacitor/haptics",
+        "@native-vue-router/core",
+      ],
+    },
+  },
+});
@@ -0,0 +1,342 @@
+# Core v2: routeless origins
+
+`@native-vue-router/core-v2` is an experimental, Vue-only scene compositor. It
+does not install Vue Router, resolve URLs, select a globally active route, or
+render through `RouterView`.
+
+The complete function, component, option, type, gesture-edge, and choreography
+reference is in [API.md](./API.md).
+
+## Install from Git
+
+The repository root exposes this workspace package, runs its build during npm's
+Git-dependency preparation, and includes the generated JavaScript, declarations,
+and stylesheet:
+
+```bash
+npm install git+https://git.harvmaster.com/Harvmaster/Native-Router-Vue.git
+```
+
+Pin applications to a commit or tag when reproducibility matters:
+
+```bash
+npm install "git+https://git.harvmaster.com/Harvmaster/Native-Router-Vue.git#<commit-or-tag>"
+```
+
+Vue 3.5 or newer is the only peer dependency.
+
+The Git-installed repository package includes a Codex integration skill at
+`skills/build-with-native-vue-router-v2`. Copy that folder into
+`${CODEX_HOME:-$HOME/.codex}/skills` and invoke it as
+`$build-with-native-vue-router-v2`.
+
+The primitive is:
+
+> A mounted component can originate a routine that creates another component,
+> moves both components relative to the origin's coordinate frame, and retains
+> the previous instance until a committed back operation pops the newer entry.
+
+## Run the experiment
+
+From the workspace root:
+
+```sh
+npm run dev:v2
+```
+
+Open the printed URL to explore nine physical labs:
+
+- a four-view chain that can keep four nodes and three edges live at once;
+- one view with horizontal, vertical, and edge-only declarations;
+- programmatic gallery navigation followed by gesture-owned traversal;
+- a vertically presented media player with local interactive state;
+- a chat that intentionally declares no back gesture;
+- a predicate-gated downward gesture that drops a left-edge dialog;
+- three nested scenes demonstrating cooperative carousels, vertical decks, and
+  an intentional parent/child gesture conflict; and
+- a checkout flow that replaces Payment Details with Confirmation and proves
+  that back returns directly to the retained Hub instance; and
+- a connected two-thirds drawer that keeps the translated source page visible
+  in the exposed final third.
+
+The expandable inspector reports mounted Vue instances, active operation
+edges, animation progress, and recent lifecycle events. In the chain lab,
+swipe rapidly through X → Y → Z → Ω to see all four components mounted while
+their independent frames are still moving.
+
+An installable, offline-capable PWA build of the same experiment is hosted at
+<https://v2.demo.native-router.harvmaster.com/>.
+
+## Basic usage
+
+Create a scene with a component recipe:
+
+```ts
+import { createOriginScene, originView } from "@native-vue-router/core-v2";
+import "@native-vue-router/core-v2/style.css";
+import HomeView from "./HomeView.vue";
+
+export const scene = createOriginScene({
+  initial: originView(HomeView, { accountId: "42" }, { key: "home" }),
+});
+```
+
+Render it:
+
+```vue
+<script setup lang="ts">
+import { OriginScene } from "@native-vue-router/core-v2";
+import { scene } from "./scene";
+</script>
+
+<template>
+  <OriginScene :scene="scene" />
+</template>
+```
+
+Declare an interaction inside the component that should originate it:
+
+```vue
+<script setup lang="ts">
+import {
+  OriginGesture,
+  forward,
+  gesture,
+  originView,
+  slideLeft,
+} from "@native-vue-router/core-v2";
+import ProfileView from "./ProfileView.vue";
+
+const openProfile = gesture.to
+  .left()
+  .navigate(() =>
+    forward(originView(ProfileView, { userId: "7" }, { key: "profile-7" })),
+  )
+  .animate(slideLeft);
+</script>
+
+<template>
+  <OriginGesture :gesture="openProfile">
+    <main>Swipe this component left</main>
+  </OriginGesture>
+</template>
+```
+
+Starting directly at `.to.left()` means pointer-down may occur anywhere on the
+host. Add `.from.left("clamp(24px, 8%, 64px)")` before `.to.right()` for a
+conventional proportional back edge, or `.from.when(context => ...)` for
+arbitrary start policy. `.complete()` can override the choreography's release
+thresholds.
+
+There is no global navigation declaration. If this component should not
+support that gesture, it simply does not render `OriginGesture`.
+
+For an existing element where an additional wrapper is undesirable, use
+`useOriginGesture()` and attach its four pointer handlers directly.
+
+For several gestures on one page surface, keep the definitions in the page and
+pass them to the policy-neutral host:
+
+```vue
+<script setup lang="ts">
+import { OriginGestureSurface } from "@native-vue-router/core-v2";
+
+const gestures = [forwardGesture, backGesture] as const;
+</script>
+
+<template>
+  <OriginGestureSurface as="main" :gestures="gestures">
+    ...
+  </OriginGestureSurface>
+</template>
+```
+
+## Going backward
+
+Every pushed history entry remains mounted. Back resolves the already-mounted
+previous node and pops only the current entry after the operation commits:
+
+```ts
+import {
+  back,
+  gesture,
+  slideRight,
+  useOriginGesture,
+} from "@native-vue-router/core-v2";
+
+const goBack = useOriginGesture(
+  gesture.from
+    .left("max(24px, 6%)")
+    .to.right()
+    .navigate((context) => (context.canGoBack ? back() : null))
+    .animate(slideRight),
+);
+```
+
+Parked entries are visually hidden, inert, and removed from pointer and
+accessibility interaction. Their Vue instances and DOM remain mounted, so
+component-local state and nested element scroll positions are preserved
+naturally. A cancelled back re-parks the previous target; a committed back
+unmounts the entry being left.
+
+The application chooses whether this is exposed as a left-edge gesture,
+toolbar button, keyboard shortcut, Android hardware-back action, or not exposed
+at all.
+
+## Replacing the current entry
+
+Use `replace()` for completed one-way flows such as Payment Details →
+Confirmation:
+
+```ts
+import {
+  originView,
+  replace,
+  slideLeft,
+  useOrigin,
+} from "@native-vue-router/core-v2";
+import OrderConfirmationView from "./OrderConfirmationView.vue";
+
+const origin = useOrigin();
+
+function confirmOrder() {
+  return origin.perform(
+    replace(
+      originView(OrderConfirmationView, { orderId: "NVO-2048" }),
+      slideLeft,
+    ),
+  );
+}
+```
+
+The replacement inherits the current entry's mounted predecessor. It does not
+retain the entry being replaced, so back from Confirmation skips Payment
+Details. The mutation is atomic: a cancelled interactive replacement removes
+the proposed Confirmation and restores Payment Details unchanged.
+
+Inside a gesture builder, omit choreography from the intent:
+
+```ts
+gesture.to
+  .left()
+  .navigate(() => replace(originView(OrderConfirmationView)))
+  .animate(slideLeft);
+```
+
+## Custom choreography
+
+A choreography returns independent effects for its source, target, and their
+shared frame:
+
+```ts
+import { defineOriginChoreography } from "@native-vue-router/core-v2";
+
+export const zoomFromCard = defineOriginChoreography({
+  name: "zoom-from-card",
+  commitThreshold: 0.42,
+  effects: ({ progress, originRect, viewport }) => ({
+    source: {
+      transform: `scale(${1 - progress * 0.08})`,
+      opacity: 1 - progress * 0.4,
+    },
+    target: {
+      transform: `translateY(${(1 - progress) * viewport.height}px)`,
+      style: {
+        borderRadius: `${(1 - progress) * 24}px`,
+      },
+    },
+  }),
+});
+```
+
+`originRect`, `targetRect`, and the scene viewport are measured after the
+target mounts. The gesture may update progress interactively or a normal click
+can call `useOrigin().perform(action)`.
+
+Transforms are concatenated from the oldest origin frame to the newest local
+effect. Opacity is multiplied. Other properties in `style` use local-last
+precedence. Consequently, if X→Y and Y→Z overlap:
+
+```text
+Y transform = (X→Y target) × (Y→Z source)
+Z transform = (X→Y target) × (Y→Z target)
+```
+
+For partial presentations that must keep both views visible after commit, set
+`persistAtRest: true` on the opening choreography:
+
+```ts
+const openDrawer = defineOriginChoreography({
+  persistAtRest: true,
+  effects: ({ progress }) => ({
+    source: { transform: `translateX(${progress * 66.6667}%)` },
+    target: { transform: `translateX(${(progress - 1) * 66.6667}%)` },
+  }),
+});
+```
+
+The retained source becomes visible-but-inert rather than parked. A reciprocal
+back choreography closes the target; a cancelled close restores the connected
+resting effects and both original Vue instances.
+
+## Why scene nodes are flat
+
+The operation graph is not represented as Vue component ancestry. Every
+component has one stable, keyed host directly under `OriginScene`.
+
+If Y were physically moved from an X→Y wrapper to the scene root when an edge
+collapsed, Vue would unmount and recreate Y. Instead, v2 rewrites graph edges
+and recalculates Y's effect layers while every retained VNode stays in the same
+flat host.
+
+“Y is Z's origin” is a coordinate and retained-history relationship, not Vue
+component ancestry.
+
+## Source layout
+
+Each module depends only on the ones listed above it.
+
+| File                    | Responsibility                                                                                    |
+| ----------------------- | ------------------------------------------------------------------------------------------------- |
+| `shared.ts`             | Geometry and environment helpers                                                                  |
+| `choreography.ts`       | Effect types, `defineOriginChoreography()`, presets, and `composeEffects()` style compositing     |
+| `navigation.ts`         | `originView()` recipes and `forward()`, `back()`, `replace()`, `above()`, `under()` actions       |
+| `scene/types.ts`        | Public scene types                                                                                |
+| `scene/graph.ts`        | `SceneGraph`: node and edge storage plus the begin/commit/cancel history rules (all synchronous)  |
+| `scene/scene.ts`        | `Scene` and `OperationHandle`: mounting, measuring, settling spring, compositing, and `useOrigin` |
+| `gesture/definition.ts` | Gesture types, component props, and the immutable `gesture` builder                               |
+| `gesture/recognizer.ts` | Pointer-down admission, `DirectionalTracker`, `GestureRecognizer`, and `useOriginGesture`         |
+| `components/`           | `OriginScene`, `OriginGesture`, `OriginGestureSurface`, and the internal node host                |
+
+Tests live in `tests/`, outside `src/`. `tests/property.test.ts` checks the
+scene's structural invariants after every step of random operation sequences
+and pointer streams; set `PROPERTY_SEEDS` to run more than the default 60.
+
+Pure helpers used by a class (for example `matchesStart`, `stepSpring`, or
+`composeNodeStyle`) are module-level `export const`s that the class calls, so
+they can be tested directly without widening the class's interface.
+
+## Current experimental boundaries
+
+- One operation creates one target. Chaining operations already permits any
+  number of simultaneous scene nodes; multi-target routines are not yet
+  exposed as a public builder.
+- A node can originate one outgoing operation at a time. Its created target
+  may immediately originate the next operation.
+- The included pointer recognizer handles one primary pointer and one axis.
+  Choreographies and scene operations are independent of it.
+- Multiple recognizers can share a host and arbitrate by start policy and
+  directional intent. A dedicated multi-pointer gesture arena is not exposed.
+- Nested `OriginScene` components have independent history and measurements.
+  Child recognizers currently claim propagation at pointer-down, so yielding a
+  region to a parent requires an explicit `.from` policy.
+- Every pushed history entry remains mounted until back pops it. There is not
+  yet an eviction policy, so applications should deliberately reset long-lived
+  navigation contexts when that API is introduced.
+- Parked instances remain mounted and ordinary Vue timers/watchers continue to
+  run. Engine-specific park/resume lifecycle hooks are not exposed yet.
+- Arbitrary CSS properties can be used, but only transforms and opacity have
+  defined multi-operation composition rules at present.
+
+These boundaries are explicit so the experiment can validate the origin
+primitive before compatibility conveniences become permanent architecture.
@@ -0,0 +1,32 @@
+{
+  "name": "@native-vue-router/core-v2",
+  "version": "0.1.0-experimental.0",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://git.harvmaster.com/Harvmaster/Native-Router-Vue.git",
+    "directory": "packages/core-v2"
+  },
+  "files": [
+    "dist",
+    "API.md",
+    "README.md"
+  ],
+  "sideEffects": [
+    "./dist/style.css"
+  ],
+  "scripts": {
+    "build": "vite build --config vite.config.ts && vue-tsc -p tsconfig.json --emitDeclarationOnly"
+  },
+  "peerDependencies": {
+    "vue": "^3.5.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./style.css": "./dist/style.css"
+  }
+}
@@ -0,0 +1,319 @@
+import type { CSSProperties } from "vue";
+import { clamp01, type OriginRect } from "./shared";
+
+/*
+ * Choreographies: the visual side of an operation. A choreography computes
+ * effects from operation progress; `composeEffects` collapses the effects
+ * applied to one node into its inline style. Nothing here knows about history.
+ */
+
+/**
+ * The lifecycle phase of an operation edge.
+ *
+ * - `preparing`: the target has been added and Vue is mounting it.
+ * - `interactive`: progress may be controlled by a gesture or application.
+ * - `settling`: the commit/cancel decision is fixed and the spring is running.
+ * - `finished`: the graph rewrite or cancellation cleanup has completed.
+ */
+export type OriginOperationPhase =
+  "preparing" | "interactive" | "settling" | "finished";
+
+/**
+ * The outcome selected for an operation.
+ *
+ * Intent remains `undecided` until `finish()` is called. It becomes final
+ * before the settling animation completes, allowing the retained target to
+ * originate its own operation immediately.
+ */
+export type OriginOperationIntent = "undecided" | "commit" | "cancel";
+
+/**
+ * One composable contribution to a scene node's final visual style.
+ *
+ * Transforms are concatenated in origin-to-descendant order and opacity values
+ * are multiplied. This lets X→Y and Y→Z affect Y simultaneously without either
+ * routine replacing the other routine's CSS transform.
+ */
+export interface OriginEffect {
+  /**
+   * A CSS transform contribution. Transform strings from inherited and local
+   * origin frames are concatenated rather than replacing one another.
+   */
+  transform?: string;
+  /**
+   * An opacity contribution between `0` and `1`. Contributions from multiple
+   * frames are multiplied and the final value is clamped.
+   */
+  opacity?: number;
+  /**
+   * Relative stacking contribution. `above()` defaults the target to +1 and
+   * `under()` defaults it to -1.
+   */
+  layer?: number;
+  /**
+   * Escape hatch for non-geometric effects such as filter, clipPath, or
+   * borderRadius. Later/local effects override inherited properties.
+   */
+  style?: CSSProperties;
+}
+
+/**
+ * Independent visual contributions calculated for one operation edge.
+ *
+ * Any omitted contribution is treated as an identity effect.
+ */
+export interface OriginEffectSet {
+  /**
+   * Applied to both source and target. This is useful for moving an entire
+   * origin-relative coordinate frame.
+   */
+  frame?: OriginEffect;
+  /** Applied to the component that initiated this operation. */
+  source?: OriginEffect;
+  /** Applied to the component created by this operation and its descendants. */
+  target?: OriginEffect;
+}
+
+/** Values supplied whenever a choreography calculates its visual effects. */
+export interface OriginChoreographyContext {
+  /** Normalized operation progress, clamped to the inclusive range `0..1`. */
+  progress: number;
+  /**
+   * How far a drag has gone past the ends of `progress`: negative when pulled
+   * back beyond the start, positive beyond full progress, otherwise `0`. Use
+   * it for rubber-banding or resistance; most choreographies ignore it.
+   */
+  overshoot: number;
+  /**
+   * Normalized progress units per second. Positive velocity moves toward
+   * commit; negative velocity moves back toward cancellation.
+   */
+  velocity: number;
+  /** Current lifecycle phase of the operation. */
+  phase: OriginOperationPhase;
+  /** Commit/cancel outcome, if release has already selected one. */
+  intent: OriginOperationIntent;
+  /** Origin host bounds captured immediately before the target mounts. */
+  originRect?: OriginRect;
+  /** Target host bounds measured after Vue mounts the target. */
+  targetRect?: OriginRect;
+  /** Scene-container bounds, or the browser viewport when no container exists. */
+  viewport: OriginRect;
+}
+
+/**
+ * A choreography describes visual relationships only. Component creation,
+ * history, and cleanup are performed by the scene operation that uses it.
+ */
+export interface OriginChoreography {
+  /** Optional diagnostic name surfaced by scene inspectors and devtools. */
+  readonly name?: string;
+  /**
+   * Calculate source, target, and shared-frame contributions for the current
+   * operation state. This function should be deterministic and side-effect
+   * free because it can run many times per animation frame.
+   */
+  effects(context: OriginChoreographyContext): OriginEffectSet;
+  /**
+   * Gesture progress required to retain the target after release.
+   *
+   * @defaultValue `0.25`
+   */
+  readonly commitThreshold?: number;
+  /**
+   * Release velocity, in progress units per second, that commits a flick
+   * regardless of progress. Velocity is normalized by the gesture host's
+   * size, so `1` means one full host width (or height) per second.
+   *
+   * @defaultValue `0.2`
+   */
+  readonly commitVelocity?: number;
+  /**
+   * Keep this choreography's progress-`1` effects connected after a committed
+   * push instead of collapsing the edge and hiding its source.
+   *
+   * This is intended for partial presentations such as drawers and inspectors
+   * where part of the retained source remains visible beside the target. The
+   * source remains mounted, visible, and inert. A back operation temporarily
+   * suspends the resting edge; cancelling back restores it.
+   *
+   * Only retained-history `push` actions support connected resting effects.
+   *
+   * @defaultValue `false`
+   */
+  readonly persistAtRest?: boolean;
+  /**
+   * Settling spring after release. A drawer, a sheet, and a full-page push
+   * usually want different springs.
+   */
+  readonly spring?: OriginSpring;
+}
+
+/** Damped-spring settings for settling a released operation. */
+export interface OriginSpring {
+  /**
+   * Pull toward the resting position. Higher settles faster.
+   *
+   * @defaultValue `280`
+   */
+  readonly stiffness?: number;
+  /**
+   * Resistance to motion. Lower overshoots and bounces.
+   *
+   * @defaultValue `30`
+   */
+  readonly damping?: number;
+}
+
+/**
+ * Preserve type inference while declaring a custom choreography.
+ *
+ * The helper performs no runtime transformation. It gives custom routines a
+ * named, documented construction point and validates their shape in TypeScript.
+ *
+ * @param choreography - Side-effect-free visual effect calculator and optional
+ * release thresholds.
+ * @returns The same choreography object.
+ */
+export function defineOriginChoreography(
+  choreography: OriginChoreography,
+): OriginChoreography {
+  return choreography;
+}
+
+/** Distinguish a choreography from a plain options object. */
+export const isChoreography = (value: unknown): value is OriginChoreography => {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "effects" in value &&
+    typeof value.effects === "function"
+  );
+};
+
+/**
+ * Normalize one contribution before the compositor combines it with effects
+ * inherited from earlier origin frames.
+ *
+ * Most applications should return plain effects from a choreography and let
+ * the scene call this function. It is exported for custom compositors and
+ * diagnostics.
+ *
+ * @param effect - Optional effect to normalize.
+ * @param fallbackLayer - Relative layer contribution added to `effect.layer`.
+ * @returns A defined effect with a numeric layer.
+ */
+export function normalizedEffect(
+  effect: OriginEffect | undefined,
+  fallbackLayer = 0,
+): OriginEffect {
+  return {
+    ...effect,
+    layer: (effect?.layer ?? 0) + fallbackLayer,
+  };
+}
+
+/** Whether a transform contributes anything to a composed transform list. */
+function isComposable(transform: unknown): transform is string {
+  return (
+    typeof transform === "string" && transform !== "" && transform !== "none"
+  );
+}
+
+/** Result of collapsing an ordered list of effects into one style. */
+export interface ComposedEffects {
+  /** Merged style with the composed `transform` and `opacity` applied. */
+  readonly style: CSSProperties;
+  /** Sum of every effect's relative layer contribution. */
+  readonly layer: number;
+}
+
+/**
+ * Collapse independent effect layers, ordered from the outermost inherited
+ * frame to the most local one, into a single style.
+ *
+ * Transforms are concatenated and opacities multiplied, including `transform`
+ * and numeric `opacity` supplied through `effect.style`. Every other `style`
+ * property uses local-last precedence over `base` and earlier effects.
+ */
+export const composeEffects = (
+  effects: readonly OriginEffect[],
+  base: CSSProperties = {},
+): ComposedEffects => {
+  const style: CSSProperties = { ...base };
+  const transforms: string[] = [];
+  let opacity = 1;
+  let layer = 0;
+
+  for (const effect of effects) {
+    if (isComposable(effect.transform)) transforms.push(effect.transform);
+    if (effect.opacity !== undefined) opacity *= effect.opacity;
+    layer += effect.layer ?? 0;
+
+    if (effect.style) {
+      Object.assign(style, effect.style);
+      if (isComposable(effect.style.transform))
+        transforms.push(effect.style.transform);
+      if (effect.style.opacity !== undefined) {
+        const styleOpacity = Number(effect.style.opacity);
+        if (Number.isFinite(styleOpacity)) opacity *= styleOpacity;
+      }
+    }
+  }
+
+  // Assign the composed properties last so no single effect's `style` can
+  // replace transform work inherited from other frames.
+  style.transform = transforms.length ? transforms.join(" ") : "none";
+  style.opacity = String(clamp01(opacity));
+  return { style, layer };
+};
+
+const percent = (value: number) => `${(value * 100).toFixed(4)}%`;
+
+/**
+ * Native-style forward motion: the target enters above the source while the
+ * source recedes slightly. These presets are examples; applications can
+ * replace them with arbitrary `defineOriginChoreography()` callbacks.
+ */
+export const slideLeft = defineOriginChoreography({
+  name: "slide-left",
+  effects: ({ progress }) => ({
+    source: {
+      transform: `translate3d(${percent(progress * -0.24)}, 0, 0) scale(${1 - progress * 0.025})`,
+      opacity: 1 - progress * 0.16,
+    },
+    target: {
+      transform: `translate3d(${percent(1 - progress)}, 0, 0)`,
+    },
+  }),
+});
+
+/**
+ * Back motion reveals the target underneath the source. This is merely a
+ * visual routine; the `back()` action selects retained-history behavior.
+ */
+export const slideRight = defineOriginChoreography({
+  name: "slide-right",
+  effects: ({ progress }) => ({
+    source: {
+      transform: `translate3d(${percent(progress)}, 0, 0)`,
+    },
+    target: {
+      transform: `translate3d(${percent(-0.24 + progress * 0.24)}, 0, 0) scale(${0.975 + progress * 0.025})`,
+      opacity: 0.84 + progress * 0.16,
+    },
+  }),
+});
+
+/**
+ * Cross-fade preset that fades the source out while fading the target in.
+ *
+ * The default release thresholds from the scene are used.
+ */
+export const fade = defineOriginChoreography({
+  name: "fade",
+  effects: ({ progress }) => ({
+    source: { opacity: 1 - progress },
+    target: { opacity: progress },
+  }),
+});
@@ -0,0 +1,35 @@
+<script setup lang="ts">
+import type { OriginGestureProps } from "../gesture/definition";
+import { useOriginGesture } from "../gesture/recognizer";
+
+defineOptions({ name: "OriginGesture", inheritAttrs: false });
+
+const props = withDefaults(defineProps<OriginGestureProps>(), {
+  as: "div",
+});
+
+/*
+ * This convenience component makes the declaration live exactly where the
+ * developer writes it. `useOriginGesture()` is also public for components that
+ * cannot accept an extra wrapper element. A new `gesture` prop applies from
+ * the next pointer-down.
+ */
+const gesture = useOriginGesture(() => props.gesture);
+</script>
+
+<template>
+  <component
+    :is="as"
+    :ref="gesture.ref"
+    v-bind="{ ...$attrs, ...gesture.listeners }"
+    class="nvo-gesture"
+    :style="gesture.style"
+    @pointerdown="gesture.onPointerdown"
+    @pointermove="gesture.onPointermove"
+    @pointerup="gesture.onPointerup"
+    @pointercancel="gesture.onPointercancel"
+    @lostpointercapture="gesture.onLostpointercapture"
+  >
+    <slot />
+  </component>
+</template>
@@ -0,0 +1,34 @@
+<script setup lang="ts">
+import type { OriginGestureSurfaceProps } from "../gesture/definition";
+import { useOriginGestures } from "../gesture/recognizer";
+
+defineOptions({ name: "OriginGestureSurface", inheritAttrs: false });
+
+const props = withDefaults(defineProps<OriginGestureSurfaceProps>(), {
+  as: "div",
+});
+
+/*
+ * All interaction policy belongs to the component that built the definitions.
+ * This convenience host only installs them, combines their browser scrolling
+ * requirements, and forwards a pointer sequence to every recognizer.
+ */
+const surface = useOriginGestures(() => props.gestures);
+</script>
+
+<template>
+  <component
+    :is="as"
+    :ref="surface.ref"
+    v-bind="{ ...$attrs, ...surface.listeners }"
+    class="nvo-gesture"
+    :style="[$attrs.style, surface.style]"
+    @pointerdown="surface.onPointerdown"
+    @pointermove="surface.onPointermove"
+    @pointerup="surface.onPointerup"
+    @pointercancel="surface.onPointercancel"
+    @lostpointercapture="surface.onLostpointercapture"
+  >
+    <slot />
+  </component>
+</template>
@@ -0,0 +1,52 @@
+<script setup lang="ts">
+import { computed, onBeforeUnmount, provide, ref, watchEffect } from "vue";
+import { originNodeScopeKey } from "../scene/scene";
+import type { OriginScene, OriginSceneNode } from "../scene/types";
+
+defineOptions({ name: "OriginNodeHost" });
+
+const props = defineProps<{
+  scene: OriginScene;
+  node: OriginSceneNode;
+}>();
+
+/*
+ * This host is the stable physical home of the view component. It is keyed by
+ * the scene node in OriginScene and never nested under another view. Only its
+ * composed CSS style changes while operation edges are created and collapsed.
+ */
+const host = ref<HTMLElement | null>(null);
+provide(originNodeScopeKey, {
+  scene: props.scene,
+  nodeKey: props.node.key,
+});
+
+watchEffect(() => {
+  props.scene.registerElement(props.node.key, host.value);
+});
+onBeforeUnmount(() => props.scene.registerElement(props.node.key, null));
+
+const style = computed(() => props.scene.styleForNode(props.node.key));
+const interactive = computed(() =>
+  props.scene.isNodeInteractive(props.node.key),
+);
+</script>
+
+<template>
+  <section
+    ref="host"
+    class="nvo-node"
+    :style="style"
+    :data-origin-node="node.key"
+    :data-origin-view="node.view.name ?? node.view.key"
+    :data-origin-state="node.state"
+    :aria-hidden="interactive ? undefined : 'true'"
+    :inert="interactive ? undefined : true"
+  >
+    <!--
+      Vue owns the component lifecycle normally. Adding another origin merely
+      adds effect layers to this host; it does not replace this component VNode.
+    -->
+    <component :is="node.view.component" v-bind="node.view.props" />
+  </section>
+</template>
@@ -0,0 +1,38 @@
+<script setup lang="ts">
+import { onBeforeUnmount, ref, watchEffect } from "vue";
+import type { OriginSceneProps } from "../scene/types";
+import OriginNodeHost from "./OriginNodeHost.vue";
+
+defineOptions({ name: "OriginScene" });
+
+const props = defineProps<OriginSceneProps>();
+
+const root = ref<HTMLElement | null>(null);
+watchEffect(() => props.scene.registerContainer(root.value));
+onBeforeUnmount(() => props.scene.registerContainer(null));
+</script>
+
+<template>
+  <!--
+    All component hosts are siblings. The operation graph is intentionally not
+    mirrored as DOM ancestry because promoting Y after X→Y must not remount Y.
+  -->
+  <main
+    ref="root"
+    class="nvo-scene"
+    :style="{
+      position: 'relative',
+      width: '100%',
+      height: '100%',
+      overflow: 'hidden',
+      isolation: 'isolate',
+    }"
+  >
+    <OriginNodeHost
+      v-for="node in scene.nodes.value"
+      :key="node.key"
+      :scene="scene"
+      :node="node"
+    />
+  </main>
+</template>
@@ -0,0 +1,628 @@
+import type { CSSProperties, MaybeRefOrGetter } from "vue";
+import type { OriginChoreography } from "../choreography";
+import type { OriginNavigationIntent } from "../navigation";
+import type { OriginContext } from "../scene/types";
+import type { OriginRect } from "../shared";
+import { isAtScrollEdge, withinEdge } from "./recognizer";
+
+/*
+ * What a gesture is: the public gesture types, component props, and the
+ * immutable builder that produces executable definitions. Running them is
+ * the recognizer's job.
+ */
+
+/** Direction in which pointer movement advances operation progress. */
+export type OriginGestureDirection = "left" | "right" | "up" | "down";
+
+/** Physical side of the gesture host used to admit pointer-down. */
+export type OriginGestureEdge = "left" | "right" | "top" | "bottom";
+
+/**
+ * CSS length accepted by an edge-based gesture start rule.
+ *
+ * Numbers are interpreted as CSS pixels. Strings may use normal CSS lengths,
+ * percentages, `calc()`, or `clamp()`, and are resolved against the gesture
+ * host when pointer-down occurs.
+ */
+export type OriginGestureDistance = number | string;
+
+/** A pointer position measured in viewport and gesture-host coordinates. */
+export interface OriginGesturePoint {
+  /** Viewport-relative horizontal position. */
+  readonly clientX: number;
+  /** Viewport-relative vertical position. */
+  readonly clientY: number;
+  /** Horizontal position relative to the gesture host's left edge. */
+  readonly localX: number;
+  /** Vertical position relative to the gesture host's top edge. */
+  readonly localY: number;
+}
+
+/** Context supplied to a custom `.from.when()` start predicate. */
+export interface OriginGestureStartContext {
+  /** Native pointer-down event being considered. */
+  readonly event: PointerEvent;
+  /** Component instance from which the gesture would originate. */
+  readonly origin: OriginContext;
+  /** Element carrying the gesture's pointer handlers. */
+  readonly host: HTMLElement;
+  /** Gesture-host bounds captured at pointer-down. */
+  readonly bounds: OriginRect;
+  /** Pointer position at pointer-down. */
+  readonly point: OriginGesturePoint;
+}
+
+/**
+ * Synchronous predicate deciding whether a pointer-down may become a gesture.
+ *
+ * Directional recognition still occurs later, after movement passes the
+ * configured intent threshold.
+ */
+export type OriginGestureStartPredicate = (
+  context: OriginGestureStartContext,
+) => boolean;
+
+/** Start policy stored in a completed gesture definition. */
+export type OriginGestureStart =
+  | {
+      /** Recognize pointer-down anywhere on the host. */
+      readonly kind: "anywhere";
+    }
+  | {
+      /** Recognize pointer-down within a CSS distance of one host side. */
+      readonly kind: "edge";
+      readonly edge: OriginGestureEdge;
+      readonly distance: OriginGestureDistance;
+    }
+  | {
+      /** Recognize pointer-down when application policy returns `true`. */
+      readonly kind: "when";
+      readonly predicate: OriginGestureStartPredicate;
+    }
+  | {
+      /**
+       * Recognize pointer-down while a scroller is at one edge. The gesture
+       * shares its axis with that scroller's native scrolling.
+       */
+      readonly kind: "scroll-edge";
+      readonly scroller: OriginGestureScroller;
+      readonly edge: OriginGestureEdge;
+    };
+
+/** Direction-recognition tuning accepted by `.to.left()` and its siblings. */
+export interface OriginGestureDirectionOptions {
+  /**
+   * Minimum directed movement in CSS pixels before the gesture captures.
+   *
+   * @defaultValue `8`
+   */
+  readonly threshold?: number;
+  /**
+   * Ratio by which directed movement must exceed cross-axis movement.
+   *
+   * @defaultValue `1.15`
+   */
+  readonly axisDominance?: number;
+  /**
+   * Movement that counts as full progress (`1`), resolved at pointer-down.
+   * A CSS length (numbers are pixels, `%` is of the host), or a function
+   * returning pixels, for example to measure a drawer narrower than the host.
+   *
+   * @defaultValue the host's width (horizontal) or height (vertical)
+   */
+  readonly distance?: OriginGestureProgressDistance;
+}
+
+/**
+ * Movement that counts as full progress: a CSS length, or a function that
+ * returns pixels, measured at pointer-down.
+ */
+export type OriginGestureProgressDistance =
+  | OriginGestureDistance
+  | ((context: {
+      readonly host: HTMLElement;
+      readonly bounds: OriginRect;
+    }) => number);
+
+/** Values available when a custom `.complete()` policy runs on pointer-up. */
+export interface OriginGestureCompletionContext {
+  /** Component instance that originated the gesture. */
+  readonly origin: OriginContext;
+  /** Recognized movement direction. */
+  readonly direction: OriginGestureDirection;
+  /** Normalized directed distance, clamped to `0..1`. */
+  readonly progress: number;
+  /** Latest normalized progress units per second. */
+  readonly velocity: number;
+  /** Directed movement from pointer-down in CSS pixels. */
+  readonly distance: number;
+  /** Absolute cross-axis movement from pointer-down in CSS pixels. */
+  readonly crossDistance: number;
+  /** Elapsed time since pointer-down in milliseconds. */
+  readonly duration: number;
+  /** Native pointer-up event that ended the interaction. */
+  readonly event: PointerEvent;
+  /** Element carrying the gesture's pointer handlers. */
+  readonly host: HTMLElement;
+  /** Gesture-host bounds captured at pointer-down. */
+  readonly bounds: OriginRect;
+  /** Pointer position captured at pointer-down. */
+  readonly start: OriginGesturePoint;
+  /** Pointer position at release. */
+  readonly current: OriginGesturePoint;
+}
+
+/** Synchronous commit/cancel policy installed by `.complete()`. */
+export type OriginGestureCompletionPredicate = (
+  context: OriginGestureCompletionContext,
+) => boolean;
+
+/**
+ * Values accepted from a gesture builder's `.navigate()` factory.
+ *
+ * A promise supports lazy view selection. Stale resolutions are discarded if
+ * the pointer has already ended or been cancelled.
+ */
+export type MaybeOriginNavigationIntent =
+  | OriginNavigationIntent
+  | null
+  | undefined
+  | Promise<OriginNavigationIntent | null | undefined>;
+
+/** Factory that resolves navigation after directional recognition succeeds. */
+export type OriginGestureNavigationFactory = (
+  context: OriginContext,
+) => MaybeOriginNavigationIntent;
+
+/**
+ * Immutable, executable result of a complete gesture builder chain.
+ *
+ * Pass this object to {@link useOriginGesture}. An omitted `.from` step is
+ * represented as an `anywhere` start rule.
+ */
+export interface OriginGestureDefinition {
+  /** Identifies a definition produced by the {@link gesture} builder. */
+  readonly kind: "origin-gesture-definition";
+  /** Pointer-down eligibility policy. */
+  readonly start: OriginGestureStart;
+  /** Direction in which movement advances operation progress. */
+  readonly direction: OriginGestureDirection;
+  /** Directional intent recognition tuning. */
+  readonly recognition: Readonly<OriginGestureDirectionOptions>;
+  /**
+   * Optional release decision. When omitted, choreography thresholds decide.
+   */
+  readonly completion?: OriginGestureCompletionPredicate;
+  /** Node-local destination/history resolver. */
+  readonly navigation: OriginGestureNavigationFactory;
+  /** Visual routine paired with the navigation intent. */
+  readonly choreography: OriginChoreography;
+  /** Handlers run, in order, when a release commits. See `.onCommit()`. */
+  readonly commitHandlers?: readonly OriginGestureCommitHandler[];
+  /** Handlers run when a drag starts to qualify to commit. See `.onArm()`. */
+  readonly armHandlers?: readonly OriginGestureCommitHandler[];
+  /** Handlers run when a drag stops qualifying to commit. */
+  readonly disarmHandlers?: readonly OriginGestureCommitHandler[];
+}
+
+/**
+ * Side effect run when a released gesture commits, such as haptic feedback.
+ *
+ * It runs once, synchronously at release, after the commit decision and
+ * before the settling animation. It receives the same context as a
+ * `.complete()` predicate. Errors are reported without interrupting the
+ * operation.
+ */
+export type OriginGestureCommitHandler = (
+  context: OriginGestureCompletionContext,
+) => void;
+
+/** Direction-selection stage shared by `gesture.to` and `.from.*().to`. */
+export interface OriginGestureToBuilder {
+  /** Recognize leftward pointer movement. */
+  left(options?: OriginGestureDirectionOptions): OriginGestureDirectedBuilder;
+  /** Recognize rightward pointer movement. */
+  right(options?: OriginGestureDirectionOptions): OriginGestureDirectedBuilder;
+  /** Recognize upward pointer movement. */
+  up(options?: OriginGestureDirectionOptions): OriginGestureDirectedBuilder;
+  /** Recognize downward pointer movement. */
+  down(options?: OriginGestureDirectionOptions): OriginGestureDirectedBuilder;
+}
+
+/** Stage produced after a `.from` policy has been selected. */
+export interface OriginGestureFromSelection {
+  /** Select the direction that advances this gesture. */
+  readonly to: OriginGestureToBuilder;
+}
+
+/** Optional pointer-down policy exposed at the start of a gesture chain. */
+export interface OriginGestureFromBuilder {
+  /** Admit pointer-down within `distance` of the host's left edge. */
+  left(distance: OriginGestureDistance): OriginGestureFromSelection;
+  /** Admit pointer-down within `distance` of the host's right edge. */
+  right(distance: OriginGestureDistance): OriginGestureFromSelection;
+  /** Admit pointer-down within `distance` of the host's top edge. */
+  top(distance: OriginGestureDistance): OriginGestureFromSelection;
+  /** Admit pointer-down within `distance` of the host's bottom edge. */
+  bottom(distance: OriginGestureDistance): OriginGestureFromSelection;
+  /** Admit pointer-down anywhere on the gesture host. */
+  anywhere(): OriginGestureFromSelection;
+  /** Admit pointer-down when a synchronous application predicate succeeds. */
+  when(predicate: OriginGestureStartPredicate): OriginGestureFromSelection;
+  /**
+   * Admit pointer-down only while `scroller` is scrolled to `edge`, for
+   * example drag-down-to-dismiss only at the top of a list. Movement the
+   * other way is left to the scroller. See {@link atScrollEdge}.
+   */
+  scrollEdge(
+    scroller: OriginGestureScroller,
+    edge: OriginGestureEdge,
+  ): OriginGestureFromSelection;
+}
+
+/**
+ * A scroll container: an element, a ref or getter returning one, or a CSS
+ * selector resolved inside the gesture host.
+ */
+export type OriginGestureScroller =
+  MaybeRefOrGetter<Element | null | undefined> | string;
+
+/** Builder stage after direction is known and completion remains optional. */
+export interface OriginGestureDirectedBuilder {
+  /** Override the choreography's default release decision. */
+  complete(
+    predicate: OriginGestureCompletionPredicate,
+  ): OriginGestureCompletedBuilder;
+  /** Select the target/history mutation while retaining default completion. */
+  navigate(
+    factory: OriginGestureNavigationFactory,
+  ): OriginGestureNavigationBuilder;
+  /** Run `handler` when a release commits. Handlers accumulate in order. */
+  onCommit(handler: OriginGestureCommitHandler): OriginGestureDirectedBuilder;
+  /**
+   * Run `handler` during a drag when releasing would start to commit, for
+   * example for a "release now" haptic. See `.onArm()` in the API reference.
+   */
+  onArm(handler: OriginGestureCommitHandler): OriginGestureDirectedBuilder;
+  /** Run `handler` during a drag when releasing would no longer commit. */
+  onDisarm(handler: OriginGestureCommitHandler): OriginGestureDirectedBuilder;
+}
+
+/** Builder stage after a custom completion policy has been selected. */
+export interface OriginGestureCompletedBuilder {
+  /** Select the target/history mutation performed on commit. */
+  navigate(
+    factory: OriginGestureNavigationFactory,
+  ): OriginGestureNavigationBuilder;
+  /** Run `handler` when a release commits. Handlers accumulate in order. */
+  onCommit(handler: OriginGestureCommitHandler): OriginGestureCompletedBuilder;
+  /**
+   * Run `handler` during a drag when releasing would start to commit, for
+   * example for a "release now" haptic. See `.onArm()` in the API reference.
+   */
+  onArm(handler: OriginGestureCommitHandler): OriginGestureCompletedBuilder;
+  /** Run `handler` during a drag when releasing would no longer commit. */
+  onDisarm(handler: OriginGestureCommitHandler): OriginGestureCompletedBuilder;
+}
+
+/** Final builder stage waiting for visual choreography. */
+export interface OriginGestureNavigationBuilder {
+  /** Attach visual choreography and produce an executable definition. */
+  animate(choreography: OriginChoreography): OriginGestureDefinition;
+  /** Run `handler` when a release commits. Handlers accumulate in order. */
+  onCommit(handler: OriginGestureCommitHandler): OriginGestureNavigationBuilder;
+  /**
+   * Run `handler` during a drag when releasing would start to commit, for
+   * example for a "release now" haptic. See `.onArm()` in the API reference.
+   */
+  onArm(handler: OriginGestureCommitHandler): OriginGestureNavigationBuilder;
+  /** Run `handler` during a drag when releasing would no longer commit. */
+  onDisarm(handler: OriginGestureCommitHandler): OriginGestureNavigationBuilder;
+}
+
+/** Root of the immutable fluent gesture-definition API. */
+export interface OriginGestureBuilder {
+  /** Optionally constrain where pointer-down may begin. */
+  readonly from: OriginGestureFromBuilder;
+  /**
+   * Select movement direction with an implicit `from.anywhere()` start.
+   */
+  readonly to: OriginGestureToBuilder;
+}
+
+/**
+ * DOM bindings returned by {@link useOriginGesture}.
+ *
+ * Attach the pointer handlers to the same `HTMLElement` (and `onTouchmove`
+ * when {@link needsTouchmove} is true), and apply
+ * {@link style}: its `touch-action` keeps native scrolling on every axis no
+ * gesture claims.
+ */
+export interface OriginGestureBinding {
+  /**
+   * Required size and `touch-action` styles for the gesture host. Reading it
+   * inside a render function tracks changes to the gesture definitions.
+   */
+  readonly style: Readonly<CSSProperties>;
+  /** Pointer-down handler that records a potentially eligible gesture. */
+  readonly onPointerdown: (event: PointerEvent) => void;
+  /** Pointer-move handler that recognizes and updates the operation. */
+  readonly onPointermove: (event: PointerEvent) => void;
+  /** Pointer-up handler that commits or cancels using progress and velocity. */
+  readonly onPointerup: (event: PointerEvent) => void;
+  /** Pointer-cancel handler that abandons any captured operation. */
+  readonly onPointercancel: () => void;
+  /**
+   * Lost-capture handler. Cancels a captured gesture whose pointer capture
+   * ends without a pointer-up, so the operation never stays stuck mid-way.
+   */
+  readonly onLostpointercapture: (event: PointerEvent) => void;
+  /**
+   * Touch-move handler for gestures that share an axis with native scrolling
+   * (`.from.scrollEdge()`): it cancels scrolling for a touch such a gesture
+   * claims, and leaves every other touch to the browser. Attach it as a
+   * non-passive listener (Vue's `@touchmove` is), and only when
+   * {@link needsTouchmove} is true.
+   */
+  readonly onTouchmove: (event: TouchEvent) => void;
+  /**
+   * Whether any gesture shares an axis with scrolling, so `onTouchmove` must
+   * be attached. Leave it off otherwise: a non-passive touch listener makes
+   * the browser wait for JavaScript on every touch move, which costs frames.
+   */
+  readonly needsTouchmove: boolean;
+  /**
+   * Extra listeners the host needs, as Vue props: `v-bind` them on the host.
+   * Scroll-edge gestures track their scroller here (a passive scroll
+   * listener), plus `onTouchmove` where the browser lacks directional
+   * `touch-action`. Empty for ordinary gestures.
+   */
+  readonly listeners: Readonly<Record<string, (event: Event) => void>>;
+  /** Function ref for the host element: `:ref="binding.ref"`. */
+  readonly ref: (element: unknown) => void;
+}
+
+// Component props ----------------------------------------------------------
+
+/** Public props accepted by the `OriginGesture` convenience component. */
+export interface OriginGestureProps {
+  /**
+   * Native HTML tag rendered as the gesture host.
+   *
+   * @defaultValue `"div"`
+   */
+  as?: string;
+  /**
+   * Immutable definition produced by the {@link gesture} builder. Replacing
+   * it takes effect from the next pointer-down; a gesture in progress keeps
+   * the definition it started with.
+   */
+  gesture: OriginGestureDefinition;
+}
+
+/** Public props accepted by the multi-definition gesture surface component. */
+export interface OriginGestureSurfaceProps {
+  /**
+   * Native HTML tag rendered as the shared gesture host.
+   *
+   * @defaultValue `"div"`
+   */
+  as?: string;
+  /**
+   * Complete immutable definitions installed on the shared host.
+   *
+   * The surface adds no start, direction, completion, navigation, or animation
+   * policy. Definitions should be created by the owning page component. The
+   * list may change; a gesture in progress keeps the definition it started
+   * with.
+   */
+  gestures: readonly OriginGestureDefinition[];
+}
+
+// Builder ------------------------------------------------------------------
+
+/*
+ * Immutable fluent builder. Each stage is a frozen object holding the choices
+ * made so far in a frozen draft; the final `.animate()` produces a frozen
+ * definition. `.onCommit()` is available at every stage after the direction
+ * and returns the same stage with the handler appended.
+ *
+ *   gesture[.from.<start>].to.<direction>()[.complete()].navigate().animate()
+ */
+
+/** Choices accumulated by the builder before `.animate()`. */
+interface GestureDraft {
+  readonly start: OriginGestureStart;
+  readonly direction: OriginGestureDirection;
+  readonly recognition: Readonly<OriginGestureDirectionOptions>;
+  readonly completion?: OriginGestureCompletionPredicate;
+  readonly commitHandlers: readonly OriginGestureCommitHandler[];
+  readonly armHandlers: readonly OriginGestureCommitHandler[];
+  readonly disarmHandlers: readonly OriginGestureCommitHandler[];
+}
+
+type HandlerList = "commitHandlers" | "armHandlers" | "disarmHandlers";
+
+/**
+ * `.onCommit()`, `.onArm()`, and `.onDisarm()` for a stage: each rebuilds the
+ * same stage from the draft with the handler appended.
+ */
+function hookMethods<Draft extends GestureDraft, Stage>(
+  draft: Draft,
+  stage: (draft: Draft) => Stage,
+) {
+  const append = (list: HandlerList) => (handler: OriginGestureCommitHandler) =>
+    stage(
+      Object.freeze({
+        ...draft,
+        [list]: Object.freeze([...draft[list], handler]),
+      }),
+    );
+  return {
+    onCommit: append("commitHandlers"),
+    onArm: append("armHandlers"),
+    onDisarm: append("disarmHandlers"),
+  };
+}
+
+function navigationStage(
+  draft: GestureDraft & { readonly navigation: OriginGestureNavigationFactory },
+): OriginGestureNavigationBuilder {
+  return Object.freeze({
+    animate: (choreography: OriginChoreography): OriginGestureDefinition =>
+      Object.freeze({
+        kind: "origin-gesture-definition",
+        start: draft.start,
+        direction: draft.direction,
+        recognition: draft.recognition,
+        completion: draft.completion,
+        navigation: draft.navigation,
+        choreography,
+        commitHandlers: draft.commitHandlers,
+        armHandlers: draft.armHandlers,
+        disarmHandlers: draft.disarmHandlers,
+      }),
+    ...hookMethods(draft, navigationStage),
+  });
+}
+
+const navigateFrom =
+  (draft: GestureDraft) => (navigation: OriginGestureNavigationFactory) =>
+    navigationStage(Object.freeze({ ...draft, navigation }));
+
+function completedStage(draft: GestureDraft): OriginGestureCompletedBuilder {
+  return Object.freeze({
+    navigate: navigateFrom(draft),
+    ...hookMethods(draft, completedStage),
+  });
+}
+
+function directedStage(draft: GestureDraft): OriginGestureDirectedBuilder {
+  return Object.freeze({
+    complete: (completion: OriginGestureCompletionPredicate) =>
+      completedStage(Object.freeze({ ...draft, completion })),
+    navigate: navigateFrom(draft),
+    ...hookMethods(draft, directedStage),
+  });
+}
+
+function toStage(start: OriginGestureStart): OriginGestureToBuilder {
+  const direct =
+    (direction: OriginGestureDirection) =>
+    (options: OriginGestureDirectionOptions = {}) =>
+      directedStage(
+        Object.freeze({
+          start,
+          direction,
+          recognition: Object.freeze({ ...options }),
+          commitHandlers: Object.freeze([]),
+          armHandlers: Object.freeze([]),
+          disarmHandlers: Object.freeze([]),
+        }),
+      );
+  return Object.freeze({
+    left: direct("left"),
+    right: direct("right"),
+    up: direct("up"),
+    down: direct("down"),
+  });
+}
+
+function fromStage(start: OriginGestureStart): OriginGestureFromSelection {
+  return Object.freeze({ to: toStage(Object.freeze(start)) });
+}
+
+const fromEdge =
+  (edge: OriginGestureEdge) => (distance: OriginGestureDistance) =>
+    fromStage({ kind: "edge", edge, distance });
+
+const fromBuilder: OriginGestureFromBuilder = Object.freeze({
+  left: fromEdge("left"),
+  right: fromEdge("right"),
+  top: fromEdge("top"),
+  bottom: fromEdge("bottom"),
+  anywhere: () => fromStage({ kind: "anywhere" }),
+  when: (predicate: OriginGestureStartPredicate) =>
+    fromStage({ kind: "when", predicate }),
+  scrollEdge: (scroller: OriginGestureScroller, edge: OriginGestureEdge) =>
+    fromStage({ kind: "scroll-edge", scroller, edge }),
+});
+
+// Start rules ---------------------------------------------------------------
+
+/*
+ * Composable `.from.when()` predicates. Each returns a start predicate, so
+ * they combine with anyOf() and allOf():
+ *
+ *   gesture.from
+ *     .when(anyOf(startedIn(".sheet-handle"), atScrollEdge(list, "top")))
+ *     .to.down()
+ */
+
+/** Admit pointer-down on an element matching `selector`, or inside one. */
+export const startedIn =
+  (selector: string): OriginGestureStartPredicate =>
+  ({ event }) =>
+    event.target instanceof Element && event.target.closest(selector) !== null;
+
+/** Admit pointer-down within `distance` of one side of the gesture host. */
+export const nearEdge =
+  (
+    edge: OriginGestureEdge,
+    distance: OriginGestureDistance,
+  ): OriginGestureStartPredicate =>
+  ({ host, bounds, point }) =>
+    withinEdge(edge, distance, host, bounds, point);
+
+/**
+ * Admit pointer-down while `scroller` is scrolled all the way to `edge`.
+ * A scroller that is missing (not yet mounted) counts as at the edge.
+ */
+export const atScrollEdge =
+  (
+    scroller: OriginGestureScroller,
+    edge: OriginGestureEdge,
+  ): OriginGestureStartPredicate =>
+  ({ host }) =>
+    isAtScrollEdge(scroller, edge, host);
+
+/** Admit pointer-down when any of `predicates` does. */
+export const anyOf =
+  (...predicates: OriginGestureStartPredicate[]): OriginGestureStartPredicate =>
+  (context) =>
+    predicates.some((predicate) => predicate(context));
+
+/** Admit pointer-down only when all of `predicates` do. */
+export const allOf =
+  (...predicates: OriginGestureStartPredicate[]): OriginGestureStartPredicate =>
+  (context) =>
+    predicates.every((predicate) => predicate(context));
+
+/**
+ * Root of the immutable gesture builder.
+ *
+ * `.from` is optional. Starting at `.to` admits pointer-down anywhere on the
+ * bound host, exactly like `.from.anywhere().to`.
+ *
+ * @example Anywhere-to-right back gesture
+ * ```ts
+ * const swipeBack = gesture
+ *   .to.right()
+ *   .navigate((context) => context.canGoBack ? back() : null)
+ *   .animate(slideRight);
+ * ```
+ *
+ * @example Predicate-gated gesture with custom completion
+ * ```ts
+ * const openPanel = gesture
+ *   .from.when(({ point, bounds }) => point.localX <= bounds.width * 0.08)
+ *   .to.down()
+ *   .complete(({ progress, velocity }) => progress > 0.5 || velocity > 1)
+ *   .navigate(() => above(originView(PanelView)))
+ *   .animate(dropPanel);
+ * ```
+ */
+export const gesture: OriginGestureBuilder = Object.freeze({
+  from: fromBuilder,
+  to: toStage(Object.freeze({ kind: "anywhere" })),
+});
@@ -0,0 +1,919 @@
+import {
+  computed,
+  onScopeDispose,
+  shallowRef,
+  toValue,
+  type MaybeRefOrGetter,
+} from "vue";
+import type { OriginAction } from "../navigation";
+import { DEFAULT_COMMIT_THRESHOLD, OriginSceneError } from "../scene/graph";
+import { useOrigin, type UseOrigin } from "../scene/scene";
+import type { OriginContext, OriginOperationHandle } from "../scene/types";
+import { clamp01, measureRect, warn, type OriginRect } from "../shared";
+import type {
+  OriginGestureBinding,
+  OriginGestureDefinition,
+  OriginGestureCompletionContext,
+  OriginGestureDirection,
+  OriginGestureDistance,
+  OriginGestureEdge,
+  OriginGesturePoint,
+  OriginGestureProgressDistance,
+  OriginGestureScroller,
+  OriginGestureStart,
+} from "./definition";
+
+/*
+ * Running gestures: pointer-down admission, movement tracking, and the
+ * recognizer that turns one host's pointer events into a scene operation.
+ */
+
+// Direction ----------------------------------------------------------------
+
+export const isHorizontal = (direction: OriginGestureDirection): boolean => {
+  return direction === "left" || direction === "right";
+};
+
+/** Component of a movement `(dx, dy)` along `direction`. */
+export const directedDistance = (
+  direction: OriginGestureDirection,
+  dx: number,
+  dy: number,
+): number => {
+  switch (direction) {
+    case "left":
+      return -dx;
+    case "right":
+      return dx;
+    case "up":
+      return -dy;
+    case "down":
+      return dy;
+  }
+};
+
+/** Absolute movement perpendicular to `direction`. */
+export const crossDistance = (
+  direction: OriginGestureDirection,
+  dx: number,
+  dy: number,
+): number => {
+  return isHorizontal(direction) ? Math.abs(dy) : Math.abs(dx);
+};
+
+/** Whether a gesture shares its axis with native scrolling. */
+export const sharesScroll = (definition: OriginGestureDefinition): boolean =>
+  definition.start.kind === "scroll-edge";
+
+/**
+ * Whether the browser supports direction-specific `touch-action` values
+ * (`pan-up`, `pan-down`, …). Chromium does; where it is missing (Safari),
+ * scroll-edge gestures fall back to claiming touches from JavaScript.
+ */
+export const supportsDirectionalPan = (): boolean =>
+  typeof CSS !== "undefined" &&
+  typeof CSS.supports === "function" &&
+  CSS.supports("touch-action", "pan-down");
+
+type PanDirection = "left" | "right" | "up" | "down";
+
+/**
+ * The pan a finger moving `direction` would start. A finger moving down pans
+ * the content up (toward its top), which is what pull-to-refresh reserves.
+ */
+const PAN_OF: Record<OriginGestureDirection, PanDirection> = {
+  down: "up",
+  up: "down",
+  left: "right",
+  right: "left",
+};
+
+/**
+ * CSS `touch-action` for a gesture host. The browser keeps every pan that no
+ * gesture needs, so native scrolling never waits for JavaScript:
+ *
+ * - a gesture that owns its axis removes that axis (`pan-y` remains for a
+ *   horizontal gesture);
+ * - a gesture sharing its axis with a scroller (`.from.scrollEdge()`) removes
+ *   only the one pan its finger direction would start, and only while the
+ *   scroller is at its edge (`pan-x pan-down` for drag-down at the top), the
+ *   pull-to-refresh pattern from the Pointer Events specification.
+ *
+ * @param atEdge - Whether a scroll-edge definition's scroller is at its edge.
+ * @param directional - Whether directional pan values are supported; without
+ * them, shared axes stay fully pannable and `onTouchmove` claims touches.
+ */
+export const touchActionFor = (
+  definitions: Iterable<Pick<OriginGestureDefinition, "direction" | "start">>,
+  atEdge: (
+    definition: Pick<OriginGestureDefinition, "start">,
+  ) => boolean = () => false,
+  directional = supportsDirectionalPan(),
+): string => {
+  const pans = new Set<PanDirection>(["left", "right", "up", "down"]);
+  let any = false;
+  for (const definition of definitions) {
+    any = true;
+    if (definition.start.kind === "scroll-edge") {
+      if (directional && atEdge(definition))
+        pans.delete(PAN_OF[definition.direction]);
+      continue;
+    }
+    const pair: PanDirection[] = isHorizontal(definition.direction)
+      ? ["left", "right"]
+      : ["up", "down"];
+    for (const pan of pair) pans.delete(pan);
+  }
+  if (!any) return "auto";
+  if (pans.size === 4) return "manipulation";
+  if (pans.size === 0) return "none";
+  const axis = (a: PanDirection, b: PanDirection, both: string) =>
+    pans.has(a) && pans.has(b)
+      ? [both]
+      : pans.has(a)
+        ? [`pan-${a}`]
+        : pans.has(b)
+          ? [`pan-${b}`]
+          : [];
+  return [
+    ...axis("left", "right", "pan-x"),
+    ...axis("up", "down", "pan-y"),
+  ].join(" ");
+};
+
+// Pointer-down admission ----------------------------------------------------
+
+/*
+ * Pointer-down admission: which events may begin a gesture at all.
+ */
+
+const IGNORED_TARGETS =
+  '[data-origin-gesture="ignore"], input, textarea, select, option, [contenteditable="true"]';
+
+/** Form controls and opted-out subtrees never start gestures. */
+export const isIgnoredTarget = (target: EventTarget | null): boolean => {
+  return (
+    !(target instanceof Element) || Boolean(target.closest(IGNORED_TARGETS))
+  );
+};
+
+export const pointOf = (
+  event: Pick<PointerEvent, "clientX" | "clientY">,
+  bounds: OriginRect,
+): OriginGesturePoint => {
+  return {
+    clientX: event.clientX,
+    clientY: event.clientY,
+    localX: event.clientX - bounds.left,
+    localY: event.clientY - bounds.top,
+  };
+};
+
+const nonNegative = (value: number) =>
+  Number.isFinite(value) ? Math.max(0, value) : 0;
+
+const PIXELS = /^\s*(-?(?:\d+\.?\d*|\.\d+))px\s*$/;
+const PERCENT = /^\s*(-?(?:\d+\.?\d*|\.\d+))%\s*$/;
+
+/**
+ * Resolve a CSS length against a box with the gesture host's size.
+ *
+ * Numbers, pixel lengths, and percentages are computed directly. Anything
+ * else (`rem`, viewport units, `calc()`, `clamp()`) is measured with a
+ * short-lived off-screen box so the browser resolves it exactly. This runs
+ * only during pointer-down for edge-constrained definitions.
+ */
+export const resolveCssDistance = (
+  distance: OriginGestureDistance,
+  axis: "horizontal" | "vertical",
+  host: HTMLElement,
+  bounds: OriginRect,
+): number => {
+  if (typeof distance === "number") return nonNegative(distance);
+  const pixels = PIXELS.exec(distance);
+  if (pixels) return nonNegative(Number(pixels[1]));
+  const percent = PERCENT.exec(distance);
+  if (percent) {
+    const size = axis === "horizontal" ? bounds.width : bounds.height;
+    return nonNegative((Number(percent[1]) / 100) * size);
+  }
+
+  const document = host.ownerDocument;
+  if (!document.body) return Math.max(0, Number.parseFloat(distance) || 0);
+
+  const container = document.createElement("div");
+  const probe = document.createElement("div");
+  Object.assign(container.style, {
+    position: "fixed",
+    left: "-100000px",
+    top: "-100000px",
+    width: `${bounds.width}px`,
+    height: `${bounds.height}px`,
+    visibility: "hidden",
+    pointerEvents: "none",
+    contain: "strict",
+  });
+  Object.assign(probe.style, {
+    position: "absolute",
+    width: axis === "horizontal" ? distance : "0",
+    height: axis === "vertical" ? distance : "0",
+  });
+  container.append(probe);
+  document.body.append(container);
+  const rect = probe.getBoundingClientRect();
+  container.remove();
+  return nonNegative(axis === "horizontal" ? rect.width : rect.height);
+};
+
+/** Whether a pointer-down satisfies a definition's start policy. */
+export const matchesStart = (
+  start: OriginGestureStart,
+  event: PointerEvent,
+  host: HTMLElement,
+  origin: OriginContext,
+  bounds: OriginRect,
+): boolean => {
+  if (start.kind === "anywhere") return true;
+  const point = pointOf(event, bounds);
+  if (start.kind === "when")
+    return start.predicate({ event, origin, host, bounds, point });
+  if (start.kind === "scroll-edge")
+    return isAtScrollEdge(start.scroller, start.edge, host);
+
+  return withinEdge(start.edge, start.distance, host, bounds, point);
+};
+
+/**
+ * Whether `scroller` is scrolled all the way to `edge`. A scroller that is
+ * missing (not yet mounted) counts as at the edge.
+ */
+export const isAtScrollEdge = (
+  scroller: OriginGestureScroller,
+  edge: OriginGestureEdge,
+  host: HTMLElement,
+): boolean => {
+  const element =
+    typeof scroller === "string"
+      ? host.querySelector(scroller)
+      : toValue(scroller);
+  if (!element) return true;
+  const { scrollTop, scrollLeft, scrollHeight, scrollWidth } = element;
+  const { clientHeight, clientWidth } = element;
+  switch (edge) {
+    case "top":
+      return scrollTop <= 0;
+    case "bottom":
+      return scrollTop + clientHeight >= scrollHeight - 1;
+    case "left":
+      return scrollLeft <= 0;
+    case "right":
+      return scrollLeft + clientWidth >= scrollWidth - 1;
+  }
+};
+
+/** Whether `point` lies within `distance` of one side of the host. */
+export const withinEdge = (
+  edge: OriginGestureEdge,
+  distance: OriginGestureDistance,
+  host: HTMLElement,
+  bounds: OriginRect,
+  point: OriginGesturePoint,
+): boolean => {
+  const horizontal = edge === "left" || edge === "right";
+  const limit = resolveCssDistance(
+    distance,
+    horizontal ? "horizontal" : "vertical",
+    host,
+    bounds,
+  );
+  switch (edge) {
+    case "left":
+      return point.localX >= 0 && point.localX <= limit;
+    case "right":
+      return (
+        point.localX <= bounds.width && bounds.width - point.localX <= limit
+      );
+    case "top":
+      return point.localY >= 0 && point.localY <= limit;
+    case "bottom":
+      return (
+        point.localY <= bounds.height && bounds.height - point.localY <= limit
+      );
+  }
+};
+
+// Movement tracking ---------------------------------------------------------
+
+type PointerSample = Pick<PointerEvent, "clientX" | "clientY" | "timeStamp">;
+
+/** Velocity is the trend of the samples in this many recent milliseconds. */
+const VELOCITY_WINDOW = 100;
+/** Shortest span, in ms, velocity is measured over, so bursts stay finite. */
+const MIN_VELOCITY_SPAN = 8;
+
+/**
+ * Measures one pointer sequence's movement along a gesture direction.
+ *
+ * Progress and velocity are normalized by the gesture distance (by default
+ * the host's size along the gesture axis), so `1` means one full distance.
+ */
+export class DirectionalTracker {
+  /** Directed distance from the start, in CSS pixels. */
+  distance = 0;
+  /** Absolute cross-axis distance from the start, in CSS pixels. */
+  crossDistance = 0;
+  /** Directed distance ÷ gesture distance, unclamped so it can overshoot. */
+  rawProgress = 0;
+  /**
+   * Directed velocity in progress units per second: the least-squares trend
+   * of the last {@link VELOCITY_WINDOW} ms, so uneven sample timing and a
+   * final held-still moment do not distort a flick.
+   */
+  velocity = 0;
+
+  private readonly samples: { time: number; position: number }[];
+
+  constructor(
+    private readonly direction: OriginGestureDirection,
+    private readonly start: PointerSample,
+    /** Gesture distance in CSS pixels, read at every sample. */
+    private readonly axisSize: () => number,
+  ) {
+    this.samples = [{ time: start.timeStamp, position: 0 }];
+  }
+
+  /** Directed distance ÷ gesture distance, clamped to `0..1`. */
+  get progress(): number {
+    return clamp01(this.rawProgress);
+  }
+
+  /** Movement from the start without recording a sample. */
+  displacement(event: Pick<PointerSample, "clientX" | "clientY">) {
+    const dx = event.clientX - this.start.clientX;
+    const dy = event.clientY - this.start.clientY;
+    return {
+      distance: directedDistance(this.direction, dx, dy),
+      crossDistance: crossDistance(this.direction, dx, dy),
+    };
+  }
+
+  /** Record a sample, updating distance, progress, and velocity. */
+  sample(event: PointerSample): void {
+    const { distance, crossDistance } = this.displacement(event);
+    this.distance = distance;
+    this.crossDistance = crossDistance;
+    const size = Math.max(1, this.axisSize());
+    this.rawProgress = distance / size;
+
+    const samples = this.samples;
+    samples.push({ time: event.timeStamp, position: distance });
+    // Keep the window, but always at least two samples to measure between.
+    const since = event.timeStamp - VELOCITY_WINDOW;
+    while (samples.length > 2 && samples[1]!.time <= since) samples.shift();
+    this.velocity = (DirectionalTracker.trend(samples) * 1000) / size;
+  }
+
+  /** Least-squares slope of position over time, in pixels per ms. */
+  private static trend(samples: readonly { time: number; position: number }[]) {
+    const first = samples[0]!;
+    const last = samples[samples.length - 1]!;
+    if (last.time - first.time < MIN_VELOCITY_SPAN)
+      return (last.position - first.position) / MIN_VELOCITY_SPAN;
+    const meanTime =
+      samples.reduce((sum, { time }) => sum + time, 0) / samples.length;
+    const meanPosition =
+      samples.reduce((sum, { position }) => sum + position, 0) / samples.length;
+    let covariance = 0;
+    let variance = 0;
+    for (const { time, position } of samples) {
+      covariance += (time - meanTime) * (position - meanPosition);
+      variance += (time - meanTime) ** 2;
+    }
+    return covariance / variance;
+  }
+}
+
+// Recognizer ----------------------------------------------------------------
+
+/** Directed movement in CSS pixels required before a gesture captures. */
+const DEFAULT_THRESHOLD = 8;
+/** Ratio by which directed movement must exceed cross-axis movement. */
+const DEFAULT_AXIS_DOMINANCE = 1.15;
+
+/** Resolve a definition's progress distance at pointer-down, in pixels. */
+export const resolveProgressDistance = (
+  distance: OriginGestureProgressDistance | undefined,
+  direction: OriginGestureDirection,
+  host: HTMLElement,
+  bounds: OriginRect,
+): (() => number) => {
+  const horizontal = isHorizontal(direction);
+  if (distance === undefined)
+    return () => (horizontal ? host.clientWidth : host.clientHeight);
+  const pixels =
+    typeof distance === "function"
+      ? distance({ host, bounds })
+      : resolveCssDistance(
+          distance,
+          horizontal ? "horizontal" : "vertical",
+          host,
+          bounds,
+        );
+  return () => pixels;
+};
+
+/** The origin capabilities a recognizer needs. */
+export type RecognizerOrigin = Pick<UseOrigin, "context" | "begin">;
+
+/** State of one admitted pointer sequence, from pointer-down to release. */
+interface PointerSession {
+  /** Definition current at pointer-down; later changes do not affect it. */
+  readonly definition: OriginGestureDefinition;
+  readonly pointerId: number;
+  readonly host: HTMLElement;
+  readonly bounds: OriginRect;
+  /** Origin context captured at pointer-down. */
+  readonly origin: OriginContext;
+  readonly start: OriginGesturePoint;
+  readonly startTime: number;
+  readonly tracker: DirectionalTracker;
+  /**
+   * For a gesture sharing its axis with scrolling: whether it has claimed
+   * this touch from native scrolling (`ours`) or not yet decided.
+   */
+  scroll: "pending" | "ours";
+  /** Latest pointer position, for the touch-move decision. */
+  last: { readonly clientX: number; readonly clientY: number };
+  /** Movement passed the recognition threshold and the pointer is captured. */
+  captured: boolean;
+  /** Releasing now would commit; drives `.onArm()` and `.onDisarm()`. */
+  armed: boolean;
+  /** The scene operation, once navigation resolved and `begin()` was called. */
+  operation: Promise<OriginOperationHandle | null> | null;
+  /**
+   * The operation's handle once `begin()` resolved, so pointer-up can finish
+   * it synchronously, inside the event, without awaiting the promise.
+   */
+  handle: OriginOperationHandle | null;
+}
+
+/**
+ * Turns one host's pointer events into a scene operation.
+ *
+ * Lifecycle of a session:
+ *
+ * 1. **down**: an eligible primary pointer opens a session.
+ * 2. **move**: once directed movement passes the threshold, the pointer is
+ *    captured and `.navigate()` is resolved; a non-null intent begins an
+ *    operation, while a declined one closes the session. Every later move
+ *    updates the operation's progress.
+ * 3. **up**: the session closes and the operation finishes, using the
+ *    definition's `.complete()` predicate when present.
+ * 4. **cancel**: pointer-cancel, lost pointer capture, a new primary
+ *    pointer-down, or disposal closes the session and cancels its operation.
+ *
+ * Navigation and `begin()` are asynchronous. Each continuation checks that
+ * its session is still current, so a stale resolution never creates or
+ * updates an orphan operation.
+ */
+export class GestureRecognizer {
+  private session: PointerSession | null = null;
+
+  constructor(
+    /** Reads the current definition; it may change between sessions. */
+    private readonly definitionOf: () => OriginGestureDefinition,
+    private readonly origin: RecognizerOrigin,
+  ) {}
+
+  /**
+   * Called for each `touchmove`: whether native scrolling must be cancelled.
+   *
+   * Only gestures that share an axis with scrolling take part. The browser
+   * sends its first cancelable `touchmove` after roughly 15–20px of movement,
+   * so the decision uses all of that movement: along this gesture's axis and
+   * direction claims the touch; clearly elsewhere lets it go to the browser
+   * (which then scrolls and sends `pointercancel`); unclear holds it for one
+   * more move.
+   */
+  claimTouch(): boolean {
+    const session = this.session;
+    if (!session || !sharesScroll(session.definition)) return false;
+    if (session.captured || session.scroll === "ours") return true;
+    const { distance, crossDistance } = session.tracker.displacement(
+      session.last,
+    );
+    const dominance =
+      session.definition.recognition.axisDominance ?? DEFAULT_AXIS_DOMINANCE;
+    const along = Math.abs(distance);
+    if (distance > 0 && along >= crossDistance * dominance) {
+      session.scroll = "ours";
+      return true;
+    }
+    if (
+      along >= crossDistance * dominance ||
+      crossDistance >= along * dominance
+    ) {
+      this.session = null;
+      return false;
+    }
+    return true;
+  }
+
+  pointerDown(event: PointerEvent): void {
+    if (!event.isPrimary) return;
+    // Only one primary pointer exists at a time, so any session still open
+    // lost its pointer-up (for example, released outside the window).
+    void this.abandon();
+
+    const host = event.currentTarget;
+    if (
+      event.button !== 0 ||
+      !(host instanceof HTMLElement) ||
+      isIgnoredTarget(event.target)
+    )
+      return;
+
+    const definition = this.definitionOf();
+    const bounds = measureRect(host);
+    const origin = this.origin.context.value;
+    if (!matchesStart(definition.start, event, host, origin, bounds)) return;
+
+    // The component containing this declaration is the operation's origin.
+    event.stopPropagation();
+    this.session = {
+      definition,
+      pointerId: event.pointerId,
+      host,
+      bounds,
+      origin,
+      start: pointOf(event, bounds),
+      startTime: event.timeStamp,
+      tracker: new DirectionalTracker(
+        definition.direction,
+        event,
+        resolveProgressDistance(
+          definition.recognition.distance,
+          definition.direction,
+          host,
+          bounds,
+        ),
+      ),
+      scroll: "pending",
+      last: { clientX: event.clientX, clientY: event.clientY },
+      captured: false,
+      armed: false,
+      operation: null,
+      handle: null,
+    };
+  }
+
+  async pointerMove(event: PointerEvent): Promise<void> {
+    const session = this.sessionFor(event);
+    if (!session) return;
+
+    session.last = { clientX: event.clientX, clientY: event.clientY };
+    if (!session.captured) {
+      if (!GestureRecognizer.recognizes(session, event)) return;
+      session.captured = true;
+      session.host.setPointerCapture?.(session.pointerId);
+      event.preventDefault();
+      session.tracker.sample(event);
+      this.updateArming(session, event);
+      const action = await this.resolveAction(session.definition);
+      // The pointer may have been released or cancelled meanwhile.
+      if (this.session !== session) return;
+      if (!action) {
+        this.session = null;
+        return;
+      }
+      session.operation = this.origin.begin(action).then(
+        (handle) => (session.handle = handle),
+        (error) => {
+          // Another recognizer on this origin won the race; that is expected.
+          if (!(
+            error instanceof OriginSceneError && error.code === "origin-busy"
+          ))
+            warn("A gesture could not begin its operation.", error);
+          return null;
+        },
+      );
+    } else {
+      event.preventDefault();
+      session.tracker.sample(event);
+      this.updateArming(session, event);
+    }
+
+    // Progress is read after the await so the latest buffered sample wins.
+    const pending = session.operation;
+    const handle = pending ? await pending : null;
+    if (this.session === session && session.operation === pending)
+      handle?.update(session.tracker.rawProgress, session.tracker.velocity);
+  }
+
+  async pointerUp(event: PointerEvent): Promise<void> {
+    const session = this.sessionFor(event);
+    if (!session) return;
+    this.session = null;
+    if (!session.captured) return;
+
+    const { tracker, definition } = session;
+    tracker.sample(event);
+    const context = GestureRecognizer.contextOf(session, event);
+    const commit = definition.completion?.(context);
+    const { rawProgress: progress, velocity } = tracker;
+
+    // Usually the operation began long ago: finish it without awaiting, so
+    // commit handlers run inside this pointer-up (iOS only allows haptics,
+    // audio, and clipboard writes during the user's gesture).
+    const handle =
+      session.handle ?? (session.operation ? await session.operation : null);
+    if (!handle) return;
+    handle.update(progress, velocity);
+    // finish() fixes the outcome synchronously, before the spring settles.
+    const settled = handle.finish(
+      commit === undefined ? undefined : { commit },
+    );
+    if (handle.intent === "commit")
+      GestureRecognizer.notify(definition.commitHandlers ?? [], context);
+    await settled;
+  }
+
+  /**
+   * The host lost pointer capture without a pointer-up; cancel like
+   * pointer-cancel. The event bubbles, and taking capture makes the touched
+   * child lose its implicit touch capture, so only the host's own loss counts.
+   */
+  pointerCaptureLost(event: PointerEvent): Promise<void> {
+    const session = this.sessionFor(event);
+    return session && event.target === session.host
+      ? this.abandon()
+      : Promise.resolve();
+  }
+
+  pointerCancel(): Promise<void> {
+    return this.abandon();
+  }
+
+  /** Close the current session, cancelling its operation if captured. */
+  async abandon(): Promise<void> {
+    const session = this.session;
+    this.session = null;
+    if (!session?.captured) return;
+    const handle = session.operation ? await session.operation : null;
+    await handle?.cancel();
+  }
+
+  /** Fire `.onArm()` / `.onDisarm()` when the release decision would flip. */
+  private updateArming(session: PointerSession, event: PointerEvent) {
+    const { definition, tracker } = session;
+    const armHandlers = definition.armHandlers ?? [];
+    const disarmHandlers = definition.disarmHandlers ?? [];
+    if (!armHandlers.length && !disarmHandlers.length) return;
+    const context = GestureRecognizer.contextOf(session, event);
+    // Distance decides arming unless the definition supplies .complete():
+    // velocity changes too quickly to drive a cue without flickering.
+    const armed = definition.completion
+      ? definition.completion(context)
+      : tracker.progress >=
+        (definition.choreography.commitThreshold ?? DEFAULT_COMMIT_THRESHOLD);
+    if (armed === session.armed) return;
+    session.armed = armed;
+    GestureRecognizer.notify(armed ? armHandlers : disarmHandlers, context);
+  }
+
+  private static contextOf(
+    session: PointerSession,
+    event: PointerEvent,
+  ): OriginGestureCompletionContext {
+    const { tracker } = session;
+    return {
+      origin: session.origin,
+      direction: session.definition.direction,
+      progress: tracker.progress,
+      velocity: tracker.velocity,
+      distance: tracker.distance,
+      crossDistance: tracker.crossDistance,
+      duration: Math.max(0, event.timeStamp - session.startTime),
+      event,
+      host: session.host,
+      bounds: session.bounds,
+      start: session.start,
+      current: pointOf(event, session.bounds),
+    };
+  }
+
+  private sessionFor(event: PointerEvent) {
+    const session = this.session;
+    return session && session.pointerId === event.pointerId ? session : null;
+  }
+
+  /** Directed movement passed the threshold and dominates the cross axis. */
+  private static recognizes(session: PointerSession, event: PointerEvent) {
+    const { recognition } = session.definition;
+    const { distance, crossDistance } = session.tracker.displacement(event);
+    return (
+      distance >= (recognition.threshold ?? DEFAULT_THRESHOLD) &&
+      distance >=
+        crossDistance * (recognition.axisDominance ?? DEFAULT_AXIS_DOMINANCE)
+    );
+  }
+
+  /**
+   * Resolve the definition's navigation against the origin's current context
+   * and pair it with its choreography. A declined navigation resolves to
+   * `null`; a failing one also warns.
+   */
+  private resolveAction(
+    definition: OriginGestureDefinition,
+  ): Promise<OriginAction | null> {
+    const fail = (error: unknown) => {
+      warn("A gesture's navigate() factory failed.", error);
+      return null;
+    };
+    try {
+      return Promise.resolve(
+        definition.navigation(this.origin.context.value),
+      ).then(
+        (navigation) =>
+          navigation
+            ? { ...navigation, choreography: definition.choreography }
+            : null,
+        fail,
+      );
+    } catch (error) {
+      return Promise.resolve(fail(error));
+    }
+  }
+
+  /** Run handlers in order; a failing handler never interrupts the others. */
+  private static notify(
+    handlers: readonly ((context: OriginGestureCompletionContext) => void)[],
+    context: OriginGestureCompletionContext,
+  ) {
+    for (const handler of handlers) {
+      try {
+        handler(context);
+      } catch (error) {
+        queueMicrotask(() => {
+          throw error;
+        });
+      }
+    }
+  }
+}
+
+// Composables ---------------------------------------------------------------
+
+/**
+ * Bind any number of definitions to one host. Recognizers are kept per list
+ * position, so re-rendering with new definition objects never interrupts a
+ * gesture in progress; each change applies from the next pointer-down.
+ */
+export const useOriginGestures = (
+  definitions: MaybeRefOrGetter<readonly OriginGestureDefinition[]>,
+): OriginGestureBinding => {
+  const origin = useOrigin();
+  const recognizers: GestureRecognizer[] = [];
+
+  /** Grow or shrink the recognizer list to match the current definitions. */
+  const current = () => {
+    const count = toValue(definitions).length;
+    while (recognizers.length < count) {
+      const index = recognizers.length;
+      recognizers.push(
+        new GestureRecognizer(() => toValue(definitions)[index]!, origin),
+      );
+    }
+    for (const removed of recognizers.splice(count)) void removed.abandon();
+    return recognizers;
+  };
+
+  // The host element, for scroll-edge state and selector scrollers.
+  const host = shallowRef<HTMLElement | null>(null);
+  // Bumped by scroll events; touch-action re-reads scroll edges on change.
+  const scrolled = shallowRef(0);
+  const directional = supportsDirectionalPan();
+  const atEdge = (definition: Pick<OriginGestureDefinition, "start">) => {
+    const { start } = definition;
+    if (start.kind !== "scroll-edge") return false;
+    const element = host.value;
+    if (!element && typeof start.scroller === "string") return true;
+    return isAtScrollEdge(start.scroller, start.edge, element!);
+  };
+  // A string, so hosts re-render only when touch-action actually changes,
+  // never merely because something scrolled.
+  const touchAction = computed(() => {
+    void scrolled.value;
+    return touchActionFor(toValue(definitions), atEdge, directional);
+  });
+  const sharesScrollAxis = computed(() =>
+    toValue(definitions).some(sharesScroll),
+  );
+
+  const style = computed(() => {
+    const value = touchAction.value;
+    return {
+      width: "100%",
+      height: "100%",
+      // Native scrolling stays on every pan no gesture needs.
+      touchAction: value,
+      // Inherited by descendants through the package stylesheet, so nested
+      // scroll containers (where browsers restart touch-action) keep it too.
+      "--nvo-touch-action": value,
+    };
+  });
+
+  // A recognizer whose component unmounts mid-gesture cancels its operation.
+  onScopeDispose(() => {
+    for (const recognizer of recognizers.splice(0)) void recognizer.abandon();
+  });
+
+  // Only without directional touch-action do scroll-edge gestures need to
+  // claim touches from JavaScript, the one path that blocks scrolling.
+  const needsTouchmove = computed(() => sharesScrollAxis.value && !directional);
+
+  const onTouchmove = (event: TouchEvent) => {
+    if (!event.cancelable) return;
+    // Ask every recognizer: each one may let go of the touch as it answers.
+    let claimed = false;
+    for (const recognizer of current())
+      if (recognizer.claimTouch()) claimed = true;
+    if (claimed) event.preventDefault();
+  };
+  const onScrollCapture = () => {
+    scrolled.value += 1;
+  };
+  const listeners = computed(() => ({
+    ...(sharesScrollAxis.value ? { onScrollCapture } : {}),
+    ...(needsTouchmove.value ? { onTouchmove } : {}),
+  }));
+
+  return {
+    get style() {
+      return style.value;
+    },
+    get needsTouchmove() {
+      return needsTouchmove.value;
+    },
+    get listeners() {
+      return listeners.value as Record<string, (event: Event) => void>;
+    },
+    ref: (element) => {
+      host.value = element instanceof HTMLElement ? element : null;
+      scrolled.value += 1;
+    },
+    onPointerdown: (event) => {
+      for (const recognizer of current()) recognizer.pointerDown(event);
+    },
+    onPointermove: (event) => {
+      for (const recognizer of current()) void recognizer.pointerMove(event);
+    },
+    onPointerup: (event) => {
+      for (const recognizer of current()) void recognizer.pointerUp(event);
+    },
+    onPointercancel: () => {
+      for (const recognizer of current()) void recognizer.pointerCancel();
+    },
+    onLostpointercapture: (event) => {
+      for (const recognizer of current())
+        void recognizer.pointerCaptureLost(event);
+    },
+    onTouchmove,
+  };
+};
+
+/**
+ * Install a component-owned pointer recognizer.
+ *
+ * Recognition is local to the element receiving these handlers. There is no
+ * application-wide gesture table and no lookup of a currently active view.
+ *
+ * Builder definitions may independently describe their pointer-down region
+ * and movement direction. Omitting `.from` recognizes pointer-down across the
+ * whole element.
+ *
+ * Interactive controls and anything inside
+ * `[data-origin-gesture="ignore"]` are ignored automatically. The recognizer
+ * preserves native scrolling on the cross-axis through its returned style.
+ *
+ * @param definition - An immutable builder result, or a ref or getter
+ * returning one. A changed definition applies from the next pointer-down.
+ * @returns Pointer handlers and required host styles.
+ * @throws If called outside a component rendered by `OriginScene`.
+ *
+ * @example Builder-defined backward gesture
+ * ```ts
+ * const swipeBack = useOriginGesture(
+ *   gesture
+ *     .from.left("32px")
+ *     .to.right()
+ *     .navigate((context) => context.canGoBack ? back() : null)
+ *     .animate(slideRight),
+ * );
+ * ```
+ */
+export function useOriginGesture(
+  definition: MaybeRefOrGetter<OriginGestureDefinition>,
+): OriginGestureBinding {
+  return useOriginGestures(() => [toValue(definition)]);
+}
@@ -0,0 +1,93 @@
+/**
+ * Routeless, component-owned scene transitions and gesture recognition for Vue.
+ *
+ * The package renders flat, stable Vue component hosts and composes temporary
+ * origin-relative operation frames. It does not depend on Vue Router or choose
+ * a globally active view.
+ *
+ * Modules, from the bottom up:
+ *
+ * - `shared`             geometry and environment helpers
+ * - `choreography`       visual effects, presets, and effect compositing
+ * - `navigation`         view recipes, intents, and actions (`forward`, …)
+ * - `scene/graph`        the scene model and its history rules
+ * - `scene/scene`        timing, measuring, compositing, `useOrigin`
+ * - `gesture/definition` gesture types and the immutable builder
+ * - `gesture/recognizer` pointer admission, tracking, and recognition
+ * - `components/`        Vue renderers and gesture hosts
+ *
+ * @packageDocumentation
+ */
+
+export type { OriginRect } from "./shared";
+
+export type {
+  OriginChoreography,
+  OriginChoreographyContext,
+  OriginEffect,
+  OriginEffectSet,
+  OriginOperationIntent,
+  OriginOperationPhase,
+  OriginSpring,
+} from "./choreography";
+export {
+  defineOriginChoreography,
+  fade,
+  normalizedEffect,
+  slideLeft,
+  slideRight,
+} from "./choreography";
+
+export type * from "./navigation";
+export {
+  above,
+  back,
+  forward,
+  originAction,
+  originView,
+  replace,
+  under,
+} from "./navigation";
+
+export type * from "./scene/types";
+export type { OriginNodeScope, UseOrigin } from "./scene/scene";
+export { OriginSceneError, type OriginSceneErrorCode } from "./scene/graph";
+export {
+  createOriginScene,
+  originNodeScopeKey,
+  useOrigin,
+} from "./scene/scene";
+
+export type * from "./gesture/definition";
+export {
+  allOf,
+  anyOf,
+  atScrollEdge,
+  gesture,
+  nearEdge,
+  startedIn,
+} from "./gesture/definition";
+export { useOriginGesture } from "./gesture/recognizer";
+
+/**
+ * Convenience component that binds one `useOriginGesture()` recognizer to a
+ * rendered HTML element. See `OriginGestureProps` for its public props.
+ */
+export { default as OriginGesture } from "./components/OriginGesture.vue";
+
+/**
+ * Policy-neutral host for multiple completed gesture definitions. The owning
+ * page builds each definition; this component only installs their recognizers
+ * and forwards pointer events across the shared surface.
+ */
+export { default as OriginGestureSurface } from "./components/OriginGestureSurface.vue";
+
+/**
+ * Renderer for an `OriginScene`. Every live view is mounted as a stable,
+ * absolutely positioned sibling beneath this component.
+ */
+export { default as OriginScene } from "./components/OriginScene.vue";
+
+// Makes the library build emit dist/style.css. Applications should import the
+// explicit `@native-vue-router/core-v2/style.css` export as shown in the README.
+import "./style.css";
@@ -0,0 +1,434 @@
+import { markRaw, type Component } from "vue";
+import { isChoreography, type OriginChoreography } from "./choreography";
+
+/*
+ * Navigation vocabulary: view recipes (what to mount) and the intents and
+ * actions (how history changes) that operations execute.
+ */
+
+/** Props accepted by a Vue component definition. */
+export type PropsOf<T> = T extends abstract new (...args: any[]) => {
+  $props: infer P;
+}
+  ? P
+  : T extends (props: infer P, ...args: any[]) => any
+    ? P
+    : never;
+
+/**
+ * A view is a recipe for creating a Vue component, not a mounted instance.
+ *
+ * Forward navigation uses the recipe to create a mounted history entry. That
+ * instance remains mounted until a committed back operation pops it.
+ *
+ * @typeParam T - The component mounted by the recipe.
+ */
+export interface OriginView<T extends Component = Component> {
+  /** The Vue component definition that will be mounted for this recipe. */
+  readonly component: T;
+  /** Props passed to the component when the recipe is mounted. */
+  readonly props?: Readonly<PropsOf<T>>;
+  /**
+   * A developer-facing recipe identity used in diagnostics and as the prefix
+   * of generated scene-node keys. It does not make Vue reuse an instance.
+   */
+  readonly key?: string;
+  /** A human-readable label used by diagnostics and DOM data attributes. */
+  readonly name?: string;
+}
+
+/** Optional developer-facing metadata for an {@link OriginView} recipe. */
+export interface OriginViewOptions {
+  /**
+   * Stable recipe identity used in diagnostics and generated node-key prefixes.
+   * It does not preserve or reuse a mounted Vue component instance.
+   */
+  key?: string;
+  /** Human-readable label used by inspectors and DOM data attributes. */
+  name?: string;
+}
+
+let viewSequence = 0;
+
+function componentName(component: Component): string | undefined {
+  return typeof component === "object" && "name" in component
+    ? String(component.name)
+    : undefined;
+}
+
+/**
+ * Turn a component and props into a lightweight, reusable view recipe.
+ *
+ * Components are marked raw so Vue never attempts to proxy their definitions
+ * when recipes are placed in reactive scene/history structures.
+ *
+ * @param component - Vue component definition to mount.
+ * @param props - Props captured by the recipe.
+ * @param options - Optional recipe identity and diagnostic name.
+ * @returns An immutable, reusable component recipe. It is not a Vue instance.
+ *
+ * @example
+ * ```ts
+ * const profile = originView(
+ *   ProfileView,
+ *   { userId: "42" },
+ *   { key: "profile-42", name: "Profile" },
+ * );
+ * ```
+ */
+export function originView<T extends Component = Component>(
+  component: T,
+  props?: PropsOf<T>,
+  options: OriginViewOptions = {},
+): OriginView<T> {
+  const name = options.name ?? componentName(component);
+  return markRaw({
+    component: markRaw(component),
+    props,
+    key: options.key ?? `${name ?? "view"}-${++viewSequence}`,
+    name,
+  });
+}
+
+/**
+ * Controls how an operation participates in retained instance history.
+ *
+ * - `push`: create a target whose previous entry is the mounted origin.
+ * - `replace`: create a target that inherits the origin's previous entry, then
+ *   remove the origin on commit.
+ * - `back`: reuse the mounted previous entry and pop the origin on commit.
+ */
+export type OriginHistoryMode = "push" | "replace" | "back";
+
+/**
+ * The target's stacking relationship to its origin while an operation exists.
+ */
+export type OriginPlacement = "above" | "under";
+
+/**
+ * A scene mutation without visual choreography.
+ *
+ * Gesture builders keep navigation intent separate from animation so the same
+ * destination can be paired with different component-local interactions.
+ * Calling `.animate()` materializes this intent as an {@link OriginAction}.
+ */
+export interface OriginNavigationIntent {
+  /**
+   * Recipe for a newly created push or replacement target. Back navigation
+   * omits this because the scene resolves the retained previous instance.
+   */
+  readonly target?: OriginView;
+  /** Target stacking relationship while the gesture operation is visible. */
+  readonly placement?: OriginPlacement;
+  /** Retained-history mutation performed if the gesture commits. */
+  readonly history: OriginHistoryMode;
+}
+
+/** A complete request to create and animate a target view from an origin. */
+export interface OriginAction {
+  /**
+   * Recipe for a newly created push or replacement target. A back action omits
+   * this because the scene resolves its already-mounted previous entry.
+   */
+  readonly target?: OriginView;
+  /** Visual relationship applied to the source, target, and shared frame. */
+  readonly choreography: OriginChoreography;
+  /**
+   * Target stacking relationship during the operation.
+   *
+   * @defaultValue `"above"`
+   */
+  readonly placement?: OriginPlacement;
+  /**
+   * History mutation applied to the target recipe.
+   *
+   * @defaultValue `"push"`
+   */
+  readonly history?: OriginHistoryMode;
+}
+
+/** Options accepted by {@link originAction}. */
+export interface OriginActionOptions {
+  /**
+   * Target stacking relationship during the operation.
+   *
+   * @defaultValue `"above"`
+   */
+  placement?: OriginPlacement;
+  /**
+   * History mutation assigned to the created target node.
+   *
+   * @defaultValue `"push"`
+   */
+  history?: OriginHistoryMode;
+}
+
+/** History options shared by the {@link above} and {@link under} helpers. */
+export interface OriginPlacementActionOptions {
+  /**
+   * History mutation assigned to the created target node.
+   *
+   * @defaultValue `"push"`
+   */
+  history?: OriginHistoryMode;
+}
+
+/** Stacking options accepted by retained-history navigation helpers. */
+export interface OriginNavigationActionOptions {
+  /**
+   * Target stacking relationship during the operation.
+   *
+   * @defaultValue `"above"` for {@link forward} and {@link replace}, `"under"`
+   * for {@link back}
+   */
+  placement?: OriginPlacement;
+}
+
+/*
+ * Every helper accepts either `(…, options?)`, producing an animation-free
+ * navigation intent for gesture `.navigate()`, or `(…, choreography,
+ * options?)`, producing a complete action for `begin()`/`perform()`.
+ */
+
+interface HelperArguments<Options> {
+  readonly choreography?: OriginChoreography;
+  readonly options: Options;
+}
+
+function helperArguments<Options extends object>(
+  choreographyOrOptions: OriginChoreography | Options | undefined,
+  options: Options | undefined,
+): HelperArguments<Partial<Options>> {
+  return isChoreography(choreographyOrOptions)
+    ? { choreography: choreographyOrOptions, options: options ?? {} }
+    : { options: choreographyOrOptions ?? {} };
+}
+
+function navigation(
+  target: OriginView | undefined,
+  placement: OriginPlacement,
+  history: OriginHistoryMode,
+): OriginNavigationIntent {
+  return { target, placement, history };
+}
+
+/** Back navigation resolves its target at execution time, so it has none. */
+function targetlessNavigation(
+  placement: OriginPlacement,
+  history: OriginHistoryMode,
+): OriginNavigationIntent {
+  return { placement, history };
+}
+
+/** Pair a navigation intent with choreography, or return it unchanged. */
+function materialize(
+  intent: OriginNavigationIntent,
+  choreography: OriginChoreography | undefined,
+): OriginNavigationIntent | OriginAction {
+  if (!choreography) return intent;
+  const { placement, history } = intent;
+  return "target" in intent
+    ? { target: intent.target, choreography, placement, history }
+    : { choreography, placement, history };
+}
+
+/**
+ * Create the scene mutation invoked by a click, gesture, hardware command, or
+ * any other application event. `above` and `under` affect stacking only; they
+ * do not imply a universal navigation direction.
+ *
+ * @param target - View recipe to create.
+ * @param choreography - Visual routine controlling the operation.
+ * @param options - Stacking and history behavior.
+ * @returns An action that can be passed to `begin()`, `perform()`, or returned
+ * from a gesture action factory.
+ */
+export function originAction(
+  target: OriginView,
+  choreography: OriginChoreography,
+  options: OriginActionOptions = {},
+): OriginAction {
+  return materialize(
+    navigation(target, options.placement ?? "above", options.history ?? "push"),
+    choreography,
+  ) as OriginAction;
+}
+
+/**
+ * Create a retained-history push intent or complete action.
+ *
+ * Committing the action parks its origin instance and leaves it mounted until
+ * a later committed {@link back} action pops the new entry. Omit choreography
+ * when declaring `.navigate()` inside a gesture builder; provide choreography
+ * when passing the result directly to `begin()` or `perform()`.
+ *
+ * @param target - View recipe created if the push commits.
+ * @param options - Stacking options for an animation-free navigation intent.
+ * @returns An animation-free intent for use with a gesture builder.
+ */
+export function forward(
+  target: OriginView,
+  options?: OriginNavigationActionOptions,
+): OriginNavigationIntent;
+export function forward(
+  target: OriginView,
+  choreography: OriginChoreography,
+  options?: OriginNavigationActionOptions,
+): OriginAction;
+export function forward(
+  target: OriginView,
+  choreographyOrOptions?: OriginChoreography | OriginNavigationActionOptions,
+  maybeOptions?: OriginNavigationActionOptions,
+): OriginAction | OriginNavigationIntent {
+  const { choreography, options } = helperArguments(
+    choreographyOrOptions,
+    maybeOptions,
+  );
+  return materialize(
+    navigation(target, options.placement ?? "above", "push"),
+    choreography,
+  );
+}
+
+/**
+ * Create a retained-history replacement intent or complete action.
+ *
+ * The target inherits the origin's previous mounted entry instead of retaining
+ * the origin itself. A commit unmounts the origin and activates the target, so
+ * a later {@link back} skips the replaced entry. A cancellation removes the
+ * proposed target and restores the origin unchanged.
+ *
+ * Omit choreography when declaring `.navigate()` inside a gesture builder;
+ * provide choreography when passing the result directly to `begin()` or
+ * `perform()`.
+ *
+ * @param target - View recipe created for the replacement.
+ * @param options - Stacking options for an animation-free navigation intent.
+ * @returns An animation-free replacement intent for use with a gesture builder.
+ */
+export function replace(
+  target: OriginView,
+  options?: OriginNavigationActionOptions,
+): OriginNavigationIntent;
+export function replace(
+  target: OriginView,
+  choreography: OriginChoreography,
+  options?: OriginNavigationActionOptions,
+): OriginAction;
+export function replace(
+  target: OriginView,
+  choreographyOrOptions?: OriginChoreography | OriginNavigationActionOptions,
+  maybeOptions?: OriginNavigationActionOptions,
+): OriginAction | OriginNavigationIntent {
+  const { choreography, options } = helperArguments(
+    choreographyOrOptions,
+    maybeOptions,
+  );
+  return materialize(
+    navigation(target, options.placement ?? "above", "replace"),
+    choreography,
+  );
+}
+
+/**
+ * Create a retained-history back intent or complete action.
+ *
+ * The action intentionally has no target recipe. At execution time the scene
+ * resolves the origin's mounted `previousNodeKey`, reveals that exact instance,
+ * and removes the current instance only if the operation commits. Omit
+ * choreography inside gesture `.navigate()`; provide it for a programmatic
+ * action.
+ *
+ * @param options - Stacking options for an animation-free navigation intent.
+ * @returns An animation-free back intent for use with a gesture builder.
+ */
+export function back(
+  options?: OriginNavigationActionOptions,
+): OriginNavigationIntent;
+export function back(
+  choreography: OriginChoreography,
+  options?: OriginNavigationActionOptions,
+): OriginAction;
+export function back(
+  choreographyOrOptions?: OriginChoreography | OriginNavigationActionOptions,
+  maybeOptions?: OriginNavigationActionOptions,
+): OriginAction | OriginNavigationIntent {
+  const { choreography, options } = helperArguments(
+    choreographyOrOptions,
+    maybeOptions,
+  );
+  return materialize(
+    targetlessNavigation(options.placement ?? "under", "back"),
+    choreography,
+  );
+}
+
+/**
+ * Create an intent or action whose target is stacked above its origin.
+ *
+ * This helper controls stacking, not movement direction. The supplied
+ * choreography may move either component however the application chooses.
+ * Omitting choreography produces an intent for gesture `.navigate()`.
+ *
+ * @param target - View recipe to create.
+ * @param choreography - Visual routine controlling the operation.
+ * @param options - Optional history behavior.
+ */
+export function above(
+  target: OriginView,
+  options?: OriginPlacementActionOptions,
+): OriginNavigationIntent;
+export function above(
+  target: OriginView,
+  choreography: OriginChoreography,
+  options?: OriginPlacementActionOptions,
+): OriginAction;
+export function above(
+  target: OriginView,
+  choreographyOrOptions?: OriginChoreography | OriginPlacementActionOptions,
+  maybeOptions?: OriginPlacementActionOptions,
+): OriginAction | OriginNavigationIntent {
+  const { choreography, options } = helperArguments(
+    choreographyOrOptions,
+    maybeOptions,
+  );
+  return materialize(
+    navigation(target, "above", options.history ?? "push"),
+    choreography,
+  );
+}
+
+/**
+ * Create an intent or action whose target is stacked underneath its origin.
+ *
+ * Commonly used for custom reveal effects, but it has no implicit history
+ * meaning. Prefer {@link back} for retained-history navigation. Omitting
+ * choreography produces an intent for gesture `.navigate()`.
+ *
+ * @param target - View recipe to create underneath the origin.
+ * @param choreography - Visual routine controlling the operation.
+ * @param options - Optional history behavior.
+ */
+export function under(
+  target: OriginView,
+  options?: OriginPlacementActionOptions,
+): OriginNavigationIntent;
+export function under(
+  target: OriginView,
+  choreography: OriginChoreography,
+  options?: OriginPlacementActionOptions,
+): OriginAction;
+export function under(
+  target: OriginView,
+  choreographyOrOptions?: OriginChoreography | OriginPlacementActionOptions,
+  maybeOptions?: OriginPlacementActionOptions,
+): OriginAction | OriginNavigationIntent {
+  const { choreography, options } = helperArguments(
+    choreographyOrOptions,
+    maybeOptions,
+  );
+  return materialize(
+    navigation(target, "under", options.history ?? "push"),
+    choreography,
+  );
+}
@@ -0,0 +1,652 @@
+import { markRaw, reactive, shallowReactive, shallowRef } from "vue";
+import type {
+  OriginAction,
+  OriginHistoryMode,
+  OriginView,
+} from "../navigation";
+import { clamp01, type OriginRect } from "../shared";
+import type {
+  MutableOriginOperation,
+  OriginContext,
+  OriginFinishOptions,
+  OriginSceneNodeState,
+} from "./types";
+
+/** Mutable storage for one mounted scene node. */
+export interface SceneNodeRecord {
+  key: string;
+  sequence: number;
+  view: OriginView;
+  /** Retained-history link: the entry a committed back returns to. */
+  previousNodeKey?: string;
+  state: OriginSceneNodeState;
+  /** Visual link: the operation edge positioning this node as its target. */
+  incomingOperationId?: number;
+}
+
+/**
+ * Why a scene operation was rejected.
+ *
+ * - `missing-node`: the node no longer exists.
+ * - `missing-origin`: the origin node does not exist.
+ * - `inert-origin`: the origin is parked or exposed and cannot originate.
+ * - `origin-busy`: the origin already has a live outgoing operation.
+ * - `invalid-action`: the action cannot be executed as written.
+ * - `no-previous-entry`: back was requested without a retained entry.
+ * - `undecided-forward`: back was requested through an unreleased forward.
+ * - `target-busy`: the retained back target is transitioning, or still
+ *   positions the origin.
+ * - `outside-scene`: `useOrigin()` was called outside an `<OriginScene>` view.
+ */
+export type OriginSceneErrorCode =
+  | "missing-node"
+  | "missing-origin"
+  | "inert-origin"
+  | "origin-busy"
+  | "invalid-action"
+  | "no-previous-entry"
+  | "undecided-forward"
+  | "target-busy"
+  | "outside-scene";
+
+/** Error thrown or rejected by scene operations, with a stable `code`. */
+export class OriginSceneError extends Error {
+  override readonly name = "OriginSceneError";
+
+  constructor(
+    readonly code: OriginSceneErrorCode,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+/**
+ * Progress at which a release commits when the choreography does not supply
+ * its own `commitThreshold`.
+ */
+export const DEFAULT_COMMIT_THRESHOLD = 0.25;
+
+/**
+ * Release velocity (progress units per second) that commits a flick at any
+ * progress when the choreography does not supply its own `commitVelocity`.
+ */
+export const DEFAULT_COMMIT_VELOCITY = 0.2;
+
+/**
+ * Decide a release outcome from explicit options, or from velocity and
+ * progress: a flick at least `commitVelocity` fast decides by its direction,
+ * forward committing and backward cancelling, regardless of distance. Slower
+ * releases commit once progress reaches `commitThreshold`.
+ */
+export const shouldCommit = (
+  operation: MutableOriginOperation,
+  options: OriginFinishOptions,
+): boolean => {
+  if (options.commit !== undefined) return options.commit;
+  const { commitThreshold, commitVelocity } = operation.choreography;
+  const flick = commitVelocity ?? DEFAULT_COMMIT_VELOCITY;
+  if (operation.velocity >= flick) return true;
+  if (operation.velocity <= -flick) return false;
+  return operation.progress >= (commitThreshold ?? DEFAULT_COMMIT_THRESHOLD);
+};
+
+/**
+ * The scene model: nodes, operation edges, and the rules that rewrite them.
+ *
+ * Two independent structures share these records:
+ *
+ * - **History** links each node to its retained previous entry through
+ *   `previousNodeKey`. It changes only when operations commit or cancel.
+ * - **Visual graph** links each target to the operation that positions it
+ *   through `incomingOperationId`; each operation links back to its origin.
+ *   Nodes without an incoming edge are listed in `roots`.
+ *
+ * Nodes are stored flat so Vue never re-parents a component when edges are
+ * added, spliced, or removed. Every method is synchronous; timing (mounting,
+ * measuring, settling) belongs to `Scene`.
+ */
+export class SceneGraph {
+  readonly nodes = shallowReactive(new Map<string, SceneNodeRecord>());
+  readonly operations = shallowReactive(
+    new Map<number, MutableOriginOperation>(),
+  );
+  readonly roots = shallowRef<string[]>([]);
+  /**
+   * Connected resting edges temporarily removed by a back operation, keyed by
+   * that back operation's id. Cancelling the back operation restores the edge.
+   */
+  private readonly suspendedEdges = new Map<number, MutableOriginOperation>();
+  /**
+   * Operations indexed by origin key, in insertion order. Every addition and
+   * removal goes through {@link attach} and {@link detach} to keep it in sync
+   * with `operations`.
+   */
+  private readonly outgoing = shallowReactive(
+    new Map<string, readonly MutableOriginOperation[]>(),
+  );
+  private nodeSequence = 0;
+  private operationSequence = 0;
+
+  constructor(initial: readonly OriginView[]) {
+    this.roots.value = initial.map((view) => this.createNode(view).key);
+  }
+
+  // Queries -----------------------------------------------------------------
+
+  node(key: string): SceneNodeRecord | undefined {
+    return this.nodes.get(key);
+  }
+
+  operation(id: number): MutableOriginOperation | undefined {
+    return this.operations.get(id);
+  }
+
+  /** The edge positioning `node` as its target, including resting edges. */
+  incomingOf(node: SceneNodeRecord): MutableOriginOperation | undefined {
+    return node.incomingOperationId
+      ? this.operations.get(node.incomingOperationId)
+      : undefined;
+  }
+
+  /** Incoming edges positioning `node`, from the node outward to its root. */
+  incomingChain(node: SceneNodeRecord): MutableOriginOperation[] {
+    const chain: MutableOriginOperation[] = [];
+    const visited = new Set<string>();
+    let current: SceneNodeRecord | undefined = node;
+    while (current && !visited.has(current.key)) {
+      visited.add(current.key);
+      const incoming = this.incomingOf(current);
+      if (!incoming) break;
+      chain.push(incoming);
+      current = this.nodes.get(incoming.originKey);
+    }
+    return chain;
+  }
+
+  /** The unfinished operation originated by a node, if any. */
+  liveOutgoingOf(nodeKey: string): MutableOriginOperation | undefined {
+    return this.outgoing
+      .get(nodeKey)
+      ?.find((operation) => operation.phase !== "finished");
+  }
+
+  /**
+   * The operation whose source effects apply to a node. Unlike
+   * {@link liveOutgoingOf}, this includes a finished, connected resting edge.
+   */
+  presentedOutgoingOf(nodeKey: string): MutableOriginOperation | undefined {
+    return this.outgoing.get(nodeKey)?.[0];
+  }
+
+  /** Retained entries preceding `node`, oldest first. */
+  historyOf(node: SceneNodeRecord): SceneNodeRecord[] {
+    const history: SceneNodeRecord[] = [];
+    const visited = new Set<string>([node.key]);
+    let previousKey = node.previousNodeKey;
+    while (previousKey && !visited.has(previousKey)) {
+      visited.add(previousKey);
+      const previous = this.nodes.get(previousKey);
+      if (!previous) break;
+      history.push(previous);
+      previousKey = previous.previousNodeKey;
+    }
+    return history.reverse();
+  }
+
+  contextFor(nodeKey: string): OriginContext {
+    const node = this.nodes.get(nodeKey);
+    if (!node)
+      throw new OriginSceneError(
+        "missing-node",
+        `Origin scene node "${nodeKey}" no longer exists.`,
+      );
+    const history = this.historyOf(node).map((entry) => entry.view);
+    return {
+      nodeKey,
+      view: node.view,
+      canGoBack: Boolean(node.previousNodeKey),
+      previous: history.at(-1),
+      history,
+    };
+  }
+
+  /**
+   * Whether a node should currently receive input.
+   *
+   * Parked and exposed entries are inert. A target being cancelled is already
+   * scheduled to disappear, and a source settling toward commit has ceded new
+   * interactions to its target. This is node-local fate, not a global "active
+   * view".
+   */
+  isInteractive(nodeKey: string): boolean {
+    const node = this.nodes.get(nodeKey);
+    if (!node || node.state === "parked" || node.state === "exposed")
+      return false;
+    if (this.incomingOf(node)?.intent === "cancel") return false;
+    return this.liveOutgoingOf(nodeKey)?.intent !== "commit";
+  }
+
+  // Transitions -------------------------------------------------------------
+
+  /**
+   * Validate an action and add its operation edge (and, for push/replace, its
+   * target node). The edge starts in the `preparing` phase.
+   *
+   * @throws If the origin cannot originate, or the action cannot be resolved.
+   */
+  begin(
+    originKey: string,
+    action: OriginAction,
+    originRect: OriginRect | undefined,
+  ): MutableOriginOperation {
+    const origin = this.assertCanOriginate(originKey);
+    const history = action.history ?? "push";
+    if (action.choreography.persistAtRest && history !== "push")
+      throw new OriginSceneError(
+        "invalid-action",
+        "persistAtRest choreographies require retained-history push navigation.",
+      );
+
+    const { target, suspendedEdge } =
+      history === "back"
+        ? this.resolveBackTarget(origin)
+        : { target: this.createForwardTarget(origin, action, history) };
+
+    const operation = this.createOperation({
+      originKey,
+      targetKey: target.key,
+      entryTargetKey: target.key,
+      choreography: action.choreography,
+      placement: action.placement ?? "above",
+      history,
+      originRect,
+    });
+    target.incomingOperationId = operation.id;
+    target.state = "transitioning";
+    origin.state = "transitioning";
+    if (suspendedEdge) this.suspendedEdges.set(operation.id, suspendedEdge);
+    return operation;
+  }
+
+  /** Apply interactive progress to an unfinished operation. */
+  update(id: number, progress: number, velocity: number): void {
+    const operation = this.operations.get(id);
+    if (!operation || operation.phase === "finished") return;
+    operation.progress = clamp01(progress);
+    operation.overshoot = progress - operation.progress;
+    operation.velocity = velocity;
+    if (operation.phase !== "preparing") operation.phase = "interactive";
+  }
+
+  /**
+   * Finalize a committed operation.
+   *
+   * A normal push parks its origin and collapses the temporary visual edge, so
+   * the target takes the origin's place in the visual graph. A connected
+   * (`persistAtRest`) push keeps the edge at progress 1 and leaves the origin
+   * exposed but inert. Replace and back remove the origin.
+   *
+   * @returns Whether the operation's nodes still existed to be committed.
+   */
+  commit(id: number): boolean {
+    const operation = this.operations.get(id);
+    if (!operation) return false;
+    const origin = this.nodes.get(operation.originKey);
+    const target = this.nodes.get(operation.targetKey);
+    if (!origin || !target) return false;
+
+    if (operation.history === "push" && operation.choreography.persistAtRest) {
+      operation.progress = 1;
+      operation.overshoot = 0;
+      operation.velocity = 0;
+      operation.intent = "commit";
+      operation.phase = "finished";
+      origin.state = "exposed";
+      this.activate(target);
+      return true;
+    }
+
+    this.transferPosition(origin, target);
+    operation.phase = "finished";
+    this.detach(operation);
+    this.suspendedEdges.delete(operation.id);
+
+    if (operation.history === "push") {
+      origin.incomingOperationId = undefined;
+      origin.state = "parked";
+    } else {
+      // Back pops the current entry; replace discards it in favor of the new
+      // target. Both preserve every earlier retained instance, and any entry
+      // still retained above the origin now sits on the target instead.
+      for (const node of this.nodes.values())
+        if (node.previousNodeKey === origin.key && node !== target)
+          node.previousNodeKey = target.key;
+      this.removeNode(origin.key);
+    }
+
+    this.activate(target);
+    return true;
+  }
+
+  /**
+   * Finalize a cancelled operation, restoring the origin.
+   *
+   * Everything the edge created or now positions is undone. Entries from the
+   * origin's retained history (a back target, or a replacement of one) return
+   * to history; anything newer is discarded. A cancelled back that suspended
+   * a connected resting edge reconnects it instead.
+   */
+  cancel(id: number): void {
+    const operation = this.operations.get(id);
+    if (!operation) return;
+    const origin = this.nodes.get(operation.originKey);
+    const entry = this.nodes.get(operation.entryTargetKey);
+    const current = this.nodes.get(operation.targetKey);
+    const suspendedEdge = this.suspendedEdges.get(id);
+    const retained = origin ? this.retainedKeys(origin) : new Set<string>();
+    operation.phase = "finished";
+    this.detach(operation);
+    this.suspendedEdges.delete(id);
+
+    if (suspendedEdge && origin && entry && current === entry) {
+      // Put the retained page back into its former position, then reconnect
+      // the resting page→drawer edge. Both nodes keep their VNodes.
+      this.discardOutgoing(entry.key, new Set(retained));
+      this.transferPosition(origin, entry);
+      this.attach(suspendedEdge);
+      origin.incomingOperationId = suspendedEdge.id;
+      entry.state = "exposed";
+    } else {
+      for (const node of new Set([entry, current])) {
+        if (!node || node === origin) continue;
+        if (retained.has(node.key)) this.returnToHistory(node, retained);
+        else this.removeBranch(node.key, new Set(retained));
+      }
+    }
+
+    if (origin) this.activate(origin);
+  }
+
+  // Transition steps --------------------------------------------------------
+
+  private assertCanOriginate(originKey: string): SceneNodeRecord {
+    const origin = this.nodes.get(originKey);
+    if (!origin)
+      throw new OriginSceneError(
+        "missing-origin",
+        `Cannot animate from missing origin "${originKey}".`,
+      );
+    if (origin.state === "parked" || origin.state === "exposed")
+      throw new OriginSceneError(
+        "inert-origin",
+        `Cannot animate from ${origin.state} origin "${originKey}".`,
+      );
+    if (this.liveOutgoingOf(originKey))
+      throw new OriginSceneError(
+        "origin-busy",
+        `Origin "${originKey}" already has an outgoing operation. ` +
+          "A descendant target may start its own operation instead.",
+      );
+    return origin;
+  }
+
+  /**
+   * Resolve the retained previous entry for a back operation.
+   *
+   * If the origin's incoming edge comes from that previous entry (a forward
+   * push still settling, or a connected resting edge), the edge is collapsed
+   * first. Creating a new edge back to its origin would otherwise form X→Y→X.
+   * Reciprocal choreographies begin at the same visual endpoints, so this
+   * handoff is continuous without remounting either node.
+   */
+  private resolveBackTarget(origin: SceneNodeRecord): {
+    target: SceneNodeRecord;
+    suspendedEdge?: MutableOriginOperation;
+  } {
+    const previousKey = origin.previousNodeKey;
+    if (!previousKey)
+      throw new OriginSceneError(
+        "no-previous-entry",
+        `Cannot go back from origin "${origin.key}" without a previous entry.`,
+      );
+    const target = this.nodes.get(previousKey);
+    if (!target)
+      throw new OriginSceneError(
+        "no-previous-entry",
+        `Cannot go back to missing retained entry "${previousKey}".`,
+      );
+
+    let suspendedEdge: MutableOriginOperation | undefined;
+    const incoming = this.incomingOf(origin);
+    if (incoming?.originKey === target.key) {
+      if (incoming.intent !== "commit")
+        throw new OriginSceneError(
+          "undecided-forward",
+          "Cannot go back through an undecided forward operation.",
+        );
+      if (incoming.phase !== "finished") this.commit(incoming.id);
+
+      const resting = this.operations.get(incoming.id);
+      if (resting?.phase === "finished" && resting.choreography.persistAtRest) {
+        // Re-root A→page→drawer as A→drawer before adding drawer→page.
+        this.detach(resting);
+        this.transferPosition(target, origin);
+        target.incomingOperationId = undefined;
+        suspendedEdge = resting;
+      }
+    }
+
+    // A target still positioning the origin (through edges other than the
+    // one collapsed above) would close a visual cycle.
+    if (
+      this.incomingChain(origin).some(
+        (operation) => operation.originKey === target.key,
+      )
+    )
+      throw new OriginSceneError(
+        "target-busy",
+        `Retained target "${target.key}" still positions origin "${origin.key}".`,
+      );
+    if (this.liveOutgoingOf(target.key))
+      throw new OriginSceneError(
+        "target-busy",
+        `Retained target "${target.key}" already has an outgoing operation.`,
+      );
+    if (target.incomingOperationId)
+      throw new OriginSceneError(
+        "target-busy",
+        `Retained target "${target.key}" is already transitioning.`,
+      );
+    return { target, suspendedEdge };
+  }
+
+  /** Create the target node for a push or replace operation. */
+  private createForwardTarget(
+    origin: SceneNodeRecord,
+    action: OriginAction,
+    history: Exclude<OriginHistoryMode, "back">,
+  ): SceneNodeRecord {
+    if (!action.target)
+      throw new OriginSceneError(
+        "invalid-action",
+        `A "${history}" operation requires a target view recipe.`,
+      );
+    // A replacement skips the origin in the retained chain. The origin stays
+    // mounted until commit so an interactive replacement can still cancel.
+    const previousKey =
+      history === "push" ? origin.key : origin.previousNodeKey;
+    return this.createNode(action.target, previousKey);
+  }
+
+  /**
+   * Make a node presentable again. A node still holding a connected resting
+   * edge (an open drawer, say) stays exposed rather than becoming active.
+   */
+  private activate(node: SceneNodeRecord): void {
+    const resting = this.presentedOutgoingOf(node.key);
+    if (resting?.phase === "finished") {
+      node.state = "exposed";
+      return;
+    }
+    node.state = "active";
+    this.refreshPresentedState(node);
+  }
+
+  /**
+   * Recompute whether a presented node is participating in a live operation.
+   * Parked and exposed nodes keep their retained state.
+   */
+  private refreshPresentedState(node: SceneNodeRecord): void {
+    if (node.state === "parked" || node.state === "exposed") return;
+    const incoming = this.incomingOf(node);
+    node.state =
+      (incoming && incoming.phase !== "finished") ||
+      this.liveOutgoingOf(node.key)
+        ? "transitioning"
+        : "active";
+  }
+
+  // Structural primitives ---------------------------------------------------
+
+  private createNode(
+    view: OriginView,
+    previousNodeKey?: string,
+  ): SceneNodeRecord {
+    const sequence = ++this.nodeSequence;
+    const node: SceneNodeRecord = shallowReactive({
+      key: `${view.key ?? view.name ?? "view"}::${sequence}`,
+      sequence,
+      view: markRaw(view),
+      previousNodeKey,
+      state: "active",
+      incomingOperationId: undefined,
+    });
+    this.nodes.set(node.key, node);
+    return node;
+  }
+
+  private createOperation(
+    init: Pick<
+      MutableOriginOperation,
+      | "originKey"
+      | "targetKey"
+      | "entryTargetKey"
+      | "choreography"
+      | "placement"
+      | "history"
+      | "originRect"
+    >,
+  ): MutableOriginOperation {
+    const operation = reactive<MutableOriginOperation>({
+      id: ++this.operationSequence,
+      originKey: init.originKey,
+      targetKey: init.targetKey,
+      entryTargetKey: init.entryTargetKey,
+      choreography: markRaw(init.choreography),
+      placement: init.placement,
+      history: init.history,
+      progress: 0,
+      overshoot: 0,
+      velocity: 0,
+      phase: "preparing",
+      intent: "undecided",
+      originRect: init.originRect,
+    });
+    this.attach(operation);
+    return operation;
+  }
+
+  private attach(operation: MutableOriginOperation): void {
+    this.operations.set(operation.id, operation);
+    const siblings = this.outgoing.get(operation.originKey) ?? [];
+    this.outgoing.set(operation.originKey, [...siblings, operation]);
+  }
+
+  private detach(operation: MutableOriginOperation): void {
+    this.operations.delete(operation.id);
+    const siblings = (this.outgoing.get(operation.originKey) ?? []).filter(
+      (sibling) => sibling.id !== operation.id,
+    );
+    if (siblings.length) this.outgoing.set(operation.originKey, siblings);
+    else this.outgoing.delete(operation.originKey);
+  }
+
+  private removeNode(nodeKey: string): void {
+    this.nodes.delete(nodeKey);
+    this.roots.value = this.roots.value.filter((key) => key !== nodeKey);
+  }
+
+  /**
+   * Resolve the operations a node started, because the node is leaving
+   * the visible graph: nodes they created (push/replace targets, including
+   * replacements whose history skips this node) are removed, and retained
+   * entries they revealed (back targets) are restored as if that back
+   * operation were cancelled.
+   */
+  /** Park a retained entry again, discarding what it started meanwhile. */
+  private returnToHistory(node: SceneNodeRecord, retained: Set<string>): void {
+    this.discardOutgoing(node.key, new Set(retained));
+    node.incomingOperationId = undefined;
+    node.state = "parked";
+  }
+
+  /** A node's key plus its retained history, which a cancel must keep. */
+  private retainedKeys(node: SceneNodeRecord): Set<string> {
+    return new Set([node.key, ...this.historyOf(node).map(({ key }) => key)]);
+  }
+
+  private discardOutgoing(nodeKey: string, visited = new Set<string>()): void {
+    for (const operation of [...(this.outgoing.get(nodeKey) ?? [])]) {
+      // Includes finished resting edges: an open drawer closes with its page.
+      if (operation.history === "back") {
+        this.cancel(operation.id);
+      } else {
+        this.detach(operation);
+        this.removeBranch(operation.entryTargetKey, visited);
+        this.removeBranch(operation.targetKey, visited);
+      }
+    }
+  }
+
+  /**
+   * Remove a node, every node whose retained history passes through it, and
+   * every operation touching any of them. Earlier entries are untouched.
+   * Operations the node itself started are discarded first.
+   */
+  private removeBranch(nodeKey: string, visited = new Set<string>()): void {
+    if (visited.has(nodeKey)) return;
+    visited.add(nodeKey);
+
+    for (const node of [...this.nodes.values()])
+      if (node.previousNodeKey === nodeKey)
+        this.removeBranch(node.key, visited);
+    this.discardOutgoing(nodeKey, visited);
+    for (const operation of [...this.operations.values()])
+      if (
+        operation.originKey === nodeKey ||
+        operation.targetKey === nodeKey ||
+        operation.entryTargetKey === nodeKey
+      )
+        this.detach(operation);
+    this.removeNode(nodeKey);
+  }
+
+  /**
+   * Give `target` the visual-graph position currently held by `from`: either
+   * as the target of `from`'s incoming edge, or as a root. Neither Vue VNode
+   * moves; only edge bookkeeping changes.
+   */
+  private transferPosition(from: SceneNodeRecord, target: SceneNodeRecord) {
+    const parent = this.incomingOf(from);
+    if (parent) {
+      parent.targetKey = target.key;
+      target.incomingOperationId = parent.id;
+    } else {
+      this.roots.value = this.roots.value.map((key) =>
+        key === from.key ? target.key : key,
+      );
+      target.incomingOperationId = undefined;
+    }
+  }
+}
@@ -0,0 +1,734 @@
+import {
+  computed,
+  inject,
+  markRaw,
+  nextTick,
+  shallowRef,
+  type ComputedRef,
+  type CSSProperties,
+  type InjectionKey,
+} from "vue";
+import {
+  composeEffects,
+  normalizedEffect,
+  type OriginEffect,
+  type OriginEffectSet,
+  type OriginSpring,
+  type OriginOperationIntent,
+  type OriginOperationPhase,
+} from "../choreography";
+import type { OriginAction, OriginView } from "../navigation";
+import {
+  DEV,
+  warn,
+  clamp,
+  clamp01,
+  measureRect,
+  prefersReducedMotion,
+  windowRect,
+  type OriginRect,
+} from "../shared";
+import {
+  OriginSceneError,
+  SceneGraph,
+  shouldCommit,
+  type SceneNodeRecord,
+} from "./graph";
+import type {
+  CreateOriginSceneOptions,
+  MutableOriginOperation,
+  OriginContext,
+  OriginFinishOptions,
+  OriginOperation,
+  OriginOperationHandle,
+  OriginScene,
+  OriginSceneNode,
+} from "./types";
+
+// Compositing ---------------------------------------------------------------
+
+/**
+ * Compositor invariants rather than visual theming. They stay inline so a
+ * missing optional stylesheet can never place scene nodes back into normal
+ * block/flex flow and vertically stack views.
+ *
+ * Deliberately not frozen: it is spread once per node per frame, and V8
+ * spreads frozen objects markedly slower.
+ */
+const NODE_BASE_STYLE: Readonly<CSSProperties> = {
+  position: "absolute",
+  inset: "0",
+  width: "100%",
+  height: "100%",
+  overflow: "hidden",
+};
+
+/** Base z-index keeping every node above content outside the scene. */
+const Z_INDEX_BASE = 1_000_000;
+/** z-index distance between adjacent relative layers. */
+const Z_INDEX_PER_LAYER = 10_000;
+
+/**
+ * Effect layers applied to a node, ordered outermost frame first.
+ *
+ * A node inherits the frame and target effects of every edge on its incoming
+ * chain, then adds the frame and source effects of the edge it originates.
+ * Ancestors' source effects are intentionally excluded: only the initiating
+ * component receives the source side of an operation.
+ *
+ * @param effectsOf - The current effect set of an operation's choreography.
+ */
+export const nodeEffectLayers = (
+  graph: SceneGraph,
+  node: SceneNodeRecord,
+  effectsOf: (operation: MutableOriginOperation) => OriginEffectSet,
+): OriginEffect[] => {
+  const chain = graph.incomingChain(node);
+  // Evaluate choreographies node-first, then apply them outermost-first.
+  const effectSets = chain.map(effectsOf);
+  const layers: OriginEffect[] = [];
+  for (let index = chain.length - 1; index >= 0; index -= 1) {
+    const targetLayer = chain[index]!.placement === "above" ? 1 : -1;
+    layers.push(
+      normalizedEffect(effectSets[index]!.frame),
+      normalizedEffect(effectSets[index]!.target, targetLayer),
+    );
+  }
+
+  const outgoing = graph.presentedOutgoingOf(node.key);
+  if (outgoing) {
+    const effects = effectsOf(outgoing);
+    layers.push(
+      normalizedEffect(effects.frame),
+      normalizedEffect(effects.source),
+    );
+  }
+  return layers;
+};
+
+/** Collapse every effect layer applied to a node into its host's style. */
+export const composeNodeStyle = (
+  graph: SceneGraph,
+  nodeKey: string,
+  effectsOf: (operation: MutableOriginOperation) => OriginEffectSet,
+): CSSProperties => {
+  const node = graph.node(nodeKey);
+  if (!node) return {};
+
+  const { style, layer } = composeEffects(
+    nodeEffectLayers(graph, node, effectsOf),
+    NODE_BASE_STYLE,
+  );
+  style.zIndex = Z_INDEX_BASE + layer * Z_INDEX_PER_LAYER + node.sequence;
+  style.pointerEvents = graph.isInteractive(nodeKey) ? "auto" : "none";
+  if (node.state === "parked") {
+    // Parked entries remain mounted in their original flat hosts. Keeping the
+    // DOM preserves local component state and nested scroll positions, while
+    // visibility/inert handling removes them from presentation.
+    style.visibility = "hidden";
+    style.contentVisibility = "hidden";
+  }
+  return style;
+};
+
+// Settling spring -----------------------------------------------------------
+
+/*
+ * A damped spring settles an operation toward 0 or 1. It keeps release
+ * velocity continuous with pointer motion without imposing a fixed-duration
+ * easing on custom choreographies.
+ */
+
+const DEFAULT_STIFFNESS = 280;
+const DEFAULT_DAMPING = 30;
+/** Fixed integration step, in seconds. */
+const STEP = 1 / 120;
+/** Frame durations are clamped to this range, in seconds. */
+const MIN_FRAME = 0.001;
+const MAX_FRAME = 0.032;
+/** Release velocities beyond this magnitude are clamped. */
+const MAX_INITIAL_VELOCITY = 8;
+const POSITION_TOLERANCE = 0.002;
+const VELOCITY_TOLERANCE = 0.02;
+
+/** Position and velocity of a spring, in progress units. */
+export interface SpringState {
+  readonly position: number;
+  readonly velocity: number;
+}
+
+/**
+ * Advance a spring by one animation frame.
+ *
+ * @param elapsedMs - Time since the previous frame in milliseconds.
+ */
+export const stepSpring = (
+  state: SpringState,
+  target: number,
+  elapsedMs: number,
+  spring: OriginSpring = {},
+): SpringState & { readonly done: boolean } => {
+  const stiffness = spring.stiffness ?? DEFAULT_STIFFNESS;
+  const damping = spring.damping ?? DEFAULT_DAMPING;
+  const elapsed = clamp(elapsedMs / 1000, MIN_FRAME, MAX_FRAME);
+  const iterations = Math.max(1, Math.ceil(elapsed / STEP));
+  const dt = elapsed / iterations;
+  let { position, velocity } = state;
+  for (let index = 0; index < iterations; index += 1) {
+    const acceleration = (target - position) * stiffness - velocity * damping;
+    velocity += acceleration * dt;
+    position += velocity * dt;
+  }
+  const done =
+    Math.abs(target - position) < POSITION_TOLERANCE &&
+    Math.abs(velocity) < VELOCITY_TOLERANCE;
+  return { position, velocity, done };
+};
+
+/**
+ * Run a spring on `requestAnimationFrame` until it rests at `target` or
+ * `onFrame` returns `false` because its subject no longer exists.
+ *
+ * Each frame reports the raw position; the final frame reports exactly
+ * `target` with zero velocity.
+ */
+export const runSpring = (
+  from: SpringState,
+  target: number,
+  onFrame: (position: number, velocity: number) => boolean,
+  spring: OriginSpring = {},
+): Promise<void> =>
+  new Promise<void>((resolve) => {
+    let state: SpringState = {
+      position: from.position,
+      velocity: clamp(
+        from.velocity,
+        -MAX_INITIAL_VELOCITY,
+        MAX_INITIAL_VELOCITY,
+      ),
+    };
+    let previous = performance.now();
+
+    const frame = (time: number) => {
+      const next = stepSpring(state, target, time - previous, spring);
+      previous = time;
+      state = next;
+      const alive = next.done
+        ? onFrame(target, 0)
+        : onFrame(next.position, next.velocity);
+      if (!alive || next.done) resolve();
+      else window.requestAnimationFrame(frame);
+    };
+    window.requestAnimationFrame(frame);
+  });
+
+// Continuity check (development only) ---------------------------------------
+
+/** A host's rendered transform as a 4×4 matrix, plus its opacity. */
+interface Pose {
+  readonly matrix: readonly number[];
+  readonly opacity: number;
+}
+
+const warnedChoreographies = new WeakSet<object>();
+
+/** Read a visible host's rendered pose; `null` if hidden or unreadable. */
+const poseOf = (host: HTMLElement): Pose | null => {
+  const style = getComputedStyle(host);
+  if (style.visibility === "hidden") return null;
+  const matrix = parseMatrix(style.transform);
+  const opacity = Number(style.opacity);
+  return matrix && Number.isFinite(opacity) ? { matrix, opacity } : null;
+};
+
+/** Parse a computed `transform` ("none", matrix() or matrix3d()). */
+const parseMatrix = (transform: string): number[] | null => {
+  if (!transform || transform === "none")
+    return [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+  const values = /^matrix(3d)?\(([^)]*)\)$/.exec(transform);
+  if (!values) return null;
+  const numbers = values[2]!.split(",").map(Number);
+  if (numbers.some((value) => !Number.isFinite(value))) return null;
+  if (values[1]) return numbers.length === 16 ? numbers : null;
+  if (numbers.length !== 6) return null;
+  const [a, b, c, d, e, f] = numbers as [
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+  ];
+  return [a, b, 0, 0, c, d, 0, 0, 0, 0, 1, 0, e, f, 0, 1];
+};
+
+/** Equal within half a pixel of translation and 1% of anything else. */
+const posesMatch = (a: Pose, b: Pose): boolean =>
+  Math.abs(a.opacity - b.opacity) <= 0.01 &&
+  a.matrix.every((value, index) => {
+    const tolerance = index === 12 || index === 13 || index === 14 ? 0.5 : 0.01;
+    return Math.abs(value - b.matrix[index]!) <= tolerance;
+  });
+
+// Scene ---------------------------------------------------------------------
+
+/** Imperative controller for one operation, returned by `Scene.begin()`. */
+class OperationHandle implements OriginOperationHandle {
+  readonly id: number;
+  readonly originKey: string;
+  readonly targetKey: string;
+
+  constructor(
+    private readonly scene: Scene,
+    /** Kept after the graph drops it, so `intent` stays readable. */
+    private readonly operation: MutableOriginOperation,
+    /** The target at creation; later edge rewrites do not change it. */
+    targetKey: string,
+  ) {
+    markRaw(this);
+    this.id = operation.id;
+    this.originKey = operation.originKey;
+    this.targetKey = targetKey;
+  }
+
+  get intent(): OriginOperationIntent {
+    return this.operation.intent;
+  }
+
+  update(progress: number, velocity = 0): void {
+    this.scene.graph.update(this.id, progress, velocity);
+  }
+
+  finish(options?: OriginFinishOptions): Promise<boolean> {
+    return this.scene.finish(this.id, options);
+  }
+
+  async cancel(options?: Pick<OriginFinishOptions, "animate">): Promise<void> {
+    await this.scene.finish(this.id, {
+      commit: false,
+      animate: options?.animate,
+    });
+  }
+}
+
+/**
+ * One independent scene: the {@link SceneGraph} model plus the timing around
+ * it — waiting for Vue to mount targets, measuring hosts, and settling
+ * released operations with a spring.
+ */
+class Scene implements OriginScene {
+  /** @internal */
+  readonly graph: SceneGraph;
+  readonly nodes: ComputedRef<readonly OriginSceneNode[]>;
+  readonly operations: ComputedRef<readonly OriginOperation[]>;
+  readonly roots: SceneGraph["roots"];
+
+  /** DOM registered by the renderer, used only for measurement. */
+  private readonly hosts = new Map<string, HTMLElement>();
+  private container: HTMLElement | null = null;
+  private resizeObserver: ResizeObserver | null = null;
+  /**
+   * Scene-container bounds, or the browser window before mounting. Cached and
+   * refreshed on resize and whenever an operation begins, so compositing
+   * never forces layout.
+   */
+  private readonly viewport = shallowRef<OriginRect>(windowRect());
+  /**
+   * One memoized effect set per operation. It recomputes only when that
+   * operation's progress, phase, intent, rects, or the viewport change, so
+   * nodes sharing an edge do not evaluate its choreography again.
+   */
+  /** The latest release (finish call) of each operation. */
+  private readonly releases = new WeakMap<MutableOriginOperation, object>();
+  /** Final outcome of each operation, once a release has decided it. */
+  private readonly outcomes = new WeakMap<MutableOriginOperation, boolean>();
+  /** Interrupted releases waiting for a later release to decide. */
+  private readonly waiters = new WeakMap<
+    MutableOriginOperation,
+    Array<(committed: boolean) => void>
+  >();
+  private readonly effectSets = new WeakMap<
+    MutableOriginOperation,
+    ComputedRef<OriginEffectSet>
+  >();
+
+  constructor(options: CreateOriginSceneOptions) {
+    // Never proxy the scene: its methods rely on raw internal state.
+    markRaw(this);
+    this.graph = new SceneGraph(
+      Array.isArray(options.initial) ? options.initial : [options.initial],
+    );
+    this.roots = this.graph.roots;
+    this.nodes = computed(() =>
+      [...this.graph.nodes.values()].map((node) => ({
+        ...node,
+        history: this.graph.historyOf(node).map((entry) => entry.view),
+      })),
+    );
+    this.operations = computed(() =>
+      [...this.graph.operations.values()].filter(
+        (operation) => operation.phase !== "finished",
+      ),
+    );
+  }
+
+  contextFor(nodeKey: string): OriginContext {
+    return this.graph.contextFor(nodeKey);
+  }
+
+  async begin(
+    originKey: string,
+    action: OriginAction,
+  ): Promise<OriginOperationHandle> {
+    if (this.container) this.refreshViewport();
+    // Only a scene at rest has a pose the new operation must continue from.
+    const poses =
+      DEV && this.operations.value.length === 0 ? this.capturePoses() : null;
+    const operation = this.graph.begin(
+      originKey,
+      action,
+      this.measure(originKey),
+    );
+    const { targetKey } = operation;
+
+    // Let Vue mount the target before measuring it. Gesture recognizers
+    // buffer pointer progress while this short preparation step is pending.
+    await nextTick();
+    operation.targetRect = this.measure(targetKey);
+    operation.phase = "interactive";
+    if (poses) this.warnOnJump(poses, operation);
+    return new OperationHandle(this, operation, targetKey);
+  }
+
+  async perform(originKey: string, action: OriginAction): Promise<boolean> {
+    const handle = await this.begin(originKey, action);
+    return handle.finish({ commit: true });
+  }
+
+  /**
+   * Fix an operation's outcome, settle it, and rewrite the graph.
+   *
+   * Calling `update()` while an operation settles "catches" it: the spring
+   * stops and progress is under control again. A later `finish()` then
+   * decides the outcome; every earlier, interrupted `finish()` resolves with
+   * that final outcome instead of applying its own.
+   *
+   * @internal Called through {@link OperationHandle}.
+   */
+  finish(id: number, options: OriginFinishOptions = {}): Promise<boolean> {
+    const operation = this.graph.operation(id);
+    if (!operation) return Promise.resolve(false);
+    if (operation.phase === "finished")
+      return Promise.resolve(operation.intent === "commit");
+    const release = {};
+    this.releases.set(operation, release);
+    return this.release(operation, release, options);
+  }
+
+  private async release(
+    operation: MutableOriginOperation,
+    release: object,
+    options: OriginFinishOptions,
+  ): Promise<boolean> {
+    // The outcome is fixed at release, so the target can originate another
+    // operation while this one is only visually settling.
+    const commit = shouldCommit(operation, options);
+    operation.intent = commit ? "commit" : "cancel";
+    operation.phase = "settling";
+    const current = () =>
+      this.releases.get(operation) === release &&
+      operation.phase === "settling";
+    await this.settle(
+      operation,
+      commit ? 1 : 0,
+      options.animate ?? true,
+      current,
+    );
+
+    // Another release already decided this operation.
+    const decided = this.outcomes.get(operation);
+    if (decided !== undefined) return decided;
+    // A later operation may already have finalized this edge.
+    const finished = (operation.phase as OriginOperationPhase) === "finished";
+    if (!this.graph.operation(operation.id) || finished)
+      return this.decide(
+        operation,
+        finished ? operation.intent === "commit" : commit,
+      );
+    // Caught by update() or superseded by a later finish(): wait for the
+    // release that decides.
+    if (!current())
+      return new Promise<boolean>((resolve) =>
+        this.waiters.set(operation, [
+          ...(this.waiters.get(operation) ?? []),
+          resolve,
+        ]),
+      );
+
+    return this.decide(
+      operation,
+      commit
+        ? this.graph.commit(operation.id)
+        : (this.graph.cancel(operation.id), false),
+    );
+  }
+
+  /** Record an operation's final outcome and settle interrupted releases. */
+  private decide(operation: MutableOriginOperation, committed: boolean) {
+    this.outcomes.set(operation, committed);
+    for (const resolve of this.waiters.get(operation) ?? []) resolve(committed);
+    this.waiters.delete(operation);
+    return committed;
+  }
+
+  registerElement(nodeKey: string, element: HTMLElement | null): void {
+    if (element) this.hosts.set(nodeKey, element);
+    else this.hosts.delete(nodeKey);
+  }
+
+  registerContainer(element: HTMLElement | null): void {
+    if (element === this.container) return;
+    this.resizeObserver?.disconnect();
+    this.resizeObserver = null;
+    this.container = element;
+    if (!element) return;
+    this.refreshViewport();
+    if (typeof ResizeObserver !== "undefined") {
+      this.resizeObserver = new ResizeObserver(() => this.refreshViewport());
+      this.resizeObserver.observe(element);
+    }
+  }
+
+  styleForNode(nodeKey: string): CSSProperties {
+    return composeNodeStyle(this.graph, nodeKey, this.effectsOf);
+  }
+
+  isNodeInteractive(nodeKey: string): boolean {
+    return this.graph.isInteractive(nodeKey);
+  }
+
+  /**
+   * Move an operation to 0 or 1, animated unless motion is disabled. The
+   * spring stops early once `current()` reports the release was caught or
+   * superseded.
+   */
+  private async settle(
+    operation: MutableOriginOperation,
+    target: 0 | 1,
+    animate: boolean,
+    current: () => boolean,
+  ) {
+    if (!animate || prefersReducedMotion()) {
+      operation.progress = target;
+      operation.overshoot = 0;
+      operation.velocity = 0;
+      return;
+    }
+    // Start from the raw position so a rubber-banded drag springs back
+    // continuously instead of snapping its overshoot away.
+    const from = {
+      position: operation.progress + operation.overshoot,
+      velocity: operation.velocity,
+    };
+    await runSpring(
+      from,
+      target,
+      (position, velocity) => {
+        if (!this.graph.operation(operation.id) || !current()) return false;
+        operation.progress = clamp01(position);
+        operation.overshoot = position - operation.progress;
+        operation.velocity = velocity;
+        return true;
+      },
+      operation.choreography.spring,
+    );
+  }
+
+  /** Development only: each visible host's rendered transform and opacity. */
+  private capturePoses(): Map<string, Pose> {
+    const poses = new Map<string, Pose>();
+    for (const [key, host] of this.hosts) {
+      const pose = poseOf(host);
+      if (pose) poses.set(key, pose);
+    }
+    return poses;
+  }
+
+  /**
+   * Development only: warn when an operation's first frame moved a node that
+   * was visibly at rest, the one-frame "pop" of mismatched choreographies.
+   */
+  private warnOnJump(
+    before: Map<string, Pose>,
+    operation: MutableOriginOperation,
+  ) {
+    const { choreography } = operation;
+    if (warnedChoreographies.has(choreography)) return;
+    for (const [key, pose] of before) {
+      const host = this.hosts.get(key);
+      const after = host && poseOf(host);
+      if (!after || posesMatch(pose, after)) continue;
+      warnedChoreographies.add(choreography);
+      warn(
+        `"${choreography.name ?? "anonymous"}" moved node "${key}" on its ` +
+          "first frame. At progress 0 its effects should match the pose the " +
+          "scene was resting in, usually the previous choreography at " +
+          "progress 1; otherwise the view jumps.",
+      );
+      return;
+    }
+  }
+
+  private measure(nodeKey: string): OriginRect | undefined {
+    const host = this.hosts.get(nodeKey);
+    return host ? measureRect(host) : undefined;
+  }
+
+  /** Re-measure the container, replacing the cached rect only on change. */
+  private refreshViewport(): void {
+    const next = this.container ? measureRect(this.container) : windowRect();
+    const current = this.viewport.value;
+    if (
+      next.top !== current.top ||
+      next.left !== current.left ||
+      next.width !== current.width ||
+      next.height !== current.height
+    )
+      this.viewport.value = next;
+  }
+
+  private readonly effectsOf = (
+    operation: MutableOriginOperation,
+  ): OriginEffectSet => {
+    let effects = this.effectSets.get(operation);
+    if (!effects) {
+      effects = computed(() =>
+        operation.choreography.effects({
+          progress: operation.progress,
+          overshoot: operation.overshoot,
+          velocity: operation.velocity,
+          phase: operation.phase,
+          intent: operation.intent,
+          originRect: operation.originRect,
+          targetRect: operation.targetRect,
+          viewport: this.viewport.value,
+        }),
+      );
+      this.effectSets.set(operation, effects);
+    }
+    return effects.value;
+  };
+}
+
+/**
+ * Create one independent scene/history context.
+ *
+ * The implementation stores nodes flat. Operation edges describe how their
+ * visual effects compose, but a Vue component never moves to a different VNode
+ * parent as edges are added or removed. This is what preserves component state
+ * while X→Y and Y→Z overlap.
+ *
+ * @param options - Initial root view recipe or recipes.
+ * @returns A self-contained reactive scene. Render it through `OriginScene`.
+ *
+ * @example
+ * ```ts
+ * const scene = createOriginScene({
+ *   initial: originView(HomeView, undefined, { key: "home" }),
+ * });
+ * ```
+ */
+export function createOriginScene(
+  options: CreateOriginSceneOptions,
+): OriginScene {
+  return new Scene(options);
+}
+
+// Node-scoped access --------------------------------------------------------
+
+/**
+ * Injection payload provided by each stable scene-node host.
+ *
+ * @internal
+ */
+export interface OriginNodeScope {
+  /** Scene containing the node. */
+  readonly scene: OriginScene;
+  /** Unique key of the mounted node. */
+  readonly nodeKey: string;
+}
+
+/** Node-scoped controls returned by {@link useOrigin}. */
+export interface UseOrigin {
+  /** Key of the mounted node containing the calling component. */
+  readonly nodeKey: string;
+  /** Scene containing the calling component. */
+  readonly scene: OriginScene;
+  /** Reactive context for the calling component's scene node. */
+  readonly context: ComputedRef<OriginContext>;
+  /** Reactive shorthand for `context.value.view`. */
+  readonly view: ComputedRef<OriginView>;
+  /** Reactive shorthand for `context.value.previous`. */
+  readonly previous: ComputedRef<OriginView | undefined>;
+  /** Reactive shorthand for `context.value.canGoBack`. */
+  readonly canGoBack: ComputedRef<boolean>;
+  /** Begin an interactively controlled operation from this component. */
+  begin(action: OriginAction): Promise<OriginOperationHandle>;
+  /** Programmatically create and commit a target from this component. */
+  perform(action: OriginAction): Promise<boolean>;
+}
+
+/**
+ * Injection key used by the internal scene-node host to establish origin
+ * ownership for descendant components.
+ *
+ * Application code normally calls {@link useOrigin} instead of injecting this
+ * key directly.
+ *
+ * @internal
+ */
+export const originNodeScopeKey: InjectionKey<OriginNodeScope> =
+  Symbol("origin-node-scope");
+
+/**
+ * Access the scene from the component that owns an interaction declaration.
+ *
+ * There is deliberately no `activeView`: the injected node is the origin
+ * because this component is where the event or application action occurred.
+ *
+ * @returns Node-scoped scene state and operation controls.
+ * @throws If called outside a component rendered by `OriginScene`.
+ *
+ * @example
+ * ```ts
+ * const origin = useOrigin();
+ *
+ * function openProfile() {
+ *   return origin.perform(
+ *     forward(originView(ProfileView), slideLeft),
+ *   );
+ * }
+ * ```
+ */
+export function useOrigin(): UseOrigin {
+  const scope = inject(originNodeScopeKey);
+  if (!scope)
+    throw new OriginSceneError(
+      "outside-scene",
+      "useOrigin() must be called inside an <OriginScene> view.",
+    );
+
+  const { scene, nodeKey } = scope;
+  const context = computed(() => scene.contextFor(nodeKey));
+
+  return {
+    nodeKey,
+    scene,
+    context,
+    view: computed(() => context.value.view),
+    previous: computed(() => context.value.previous),
+    canGoBack: computed(() => context.value.canGoBack),
+    begin: (action) => scene.begin(nodeKey, action),
+    perform: (action) => scene.perform(nodeKey, action),
+  };
+}
@@ -0,0 +1,236 @@
+import type { ComputedRef, CSSProperties, ShallowRef } from "vue";
+import type {
+  OriginChoreography,
+  OriginOperationIntent,
+  OriginOperationPhase,
+} from "../choreography";
+import type {
+  OriginAction,
+  OriginHistoryMode,
+  OriginPlacement,
+  OriginView,
+} from "../navigation";
+import type { OriginRect } from "../shared";
+
+/**
+ * Visibility/lifecycle role of a mounted scene node.
+ *
+ * - `active`: currently exposed for normal interaction.
+ * - `transitioning`: participating in at least one live operation edge.
+ * - `exposed`: retained and visually presented behind/beside the active entry,
+ *   but inert.
+ * - `parked`: retained in history but visually hidden and inert.
+ */
+export type OriginSceneNodeState =
+  "active" | "transitioning" | "exposed" | "parked";
+
+/**
+ * Read-only diagnostic representation of one mounted scene node.
+ *
+ * A node corresponds to one currently mounted Vue component instance.
+ */
+export interface OriginSceneNode {
+  /** Unique identity for this particular mounted scene node. */
+  readonly key: string;
+  /** Monotonically increasing creation order within the scene. */
+  readonly sequence: number;
+  /** Recipe used to create the node's component. */
+  readonly view: OriginView;
+  /** Recipes for the retained instance chain preceding this node. */
+  readonly history: readonly OriginView[];
+  /** Key of the retained mounted entry immediately before this node. */
+  readonly previousNodeKey?: string;
+  /** Current visibility/lifecycle role of this mounted instance. */
+  readonly state: OriginSceneNodeState;
+  /**
+   * Operation edge positioning this node as its target. This may identify a
+   * connected resting edge that is intentionally absent from live-operation
+   * diagnostics.
+   */
+  readonly incomingOperationId?: number;
+}
+
+/** Read-only diagnostic representation of one live operation edge. */
+export interface OriginOperation {
+  /** Unique, monotonically increasing operation identity within the scene. */
+  readonly id: number;
+  /** Key of the mounted component that originated the operation. */
+  readonly originKey: string;
+  /** Key of the newly created or retained target component. */
+  readonly targetKey: string;
+  /** Original history entry targeted before visual-edge rewrites. */
+  readonly entryTargetKey: string;
+  /** Choreography currently calculating this edge's effects. */
+  readonly choreography: OriginChoreography;
+  /** Target stacking relationship to the origin. */
+  readonly placement: OriginPlacement;
+  /** Retained-history behavior performed if this operation commits. */
+  readonly history: OriginHistoryMode;
+  /** Normalized progress in the inclusive range `0..1`. */
+  readonly progress: number;
+  /** Drag distance past either end of `progress`; usually `0`. */
+  readonly overshoot: number;
+  /** Latest normalized velocity in progress units per second. */
+  readonly velocity: number;
+  /** Current operation lifecycle phase. */
+  readonly phase: OriginOperationPhase;
+  /** Selected operation outcome. */
+  readonly intent: OriginOperationIntent;
+}
+
+/**
+ * Node-local information supplied to component-owned action factories.
+ *
+ * There is deliberately no global `current` or `active` view. The component
+ * handling the event is the origin represented by this context.
+ */
+export interface OriginContext {
+  /** Unique key of the mounted node that owns the interaction. */
+  readonly nodeKey: string;
+  /** Recipe used to create the origin node. */
+  readonly view: OriginView;
+  /** Whether this retained history entry has a mounted previous instance. */
+  readonly canGoBack: boolean;
+  /** Recipe belonging to the retained previous instance, when available. */
+  readonly previous?: OriginView;
+  /** Recipes belonging to all retained instances preceding this node. */
+  readonly history: readonly OriginView[];
+}
+
+/** Options controlling how a manually managed operation is resolved. */
+export interface OriginFinishOptions {
+  /**
+   * Override the choreography's progress/velocity decision. Omit it to use the
+   * choreography's commit thresholds.
+   */
+  commit?: boolean;
+  /**
+   * Whether to run the settling spring before finalizing the graph.
+   *
+   * @defaultValue `true`
+   */
+  animate?: boolean;
+}
+
+/** Imperative controller for one mounted, live operation edge. */
+export interface OriginOperationHandle {
+  /** Identity of the live operation controlled by this handle. */
+  readonly id: number;
+  /** Key of the source node that created the operation. */
+  readonly originKey: string;
+  /** Key of the newly mounted or retained target node. */
+  readonly targetKey: string;
+  /**
+   * The operation's selected outcome. It becomes `commit` or `cancel`
+   * synchronously when `finish()` or `cancel()` is called, before settling.
+   */
+  readonly intent: OriginOperationIntent;
+  /**
+   * Set interactive progress and optional velocity.
+   *
+   * Progress is clamped to `0..1`; any excess is reported to choreographies as
+   * `overshoot`. Velocity is normalized to progress units per second and is
+   * used by the choreography's flick threshold.
+   */
+  update(progress: number, velocity?: number): void;
+  /**
+   * Select commit/cancel, run the settling spring, and finalize the scene.
+   *
+   * @returns `true` when the target was retained, otherwise `false`.
+   */
+  finish(options?: OriginFinishOptions): Promise<boolean>;
+  /** Cancel the operation and remove its target branch. */
+  cancel(options?: Pick<OriginFinishOptions, "animate">): Promise<void>;
+}
+
+/** Options used to create an independent origin scene. */
+export interface CreateOriginSceneOptions {
+  /**
+   * One initial root recipe, or several independent roots rendered in the same
+   * flat scene. Most applications begin with one root.
+   */
+  initial: OriginView | readonly OriginView[];
+}
+
+/**
+ * A self-contained scene graph, view-recipe history, and animation compositor.
+ *
+ * Multiple scenes may coexist and do not share nodes, history, or operations.
+ */
+export interface OriginScene {
+  /** Reactive snapshot of every currently mounted node. */
+  readonly nodes: ComputedRef<readonly OriginSceneNode[]>;
+  /** Reactive snapshot of every live animation/gesture operation. */
+  readonly operations: ComputedRef<readonly OriginOperation[]>;
+  /** Keys of visible operation-graph roots; parked history is excluded. */
+  readonly roots: Readonly<ShallowRef<readonly string[]>>;
+  /** Return the node-local action context for a mounted node key. */
+  contextFor(nodeKey: string): OriginContext;
+  /**
+   * Create a forward target or reveal a retained back target, then return
+   * manual control of its operation.
+   *
+   * @throws If the origin is missing, parked/exposed and inert, or already owns
+   * an outgoing operation.
+   */
+  begin(
+    originKey: string,
+    action: OriginAction,
+  ): Promise<OriginOperationHandle>;
+  /**
+   * Resolve a target and commit it programmatically using the settling spring.
+   *
+   * @returns `true` once the target has been committed.
+   */
+  perform(originKey: string, action: OriginAction): Promise<boolean>;
+  /** @internal Register or unregister a scene node's host element. */
+  registerElement(nodeKey: string, element: HTMLElement | null): void;
+  /** @internal Register or unregister the scene container used for measurement. */
+  registerContainer(element: HTMLElement | null): void;
+  /** @internal Calculate the fully composited inline style for one node host. */
+  styleForNode(nodeKey: string): CSSProperties;
+  /** @internal Determine whether a node should currently receive pointer input. */
+  isNodeInteractive(nodeKey: string): boolean;
+}
+
+/**
+ * Mutable operation storage used by the scene implementation.
+ *
+ * @internal
+ */
+export interface MutableOriginOperation {
+  /** Unique operation identity. */
+  id: number;
+  /** Origin node key. */
+  originKey: string;
+  /** Newly created or retained target node key. */
+  targetKey: string;
+  /** Original history entry targeted before visual-edge rewrites. */
+  entryTargetKey: string;
+  /** Visual choreography for this edge. */
+  choreography: OriginChoreography;
+  /** Target stacking relationship. */
+  placement: OriginPlacement;
+  /** Retained-history behavior selected for this operation. */
+  history: OriginHistoryMode;
+  /** Normalized progress. */
+  progress: number;
+  /** Drag distance past either end of `progress`. */
+  overshoot: number;
+  /** Normalized velocity. */
+  velocity: number;
+  /** Current lifecycle phase. */
+  phase: OriginOperationPhase;
+  /** Selected outcome. */
+  intent: OriginOperationIntent;
+  /** Measured origin bounds, when an element was available. */
+  originRect?: OriginRect;
+  /** Measured target bounds, after the target mounted. */
+  targetRect?: OriginRect;
+}
+
+/** Public props accepted by the `OriginScene` renderer component. */
+export interface OriginSceneProps {
+  /** Scene instance whose flat component nodes should be rendered. */
+  scene: OriginScene;
+}
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Claude	caf2ad692a	Restore native scrolling and reliable recognition; add feel tests The previous round regressed the demo against main: dropped frames while a finger drags, and swipes ignored when they start imperfectly. Frame drops: hosts used touch-action: manipulation plus a blocking touchmove listener, so Chrome waited for JavaScript on every touch move (~30% of frames over 20ms in a drag, p95 28ms). Hosts again use per-axis touch-action like main (pan-y for horizontal gestures, and so on), and attach no touch listener. Flaky recognition: an irreversible decision after 6px dropped swipes with a wobbly or backward start. Recognition again measures from the pointer-down point until the pointer lifts, as on main. Scrolling beside gestures, natively: - .from.scrollEdge() uses direction-specific touch-action while its scroller is at the edge (pan-x pan-down for drag-down at the top), the pull-to-refresh pattern from the Pointer Events spec. A passive scroll listener keeps it current; no touch handling blocks the browser. - Where directional values are unsupported (Safari), scroll-edge gestures alone fall back to claiming touches at the browser's first cancelable touchmove. - Hosts publish touch-action as --nvo-touch-action and the stylesheet applies it to descendants, so nested scroll containers keep it and horizontal swipes over lists are not cancelled. Ignored subtrees get touch-action: auto back. - Bindings gain listeners and ref (spread on the host); the components use them. Feel tests (npm run test:feel): Chromium with emulated touch checks recognition on ten human-like traces, frame pacing budgets while dragging (p95 <= 20ms, <= 5% over 20ms) for a swipe and a scroll-edge dismiss, and the behaviour checks. Against the previous code they fail on exactly the reported regressions; now 23/23 pass. On the demo, all traces match main and drag frame pacing matches or beats it. Commit thresholds are unchanged (0.25 distance, 0.2 flick). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Faarh2Ts6StJPcz2mRiHiR	2026-11-03 05:56:26 +00:00
Claude	6889fc0112	Make gestures cooperate with scrolling and feel smoother From an app built on core-v2: Scrolling (#3, #4, #14) - Each recognizer locks onto a touch within its first 6px: along its axis and direction it holds the touch, otherwise it lets go. A new onTouchmove binding cancels native scrolling only while a recognizer holds the touch, so hosts use touch-action: manipulation and one vertical gesture no longer disables vertical scrolling. Several gestures on one host share touches through the same rule. - .from.scrollEdge(scroller, edge) admits drag-to-dismiss only while a scroller is at the edge (#5). Feel - recognition.distance sets what counts as full progress: pixels, a CSS length, or a measuring function (#6). - Choreographies receive overshoot, the drag past either end of the clamped progress, and the settling spring starts from it (#7). - Velocity is the least-squares trend of the last 100ms (#8). - Defaults retuned to commitThreshold 0.25 and commitVelocity 0.2; the slide presets use them (#9). - Choreographies may set spring stiffness and damping (#10). Hooks and helpers - .onArm()/.onDisarm() run during a drag when releasing would start or stop committing (#12). - startedIn, nearEdge, atScrollEdge, anyOf, allOf start predicates (#15). - Development builds warn when an operation's first frame moves a node that was visibly at rest, the one-frame "pop" of mismatched open and close choreographies (#16). Docs: scrolling, ignored elements, animation performance, haptics, and operating-system edge gestures including CloseWatcher/popstate for PWAs (#11, #17, #18). Verification: a Chromium harness with emulated touch (verify/browser) checks swipes over scrollers, native scrolling beside gestures, scroll-edge dismissal, onCommit inside pointerup, and the continuity warning. Reverting the earlier capture fix makes it fail exactly as reported ("none of the handles work"). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Faarh2Ts6StJPcz2mRiHiR	2026-10-31 08:22:11 +00:00
Claude	d4d7feb3b7	Fix touch gestures cancelling, backward flicks, and late onCommit - Only the host's own lostpointercapture cancels a gesture. Taking capture makes the touched child lose its implicit touch capture, and that bubbling event was cancelling every touch gesture immediately. - A flick at least commitVelocity fast now decides by its direction: backward cancels even past the distance threshold, forward commits. Slower releases still decide by distance. - Pointer-up finishes an already-begun operation without awaiting, so onCommit runs inside the pointer-up event, where iOS still allows haptics, audio, and clipboard writes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Faarh2Ts6StJPcz2mRiHiR	2026-10-31 05:41:51 +00:00
Claude	7033814550	Trim per-release overhead in the scene Only re-measure the viewport at begin() when a container is mounted, and only allocate waiting machinery when an interrupted finish() actually needs to wait for a later release. Interrupted releases now resolve with the final decided outcome in every case. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Faarh2Ts6StJPcz2mRiHiR	2026-10-16 04:28:43 +00:00
Claude	a46c411ec4	Move core-v2 tests into packages/core-v2/tests Tests no longer sit next to the implementation. They import the package through ../src, the root tsconfig still type-checks them, and the package build and declarations cover only src/. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Faarh2Ts6StJPcz2mRiHiR	2026-10-16 04:24:47 +00:00
Claude	1924d4b52b	Close a revealed page's open drawer when its back is cancelled discardOutgoing skipped finished resting edges, so a persistAtRest drawer opened by a node revealed during a back operation stayed attached after that back was cancelled and the node returned to history. Found by the property tests (1000-seed run). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Faarh2Ts6StJPcz2mRiHiR	2026-10-16 04:10:53 +00:00
Claude	b6f782d8af	Fix stuck gestures and scene graph races; honour commitVelocity Gestures - Cancel a captured gesture on lostpointercapture, on a new primary pointer-down, and when its component unmounts, so operations are never left stuck mid-transition. Bindings gain onLostpointercapture. - Warn (console.warn) when navigate() fails or the scene rejects an operation; stay quiet when two recognizers race for one origin. - OriginGesture and OriginGestureSurface props are reactive. Changes apply from the next pointer-down; recognizers are kept per list position so re-renders never interrupt a drag. - Remove the legacy direction/edge/threshold/action gesture form (OriginGestureOptions, legacy OriginGesture props, MaybeOriginAction). Scene - Honour choreography commitVelocity (default 0.3, as before). - Scene errors are OriginSceneError with a stable code. - update() during settling now really catches an operation: the spring stops, and only the latest finish() decides the outcome. - Fix graph corruption found by the new property tests, all present on main: replacements escaping a cancelled push, edges left dangling when their current target differs from the original one, revealed targets keeping operations after their back is cancelled, history pointing at removed entries after replace, visual cycles from back through an undecided replace, exposed nodes reactivated as active, and a cancel cascade that could empty the whole scene. Tests - Add property tests checking structural invariants after every step of random operation sequences and pointer streams (PROPERTY_SEEDS). - Add recognizer tests for stuck gestures, warnings, reactive props, and commitVelocity. Drop the main-comparison suites; keep benchmarks. Also fix the origins demo's two pre-existing type errors. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Faarh2Ts6StJPcz2mRiHiR	2026-10-16 04:09:57 +00:00
Claude	46f030630b	Speed up compositing and gesture start without behavior changes - Memoize each operation's choreography effect set in a computed, so nodes sharing an edge stop re-evaluating it (linear, not quadratic, in chain depth). - Cache the scene viewport and refresh it from a ResizeObserver and at each begin(), instead of measuring the container per node per frame. - Index operations by origin key so outgoing lookups no longer scan every operation; all map changes go through attach()/detach(). - Resolve px and % gesture edge distances arithmetically; only other CSS lengths use the off-screen probe. Verified in Chromium to match the probe within its 1/64px layout rounding. The differential suites against main still match exactly. Benchmarks vs main: styleForNode 2.0x (3 live ops) and 2.4x (10 live ops), rendered frames 1.14x. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Faarh2Ts6StJPcz2mRiHiR	2026-10-16 03:26:51 +00:00
Claude	8448e910ed	Add .onCommit() to the gesture builder `.onCommit(handler)` is available at every builder stage after the direction, returns the same stage, and accumulates handlers in order. Handlers run once, synchronously at release, when the operation commits and before the settling animation, with the same context `.complete()` receives. A throwing handler is reported without stopping later handlers or the operation. Intended for haptic feedback such as `navigator.vibrate`. Named onCommit rather than then so builder stages never become thenables. The builder now threads one frozen draft through its stages. OriginOperationHandle gains a read-only `intent`, which the recognizer reads right after finish() to know whether the release committed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Faarh2Ts6StJPcz2mRiHiR	2026-10-16 03:08:12 +00:00
Claude	511e58c198	Consolidate core-v2 modules and move scene logic onto classes - Merge the small modules into 12 files: shared, choreography, navigation, scene/{types,graph,scene}, gesture/{definition,recognizer}. - SceneGraph now owns the begin/update/commit/cancel history rules as methods, with the step helpers as private methods. - createOriginScene returns a markRaw'd Scene class; operation handles are an OperationHandle class instead of inline object literals. - GestureRecognizer gains static create()/policyFor() factories, absorbing the separate policy module. - Pure helpers used by classes (matchesStart, pointOf, stepSpring, composeNodeStyle, nodeEffectLayers, shouldCommit, ...) are exported consts so they can be tested directly. - Add haptics tests showing where navigator.vibrate can be triggered. Public exports, types, and behavior are unchanged; the differential suites against main still pass. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Faarh2Ts6StJPcz2mRiHiR	2026-10-16 02:49:56 +00:00
Claude	329271691c	Restructure core-v2 into layered modules Rewrite the core-v2 internals without changing the public API or runtime behavior. The four large files (types, scene, motion, gesture) become layered modules with one responsibility each: - shared/: geometry and environment helpers - view/: originView recipes - choreography/: effect types, presets, and composeEffects compositing - actions/: forward/back/replace/above/under via one overload resolver - scene/: SceneGraph storage, transitions (history rules), compositor (styles and interactivity), spring (pure stepper + rAF driver), and createOriginScene, which only wires them and owns async timing - composables/: useOrigin and the node-scope injection key - gesture/: builder, definition->policy normalization, start admission, DirectionalTracker, and a GestureRecognizer session state machine replacing fifteen loose closure variables - components/: renderers and gesture hosts, plus their prop types Verification (packages/core-v2/verify): differential fuzzing drives main and this branch with identical random operation sequences and pointer streams and requires identical scene state, styles, contexts, callbacks, and promise results at every step. It caught every planted mutation that applied. Benchmarks are at parity. Also fix a pre-existing test that called the defineProps macro inside a runtime defineComponent, and correct API.md's description of the flick commit threshold to match the runtime. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Faarh2Ts6StJPcz2mRiHiR	2026-10-16 01:15:12 +00:00
Harvmaster	d8303107fb	Fix prop typing	2026-08-12 00:28:01 +00:00
Harvmaster	435ac9a899	Add core-v2 skill and make installable	2026-07-31 08:10:01 +00:00
Harvmaster	056f341cd3	Increase complexity of test demo	2026-07-31 07:51:50 +00:00
Harvmaster	55dad11b25	V2: Origin based animations, Gesture Builder, New Demo, non-url-based-routing. Massive improvements.	2026-07-25 05:57:26 +00:00
Harvmaster	5a514906eb	Separate out into files	2026-07-22 11:37:46 +00:00
Harvmaster	6aed7606ad	Add experiments folder. Add usage.md and SKILL.md. Fix Sheet interactions and add dynamic sheet mode.	2026-07-22 07:04:39 +00:00
Harvmaster	bfe364c57d	Move components.ts into many SFC files	2026-07-22 02:38:01 +00:00
Harvmaster	18baa96848	Add prettier. Format.	2026-07-22 02:12:05 +00:00
Harvmaster	d28b09dc21	Add minimal reproduction of compositor bug	2026-07-22 01:51:22 +10:00
Harvmaster	c27e5906ca	Add profiler	2026-07-22 01:03:27 +10:00
Harvmaster	db864af147	Fix frame pacing	2026-07-21 21:59:26 +10:00
Harvmaster	7d134ff8c9	Improve caching	2026-07-21 18:45:59 +10:00
Harvmaster	92c61abcfe	Add docs and further stress tests to the demo	2026-07-21 17:56:58 +10:00
Harvmaster	9af84760fa	Fix animation stale reference	2026-07-21 16:03:28 +10:00