@sigx/lynx-navigation 0.1.0 → 0.1.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Andreas Ekdahl
+Copyright (c) 2025-2026 Andreas Ekdahl
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -0,0 +1,355 @@
+# @sigx/lynx-navigation
+
+Type-first native navigator for [SignalX](https://github.com/signalxjs) on
+Lynx. Define routes once with `defineRoutes`, augment the `Register`
+interface, and every navigator API — `useNav`, `useParams`, `useSearch`,
+`<Link>`, `<Tabs.Screen>`, `<Drawer>` — picks up precise per-route
+param/search inference.
+
+The navigator ships native UI primitives (Stack, Tabs, Drawer, modal
+presentation), focus hooks, deep-link integration, lazy routes, screen
+options, and persistence — all reactive via sigx signals, all typed.
+
+> **Status — 1.0 candidate.** Public surface is frozen; every export below
+> is locked by the test suite in `__tests__/public-surface.test.ts`. The
+> remaining work before flipping `private: false` is benchmarks against
+> the legacy switch-based pattern and the publish flow.
+
+## Install
+
+```bash
+pnpm add @sigx/lynx-navigation
+```
+
+Peer-deps: `@sigx/lynx`, `@sigx/lynx-motion`. Optional but recommended:
+[`@sigx/lynx-linking`](../lynx-linking) for deep-link wiring,
+[`@sigx/lynx-storage`](../lynx-storage) for stack persistence.
+
+## Quick start
+
+```tsx
+// src/routes.ts
+import { defineRoutes } from '@sigx/lynx-navigation';
+import { z } from 'zod';
+import { Home } from './screens/Home';
+import { Profile } from './screens/Profile';
+
+export const routes = defineRoutes({
+    home: { component: Home },
+    profile: {
+        component: Profile,
+        params: z.object({ id: z.string() }),
+        path: '/users/:id',
+    },
+});
+
+declare module '@sigx/lynx-navigation' {
+    interface Register { routes: typeof routes }
+}
+```
+
+```tsx
+// src/App.tsx
+import { NavigationRoot, Stack } from '@sigx/lynx-navigation';
+import { routes } from './routes';
+
+export const App = () => (
+    <NavigationRoot routes={routes} initialRoute="home">
+        <Stack />
+    </NavigationRoot>
+);
+```
+
+`<NavigationRoot>` creates a fresh navigator instance and provides it via
+sigx's `defineProvide`, so multiple roots (or tests) get isolated state.
+`<Stack>` renders the top entry, and during a push/pop the previous entry
+too — driven by an MT-side `SharedValue` so per-frame interpolation never
+crosses to BG.
+
+## API reference
+
+### `defineRoutes(routes)`
+
+Locks in a typed route map. Each entry is a `RouteDefinition`:
+
+```ts
+interface RouteDefinition<P = unknown, S = unknown> {
+    component: ComponentLike;        // sigx component or lazy(...)
+    params?: StandardSchemaV1<P>;    // zod / valibot / arktype / etc.
+    search?: StandardSchemaV1<S>;
+    path?: string;                   // for deep-link parsing
+    presentation?: Presentation;     // 'card' (default) | 'modal' | 'fullScreen' | 'transparent-modal'
+}
+```
+
+Augment `Register.routes` once with the return value of `defineRoutes`
+and every other API gets typed.
+
+### `<NavigationRoot>`
+
+| Prop | Default | Notes |
+|---|---|---|
+| `routes` | required | Output of `defineRoutes(...)`. |
+| `initialRoute` | first key | Starting route at the bottom of the stack. |
+| `initialParams` / `initialSearch` | `{}` | Required when `initialRoute` declares a schema. |
+| `animated` | `true` | Disable in tests so navigations commit synchronously. |
+| `edgeSwipeEnabled` | `true` | iOS edge-swipe-back. |
+
+### `<Stack>`
+
+Renders the topmost stack entry plus the entry beneath it during
+transitions. No props — driven entirely by the navigator state.
+
+### `<Screen>`
+
+Per-route slot container. Lets a screen declare its header / tab-bar item
+JSX inline alongside its body:
+
+```tsx
+const Profile = component(() => () => (
+    <Screen>
+        <Screen.Header>
+            <view><text>Custom header</text></view>
+        </Screen.Header>
+        <Screen.HeaderRight>
+            <text bindtap={save}>Save</text>
+        </Screen.HeaderRight>
+        <Screen.TabBarItem>
+            {({ active }) => <text style={{ opacity: active ? 1 : 0.6 }}>Me</text>}
+        </Screen.TabBarItem>
+
+        <view><text>profile body</text></view>
+    </Screen>
+));
+```
+
+All sub-slots are optional. Anything not declared falls back to the
+navigator's default chrome.
+
+### `<Header>`
+
+Default navigator header. Reads the focused entry's `<Screen.Header>`
+slot if set, otherwise renders `headerLeft | title | headerRight` with a
+back button as the default `headerLeft` when `nav.canGoBack` is true.
+Pulls `title` / `headerShown` / `gestureEnabled` from the focused
+screen's `useScreenOptions(...)` registration.
+
+```tsx
+<NavigationRoot routes={routes} initialRoute="home">
+    <Header />
+    <Stack />
+</NavigationRoot>
+```
+
+### `<Tabs>` + `<Tabs.Screen>` + `<TabBar>`
+
+Persistent tab navigator. Each tab keeps its own stack across switches.
+
+```tsx
+<Tabs initialTab="home">
+    <Tabs.Screen name="home" component={HomeStack} label="Home" />
+    <Tabs.Screen name="profile" component={ProfileStack} label="Me"
+        accessibilityLabel="Profile tab" />
+    <TabBar />
+</Tabs>
+```
+
+`<TabBar>` is the default chrome — kebab-case `accessibility-*` props for
+screen readers, opacity-based active marker, tap to switch. Pass
+`renderTab={(info, ctx) => <view bindtap={ctx.onPress}>…</view>}` to
+fully override per-item rendering.
+
+`useTabs()` returns `{ active, setActive, tabs }` — reactive.
+
+### `<Drawer>`
+
+Off-canvas sidebar navigator.
+
+```tsx
+<Drawer sidebar={() => <view><text>Menu</text></view>}>
+    <Stack />
+</Drawer>
+```
+
+`useDrawer()` returns `{ isOpen, open(), close(), toggle() }`. The
+sidebar is laid out absolutely on the left and toggled via `display`.
+Gesture-driven open and slide-in animation are deferred to apps — wrap
+your sidebar JSX in a motion component if you want it.
+
+### `useNav()`
+
+```ts
+const nav = useNav();
+// readonly + reactive
+nav.current      // top StackEntry
+nav.stack        // StackEntry[]
+nav.canGoBack    // boolean
+
+// mutators
+nav.push('profile', { id: 'alice' });
+nav.push('profile', { id: 'alice' }, { tab: 'about' });
+nav.replace('home');
+nav.pop();
+nav.pop(2);
+nav.popTo('home');
+nav.popToRoot();
+nav.reset([{ name: 'home', params: {}, search: {} }]);
+```
+
+Per-route overloaded — `params` is required iff the route declares a
+`params` schema, and the value is type-checked against it.
+
+### `<Link>`
+
+JSX flavor of `nav.push`:
+
+```tsx
+<Link to="profile" params={{ id: 'alice' }} search={{ tab: 'about' }}>
+    Open Alice
+</Link>
+<Link to="home" replace>Reset</Link>
+```
+
+Same per-route conditional typing as `nav.push`.
+
+### `useParams(name)` / `useSearch(name)`
+
+Typed accessors for the *currently-mounted* route. Calling with the wrong
+route name is a TS error.
+
+```ts
+const { id } = useParams('profile');         // { id: string }
+const { tab } = useSearch('profile');        // { tab: 'posts' | 'about' }
+```
+
+### `useFocusEffect(handler)` / `useIsFocused()`
+
+`useIsFocused()` is a reactive boolean — `true` while this screen is the
+visible top of its navigator. `useFocusEffect(() => () => cleanup)` runs
+`handler` on focus and the returned function on blur. Use these to mount
+side-effects (analytics, subscriptions, video playback) only while the
+screen is visible.
+
+### `useHardwareBack(handler)`
+
+Subscribe to Android system-back / iOS edge-swipe. Return `true` to
+swallow the press, `false`/`undefined` to let the navigator handle it.
+
+### `useScreenOptions(options | () => options)`
+
+Imperatively merge `ScreenOptions` (`title`, `headerShown`,
+`gestureEnabled`) for the current screen. Pass a plain object for a
+one-time merge; pass a function and every signal touched inside it is
+tracked, so the options re-merge on change.
+
+```tsx
+const Profile = component(() => {
+    const { id } = useParams('profile');
+    useScreenOptions(() => ({ title: `User ${id}` }));
+    return () => <view><text>profile</text></view>;
+});
+```
+
+### `useLinkingNav(options?)`
+
+Bridges `@sigx/lynx-linking` URL events into the navigator. Call once
+inside a `<NavigationRoot>` subtree. Options:
+
+| Key | Notes |
+|---|---|
+| `prefixes` | Schemes to strip before parsing (`'myapp://'`, `'https://myapp.com'`). |
+| `onURL(url, nav)` | Intercept before default dispatch. Call `nav.push` yourself to handle. |
+| `onUnmatched(url)` | Fired for URLs no route matches. Default: silent. |
+| `replaceInitial` | Use `replace` for cold-start URLs (default `true`). |
+
+### `useNavSerializer(options)`
+
+Persist the navigator's stack across launches. Adapter is yours to
+implement — `@sigx/lynx-storage`, MMKV, AsyncStorage, anything.
+
+```ts
+useNavSerializer({
+    storage: {
+        async load() { return JSON.parse(await Storage.get('nav')); },
+        async save(snap) { await Storage.set('nav', JSON.stringify(snap)); },
+    },
+    debounceMs: 250,
+    onRestored: (snap) => console.log('restored', snap.stack.length, 'entries'),
+    onRestoreError: (reason, err) => console.warn('restore failed', reason, err),
+});
+```
+
+Snapshots carry a `version` field (`NAV_SNAPSHOT_VERSION`) — bump it when
+the schema changes and `onRestoreError` fires `'version'`.
+
+### `hrefFor(name, params?, search?)` / `parseHref(input, routes)`
+
+Build and parse path-style URLs declared by each route's `path` template:
+
+```ts
+const href = hrefFor('profile', { id: 'alice' }, { tab: 'posts' });
+// → "/users/alice?tab=posts"
+
+const parsed = parseHref('/users/bob?tab=about', routes);
+// → { name: 'profile', params: { id: 'bob' }, search: { tab: 'about' } }
+```
+
+### Lazy routes
+
+Routes can pass a `lazy(...)` component from `@sigx/lynx` (re-exports
+`@sigx/runtime-core`'s `lazy` + `<Suspense>`). The navigator calls
+`.preload()` on push so the chunk is fetched before the screen mounts:
+
+```tsx
+import { lazy } from '@sigx/lynx';
+
+export const routes = defineRoutes({
+    home: { component: Home },
+    profile: { component: lazy(() => import('./screens/Profile')) },
+});
+```
+
+Wrap your `<Stack>` in `<Suspense fallback={…}>` to show a fallback while
+the chunk loads. The bundler (rspeedy/rspack) needs to produce
+Lynx-loadable chunks for the layered MT-bundle — see the `examples/`
+folder for a working setup.
+
+## Modal presentation
+
+Set `presentation: 'modal' | 'fullScreen' | 'transparent-modal'` on a
+route definition. Modals ship as stack entries with a different
+transition (bottom-sheet style) — there's no separate `<Modal>`
+navigator. Use `nav.pop()` to dismiss.
+
+## Testing
+
+```ts
+import { render, act } from '@sigx/lynx-testing';
+
+render(
+    <NavigationRoot routes={routes} initialRoute="home" animated={false}>
+        <Stack />
+    </NavigationRoot>,
+);
+```
+
+Pass `animated={false}` so navigations commit synchronously — `lynx-testing`
+has no MT runtime so the slide-from-right transition never completes
+otherwise. Then `act(() => nav.push(...))` immediately re-renders.
+
+## Runtime gotchas
+
+- **`useMainThreadRef` will crash on BG.** Refs returned by sigx that bind
+  to MT-only host nodes blow up if you read them outside `runOnMainThread`.
+- **`runOnBackground` closure capture.** Variables captured in the body
+  are snapshot at call time. Read signals via `.value` *inside* the body,
+  not at definition.
+- **`SharedValue` writes must come from MT worklets.** The transition
+  layer enforces this — pushing to a `SharedValue` from BG silently no-ops.
+- **Lynx has no `z-index`.** Layering is document-order. The navigator
+  renders the underneath entry first, then the top entry — overlap them
+  via `position: absolute` and an explicit offset.
+
+## License
+
+MIT

package/dist/components/Drawer.d.ts

@@ -0,0 +1,58 @@
+/**
+ * `<Drawer>` — minimal off-canvas drawer navigator.
+ *
+ * Usage:
+ *
+ * ```tsx
+ * <NavigationRoot routes={routes}>
+ *   <Drawer
+ *     sidebar={() => <view><text>Menu</text></view>}
+ *   >
+ *     <Stack />
+ *   </Drawer>
+ * </NavigationRoot>
+ * ```
+ *
+ * `useDrawer()` from inside any descendant gives `{ isOpen, open(), close(),
+ * toggle() }`. The sidebar is laid out absolutely on the left and is
+ * visible whenever `isOpen` is true.
+ *
+ * Scope: this slice ships the state primitive + the bare-bones layout.
+ * Gesture-driven open (edge swipe from the left) and MTS slide-in are out
+ * of scope — the app shell can wrap its sidebar JSX in its own transition.
+ *
+ * Design note: the sidebar is passed as a render function via the
+ * `sidebar` slot prop rather than a `<Drawer.Sidebar>` child. Mixing
+ * "register-yourself-as-a-fill" children with the parent's own visible
+ * layout creates a feedback loop in sigx's reactive scope (the parent's
+ * render reads the fill, child's setup writes it, parent re-renders,
+ * child re-mounts, …). A scoped slot avoids that entirely and the API
+ * is identical at the call site.
+ *
+ * `default` slot is the main content (almost always a `<Stack>`).
+ */
+import { type Define } from '@sigx/lynx';
+/** Reactive controller returned by `useDrawer()`. */
+export interface DrawerNav {
+    /** True when the drawer is currently visible. Reactive. */
+    readonly isOpen: boolean;
+    /** Opens the drawer. */
+    open(): void;
+    /** Closes the drawer. */
+    close(): void;
+    /** Toggles between open and closed. */
+    toggle(): void;
+}
+/**
+ * Access the enclosing Drawer navigator. Throws when called outside
+ * `<Drawer>`.
+ */
+export declare const useDrawer: import("@sigx/runtime-core").InjectableFunction<DrawerNav>;
+type DrawerProps = Define.Prop<'initialOpen', boolean> & Define.Slot<'sidebar'> & Define.Slot<'default'>;
+export declare const Drawer: import("@sigx/runtime-core").ComponentFactory<DrawerProps, void, {
+    sidebar: () => import("@sigx/runtime-core").JSXElement | import("@sigx/runtime-core").JSXElement[] | null;
+} & {
+    default: () => import("@sigx/runtime-core").JSXElement | import("@sigx/runtime-core").JSXElement[] | null;
+}>;
+export {};
+//# sourceMappingURL=Drawer.d.ts.map

package/dist/components/Drawer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Drawer.d.ts","sourceRoot":"","sources":["../../src/components/Drawer.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,EAKH,KAAK,MAAM,EAEd,MAAM,YAAY,CAAC;AAEpB,qDAAqD;AACrD,MAAM,WAAW,SAAS;IACtB,2DAA2D;IAC3D,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,wBAAwB;IACxB,IAAI,IAAI,IAAI,CAAC;IACb,yBAAyB;IACzB,KAAK,IAAI,IAAI,CAAC;IACd,uCAAuC;IACvC,MAAM,IAAI,IAAI,CAAC;CAClB;AAED;;;GAGG;AACH,eAAO,MAAM,SAAS,4DAIpB,CAAC;AAEH,KAAK,WAAW,GACV,MAAM,CAAC,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC,GACnC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,GACtB,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AAE7B,eAAO,MAAM,MAAM;;;;EAmDjB,CAAC"}

package/dist/components/Drawer.js

@@ -0,0 +1,76 @@
+import { jsx as _jsx, jsxs as _jsxs } from "@sigx/lynx/jsx-runtime";
+/**
+ * `<Drawer>` — minimal off-canvas drawer navigator.
+ *
+ * Usage:
+ *
+ * ```tsx
+ * <NavigationRoot routes={routes}>
+ *   <Drawer
+ *     sidebar={() => <view><text>Menu</text></view>}
+ *   >
+ *     <Stack />
+ *   </Drawer>
+ * </NavigationRoot>
+ * ```
+ *
+ * `useDrawer()` from inside any descendant gives `{ isOpen, open(), close(),
+ * toggle() }`. The sidebar is laid out absolutely on the left and is
+ * visible whenever `isOpen` is true.
+ *
+ * Scope: this slice ships the state primitive + the bare-bones layout.
+ * Gesture-driven open (edge swipe from the left) and MTS slide-in are out
+ * of scope — the app shell can wrap its sidebar JSX in its own transition.
+ *
+ * Design note: the sidebar is passed as a render function via the
+ * `sidebar` slot prop rather than a `<Drawer.Sidebar>` child. Mixing
+ * "register-yourself-as-a-fill" children with the parent's own visible
+ * layout creates a feedback loop in sigx's reactive scope (the parent's
+ * render reads the fill, child's setup writes it, parent re-renders,
+ * child re-mounts, …). A scoped slot avoids that entirely and the API
+ * is identical at the call site.
+ *
+ * `default` slot is the main content (almost always a `<Stack>`).
+ */
+import { component, defineInjectable, defineProvide, signal, } from '@sigx/lynx';
+/**
+ * Access the enclosing Drawer navigator. Throws when called outside
+ * `<Drawer>`.
+ */
+export const useDrawer = defineInjectable(() => {
+    throw new Error('[lynx-navigation] useDrawer() called outside of a <Drawer> component.');
+});
+export const Drawer = component(({ props, slots }) => {
+    // `isOpenSig` uses the `{value}` wrapper pattern — sigx's `signal()` of
+    // a primitive returns a proxy that requires `.value` reads; wrapping in
+    // an object makes the proxy carry a mutable boolean.
+    const isOpenSig = signal({
+        value: props.initialOpen === true,
+    });
+    const nav = {
+        get isOpen() {
+            return isOpenSig.value;
+        },
+        open() {
+            isOpenSig.value = true;
+        },
+        close() {
+            isOpenSig.value = false;
+        },
+        toggle() {
+            isOpenSig.value = !isOpenSig.value;
+        },
+    };
+    defineProvide(useDrawer, () => nav);
+    return () => {
+        const open = isOpenSig.value;
+        return (_jsxs("view", { style: { width: '100%', height: '100%' }, children: [_jsx("view", { style: { width: '100%', height: '100%' }, children: slots.default?.() }), _jsx("view", { style: {
+                        position: 'absolute',
+                        left: 0,
+                        top: 0,
+                        bottom: 0,
+                        display: open ? 'flex' : 'none',
+                    }, children: slots.sidebar?.() })] }));
+    };
+});
+//# sourceMappingURL=Drawer.js.map

package/dist/components/Drawer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Drawer.js","sourceRoot":"","sources":["../../src/components/Drawer.tsx"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,EACH,SAAS,EACT,gBAAgB,EAChB,aAAa,EACb,MAAM,GAGT,MAAM,YAAY,CAAC;AAcpB;;;GAGG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,gBAAgB,CAAY,GAAG,EAAE;IACtD,MAAM,IAAI,KAAK,CACX,uEAAuE,CAC1E,CAAC;AACN,CAAC,CAAC,CAAC;AAOH,MAAM,CAAC,MAAM,MAAM,GAAG,SAAS,CAAc,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE;IAC9D,wEAAwE;IACxE,wEAAwE;IACxE,qDAAqD;IACrD,MAAM,SAAS,GAA+B,MAAM,CAAC;QACjD,KAAK,EAAE,KAAK,CAAC,WAAW,KAAK,IAAI;KACpC,CAAC,CAAC;IAEH,MAAM,GAAG,GAAc;QACnB,IAAI,MAAM;YACN,OAAO,SAAS,CAAC,KAAK,CAAC;QAC3B,CAAC;QACD,IAAI;YACA,SAAS,CAAC,KAAK,GAAG,IAAI,CAAC;QAC3B,CAAC;QACD,KAAK;YACD,SAAS,CAAC,KAAK,GAAG,KAAK,CAAC;QAC5B,CAAC;QACD,MAAM;YACF,SAAS,CAAC,KAAK,GAAG,CAAC,SAAS,CAAC,KAAK,CAAC;QACvC,CAAC;KACJ,CAAC;IAEF,aAAa,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC;IAEpC,OAAO,GAAG,EAAE;QACR,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,CAAC;QAC7B,OAAO,CACH,gBAAM,KAAK,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,aAE1C,eAAM,KAAK,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YACzC,KAAK,CAAC,OAAO,EAAE,EAAE,GACf,EAKP,eACI,KAAK,EAAE;wBACH,QAAQ,EAAE,UAAU;wBACpB,IAAI,EAAE,CAAC;wBACP,GAAG,EAAE,CAAC;wBACN,MAAM,EAAE,CAAC;wBACT,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM;qBAClC,YAEA,KAAK,CAAC,OAAO,EAAE,EAAE,GACf,IACJ,CACV,CAAC;IACN,CAAC,CAAC;AACN,CAAC,CAAC,CAAC"}

package/dist/components/EdgeBackHandle.js

@@ -0,0 +1,144 @@
+import { jsx as _jsx } from "@sigx/lynx/jsx-runtime";
+import { component, Gesture, runOnBackground, useGestureDetector, useMainThreadRef, } from '@sigx/lynx';
+import { withTiming } from '@sigx/lynx-motion';
+import { useNavInternals } from '../hooks/use-nav-internal.js';
+import { SCREEN_WIDTH } from '../internal/screen-width.js';
+/**
+ * Edge-pan recognizer for iOS-style swipe-back. Mounts as an absolutely-
+ * positioned 20px-wide strip on the left edge of the active screen; only
+ * exists when `nav.canGoBack && !transition`.
+ *
+ * `Gesture.Pan().minDistance(MIN_DISTANCE)` lets quick taps pass through to
+ * whatever's behind the strip (back button, screen header, etc.). Only
+ * horizontal drags past the threshold activate the gesture.
+ *
+ * MT/BG split:
+ *   - All gesture handlers run on MT. They write `progress.current.value`
+ *     directly per frame (no per-frame bridge crossing) and dispatch
+ *     `runOnBackground(...)` only at start/commit/cancel — three BG hops
+ *     per gesture max.
+ *   - The transition state machine on BG mounts the underneath
+ *     `<ScreenContainer>` once `beginBackGesture` lands; the gesture's
+ *     in-flight progress writes are picked up the moment the binding
+ *     registers (Phase 0.5 polish: pre-mount underneath when canGoBack to
+ *     eliminate the brief pre-mount latency).
+ *
+ * Implementation notes (matching `<Draggable>`):
+ *   - Single `useMainThreadRef` holding an object — primitive refs don't
+ *     survive worklet capture cleanly in some Lynx versions, while object
+ *     refs do (the worklet runtime resolves the ref via the
+ *     `_workletRefMap`).
+ *   - `e: any` rather than `e: unknown` — type annotations are erased, but
+ *     SWC's worklet transform has been observed to behave better with the
+ *     looser annotation. Keeps us aligned with Draggable verbatim.
+ *   - Empty `onBegin`: load-bearing on iOS — without a registered onBegin
+ *     callback, `LynxPanGestureHandler` skips the begin path and onStart/
+ *     onEnd never fire (per Draggable's notes).
+ */
+/** Fraction of screen width past which a release commits the back nav. */
+const COMMIT_TRANSLATION = 0.33;
+/** px/sec horizontal speed past which a release commits, regardless of distance. */
+const COMMIT_VELOCITY = 300;
+/** Width of the touchable strip on the left edge of every screen. */
+const EDGE_ZONE_WIDTH = 20;
+/** Minimum movement before the gesture activates (lets taps pass through). */
+const MIN_DISTANCE = 8;
+const SNAP_DURATION_SEC = 0.18;
+/**
+ * Pre-computed milliseconds for the BG-side `setTimeout`. Module-level so
+ * it's in scope for both the MT worklet (`withTiming` argument) and the BG
+ * callback wrapped by `runOnBackground` (`setTimeout` argument). Locals
+ * declared inside an MT worklet body are MT-only — the BG callback's
+ * closure can't see them, hence "ReferenceError: snapMs is not defined".
+ */
+const SNAP_DURATION_MS = Math.round(SNAP_DURATION_SEC * 1000);
+export const EdgeBackHandle = component(() => {
+    const ref = useMainThreadRef(null);
+    // Per-gesture transient state — captured as a plain closure object
+    // rather than a `useMainThreadRef`. Lynx's SWC worklet transform deep-
+    // copies plain objects into `_c` once at register time; mutations on MT
+    // persist across calls because the same `_c` is bound for the lifetime
+    // of the gesture registration. Using a `useMainThreadRef` here was
+    // crashing on iOS with `cannot read property 'current' of undefined`
+    // — the resolved-ref capture path looked up an empty
+    // `_workletRefMap` entry under a race I haven't fully tracked down.
+    // Plain object avoids that path entirely.
+    const state = {
+        startPageX: 0,
+        prevPageX: 0,
+        prevTime: 0,
+        velocity: 0,
+    };
+    const internals = useNavInternals();
+    const progress = internals.progress;
+    const beginBackGesture = internals.beginBackGesture;
+    const commitBackGesture = internals.commitBackGesture;
+    const cancelBackGesture = internals.cancelBackGesture;
+    const pan = Gesture.Pan()
+        .minDistance(MIN_DISTANCE)
+        .onBegin(() => {
+        'main thread';
+    })
+        .onStart((e) => {
+        'main thread';
+        const p = e && e.params;
+        const pageX = (p && p.pageX) || 0;
+        state.startPageX = pageX;
+        state.prevPageX = pageX;
+        state.prevTime = Date.now();
+        state.velocity = 0;
+        runOnBackground(() => {
+            beginBackGesture();
+        })();
+    })
+        .onUpdate((e) => {
+        'main thread';
+        if (!progress)
+            return;
+        const p = e && e.params;
+        const pageX = (p && p.pageX) || 0;
+        const dx = pageX - state.startPageX;
+        const prog = Math.max(0, Math.min(1, dx / SCREEN_WIDTH));
+        progress.current.value = prog;
+        const now = Date.now();
+        const dt = now - state.prevTime;
+        if (dt > 0) {
+            state.velocity =
+                ((pageX - state.prevPageX) / dt) * 1000;
+        }
+        state.prevPageX = pageX;
+        state.prevTime = now;
+    })
+        .onEnd((e) => {
+        'main thread';
+        if (!progress)
+            return;
+        const p = e && e.params;
+        const pageX = (p && p.pageX) || 0;
+        const dx = pageX - state.startPageX;
+        const fraction = dx / SCREEN_WIDTH;
+        const commit = fraction > COMMIT_TRANSLATION ||
+            state.velocity > COMMIT_VELOCITY;
+        if (commit) {
+            withTiming(progress, 1, { duration: SNAP_DURATION_SEC });
+            runOnBackground(() => {
+                setTimeout(() => commitBackGesture(), SNAP_DURATION_MS);
+            })();
+        }
+        else {
+            withTiming(progress, 0, { duration: SNAP_DURATION_SEC });
+            runOnBackground(() => {
+                setTimeout(() => cancelBackGesture(), SNAP_DURATION_MS);
+            })();
+        }
+    });
+    useGestureDetector(ref, pan);
+    return () => (_jsx("view", { "main-thread:ref": ref, style: {
+            position: 'absolute',
+            top: '0',
+            left: '0',
+            width: `${EDGE_ZONE_WIDTH}px`,
+            bottom: '0',
+        } }));
+});
+//# sourceMappingURL=EdgeBackHandle.js.map

package/dist/components/EdgeBackHandle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EdgeBackHandle.js","sourceRoot":"","sources":["../../src/components/EdgeBackHandle.tsx"],"names":[],"mappings":"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"}