@react-navigation/lynx 0.2.0 → 0.3.0-canary-20260907-96fbfef4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-navigation/lynx",
-  "version": "0.2.0",
+  "version": "0.3.0-canary-20260907-96fbfef4",
   "description": "Lynx integration for React Navigation",
   "keywords": [
     "react",
@@ -32,6 +32,7 @@
     "src"
   ],
   "dependencies": {
+    "escape-string-regexp": "^5.0.0",
     "@react-navigation/core": "^8.0.0-alpha.33"
   },
   "peerDependencies": {
@@ -39,9 +40,9 @@
     "lynx-screens": "*"
   },
   "devDependencies": {
-    "@lynx-js/react": "^0.125.0",
-    "@lynx-js/testing-environment": "^0.3.3",
-    "@lynx-js/types": "^4.1.0",
+    "@lynx-js/react": "^0.126.0",
+    "@lynx-js/testing-environment": "^0.3.4",
+    "@lynx-js/types": "^4.2.1",
     "@types/react": "~19.2.17",
     "jsdom": "^26.0.0",
     "typescript": "^6.0.3",

package/src/NavigationContainer.tsx

@@ -10,42 +10,30 @@ import {
 import * as React from 'react';
 
 import { LightTheme } from './theming/LightTheme';
+import { type LinkingOptions, useLinking } from './useLinking';
 
 export type NavigationContainerLynxProps<
   ParamList extends {} = ParamListBase,
 > = NavigationContainerProps & {
-  /**
-   * Theme handed to `useTheme` and to any navigator that reads colors.
-   */
   theme?: Theme | undefined;
-  /**
-   * Rendered while persisted state is being restored.
-   */
+  /** Rendered while persisted state is being restored. */
   fallback?: React.ReactNode | undefined;
+  /** Maps URLs handed over by the host onto navigation state. */
+  linking?: LinkingOptions<ParamList> | undefined;
   ref?: React.Ref<NavigationContainerRef<ParamList>> | undefined;
 };
 
 /**
  * The Lynx counterpart of `@react-navigation/native`'s `NavigationContainer`.
  *
- * It is the platform layer's entry point: everything a navigator needs that is
- * not navigation state itself - the theme, and eventually deep linking and
- * state persistence - is wired here rather than in each navigator.
- *
- * Not yet ported from React Native:
- *
- * - deep linking (`linking`), which needs a Lynx URL source
- * - state persistence, which needs a Lynx storage binding
- * - `useDocumentTitle`, which is a browser concern and has no Lynx meaning
- *
- * The hardware back button is deliberately absent: on Lynx it is handled by
- * the native stack per screen, through `preventNativeDismiss` and the dismiss
- * callbacks, so a container-level handler would fight with it.
+ * No state persistence yet, and no back-button handler: the native stack owns
+ * dismissal per screen, so a container-level one would fight with it.
  */
 export function NavigationContainer<ParamList extends {} = ParamListBase>({
   theme = LightTheme,
   fallback = null,
   onStateChange,
+  linking,
   ref,
   ...rest
 }: NavigationContainerLynxProps<ParamList>) {
@@ -57,23 +45,32 @@ export function NavigationContainer<ParamList extends {} = ParamListBase>({
     () => refContainer.current as NavigationContainerRef<ParamList>
   );
 
+  const { getInitialState } = useLinking(refContainer, linking);
+
+  // Read once: later URLs go through the subscription instead.
+  const [linkingInitialState] = React.useState(() =>
+    rest.initialState != null ? undefined : getInitialState()
+  );
+
+  const { children: _children, ...restWithoutChildren } = rest;
+
   const handleStateChange = (state: Readonly<NavigationState> | undefined) => {
     onStateChange?.(state);
   };
 
-  // Kept for parity with React Native, where this renders while persisted
-  // state is being restored. With no persistence yet there is nothing to wait
-  // for, so it only shows if a caller passes `fallback` and no children.
   if (rest.children == null) {
     return <ThemeProvider value={theme}>{fallback}</ThemeProvider>;
   }
 
   return (
     <BaseNavigationContainer
-      {...rest}
+      {...restWithoutChildren}
+      initialState={rest.initialState ?? linkingInitialState}
       theme={theme}
       onStateChange={handleStateChange}
       ref={refContainer}
-    />
+    >
+      {rest.children}
+    </BaseNavigationContainer>
   );
 }

package/src/__tests__/extractPathFromURL.test.ts

@@ -0,0 +1,505 @@
+import { expect, test } from 'vitest';
+
+import { extractPathFromURL } from '../extractPathFromURL';
+
+test('extracts path from URL with protocol', () => {
+  expect(extractPathFromURL(['scheme://'], 'scheme://some/path')).toBe(
+    '/some/path'
+  );
+
+  expect(extractPathFromURL(['scheme://'], 'scheme:some/path')).toBe(
+    '/some/path'
+  );
+
+  expect(extractPathFromURL(['scheme://'], 'scheme:///some/path')).toBe(
+    '/some/path'
+  );
+
+  expect(extractPathFromURL(['scheme:///'], 'scheme:some/path')).toBe(
+    '/some/path'
+  );
+
+  expect(extractPathFromURL(['scheme:'], 'scheme:some/path')).toBe(
+    '/some/path'
+  );
+
+  expect(extractPathFromURL(['scheme:'], 'scheme://some/path')).toBe(
+    '/some/path'
+  );
+
+  expect(extractPathFromURL(['scheme:'], 'scheme:///some/path')).toBe(
+    '/some/path'
+  );
+});
+
+test('extracts path from URL with protocol and host', () => {
+  expect(
+    extractPathFromURL(
+      ['scheme://example.com'],
+      'scheme://example.com/some/path'
+    )
+  ).toBe('/some/path');
+
+  expect(
+    extractPathFromURL(['scheme://example.com'], 'scheme:example.com/some/path')
+  ).toBe('/some/path');
+
+  expect(
+    extractPathFromURL(
+      ['scheme://example.com'],
+      'scheme:///example.com/some/path'
+    )
+  ).toBe('/some/path');
+
+  expect(
+    extractPathFromURL(
+      ['scheme:///example.com'],
+      'scheme:example.com/some/path'
+    )
+  ).toBe('/some/path');
+
+  expect(
+    extractPathFromURL(['scheme:example.com'], 'scheme:example.com/some/path')
+  ).toBe('/some/path');
+
+  expect(
+    extractPathFromURL(['scheme:example.com'], 'scheme://example.com/some/path')
+  ).toBe('/some/path');
+
+  expect(
+    extractPathFromURL(
+      ['scheme:example.com'],
+      'scheme:///example.com/some/path'
+    )
+  ).toBe('/some/path');
+
+  expect(
+    extractPathFromURL(['scheme://example.com'], 'scheme://example.com/')
+  ).toBe('/');
+
+  expect(
+    extractPathFromURL(['scheme://example.com'], 'scheme://example.com')
+  ).toBe('/');
+});
+
+test('extracts path from URL with protocol and host with wildcard', () => {
+  expect(
+    extractPathFromURL(
+      ['scheme://*.example.com'],
+      'scheme://test.example.com/some/path'
+    )
+  ).toBe('/some/path');
+
+  expect(
+    extractPathFromURL(
+      ['scheme://*.example.com'],
+      'scheme:test.example.com/some/path'
+    )
+  ).toBe('/some/path');
+
+  expect(
+    extractPathFromURL(
+      ['scheme://*.example.com'],
+      'scheme:///test.example.com/some/path'
+    )
+  ).toBe('/some/path');
+
+  expect(
+    extractPathFromURL(
+      ['scheme:///*.example.com'],
+      'scheme:test.example.com/some/path'
+    )
+  ).toBe('/some/path');
+
+  expect(
+    extractPathFromURL(
+      ['scheme:*.example.com'],
+      'scheme:test.example.com/some/path'
+    )
+  ).toBe('/some/path');
+
+  expect(
+    extractPathFromURL(
+      ['scheme:*.example.com'],
+      'scheme://test.example.com/some/path'
+    )
+  ).toBe('/some/path');
+
+  expect(
+    extractPathFromURL(
+      ['scheme:*.example.com'],
+      'scheme:///test.example.com/some/path'
+    )
+  ).toBe('/some/path');
+});
+
+test('extracts path from URL with protocol, host and path', () => {
+  expect(
+    extractPathFromURL(
+      ['scheme://example.com/test'],
+      'scheme://example.com/test/some/path'
+    )
+  ).toBe('/some/path');
+
+  expect(
+    extractPathFromURL(['scheme://example.com'], 'scheme:example.com/some/path')
+  ).toBe('/some/path');
+
+  expect(
+    extractPathFromURL(
+      ['scheme://example.com/test'],
+      'scheme:///example.com/test/some/path'
+    )
+  ).toBe('/some/path');
+
+  expect(
+    extractPathFromURL(
+      ['scheme:///example.com/test'],
+      'scheme:example.com/test/some/path'
+    )
+  ).toBe('/some/path');
+
+  expect(
+    extractPathFromURL(
+      ['scheme:example.com/test'],
+      'scheme:example.com/test/some/path'
+    )
+  ).toBe('/some/path');
+
+  expect(
+    extractPathFromURL(
+      ['scheme:example.com/test'],
+      'scheme://example.com/test/some/path'
+    )
+  ).toBe('/some/path');
+
+  expect(
+    extractPathFromURL(
+      ['scheme:example.com/test'],
+      'scheme:///example.com/test/some/path'
+    )
+  ).toBe('/some/path');
+
+  expect(
+    extractPathFromURL(
+      ['scheme:example.com/test'],
+      'scheme:///example.com/test//some/path'
+    )
+  ).toBe('/some/path');
+
+  expect(
+    extractPathFromURL(
+      ['scheme:example.com/test'],
+      'scheme:///example.com/test/some//path'
+    )
+  ).toBe('/some/path');
+
+  expect(
+    extractPathFromURL(
+      ['scheme://example.com/test'],
+      'scheme://example.com/test?foo=bar'
+    )
+  ).toBe('/?foo=bar');
+
+  expect(
+    extractPathFromURL(
+      ['scheme://example.com/test'],
+      'scheme://example.com/test#section'
+    )
+  ).toBe('/#section');
+});
+
+test('extracts path from URL with IP address and port', () => {
+  // Test exact IP address and port matching
+  expect(
+    extractPathFromURL(
+      ['http://127.0.0.1:19000'],
+      'http://127.0.0.1:19000/some/path'
+    )
+  ).toBe('/some/path');
+
+  expect(
+    extractPathFromURL(
+      ['https://127.0.0.1:8080'],
+      'https://127.0.0.1:8080/secure/path'
+    )
+  ).toBe('/secure/path');
+
+  expect(
+    extractPathFromURL(
+      ['exp://127.0.0.1:19000'],
+      'exp://127.0.0.1:19000/--/simple-stack'
+    )
+  ).toBe('/--/simple-stack');
+
+  expect(
+    extractPathFromURL(
+      ['rne://127.0.0.1:19000'],
+      'rne://127.0.0.1:19000/--/simple-stack'
+    )
+  ).toBe('/--/simple-stack');
+
+  // Test IPv6 prefixes
+  expect(
+    extractPathFromURL(['http://[::1]:8080'], 'http://[::1]:8080/some/path')
+  ).toBe('/some/path');
+
+  // Test with query parameters
+  expect(
+    extractPathFromURL(
+      ['http://127.0.0.1:19000'],
+      'http://127.0.0.1:19000/path?param=value'
+    )
+  ).toBe('/path?param=value');
+
+  // Test empty path
+  expect(
+    extractPathFromURL(['http://127.0.0.1:19000'], 'http://127.0.0.1:19000')
+  ).toBe('/');
+  expect(
+    extractPathFromURL(['http://127.0.0.1:19000'], 'http://127.0.0.1:19000/')
+  ).toBe('/');
+});
+
+test('returns undefined for non-matching protocol', () => {
+  expect(extractPathFromURL(['scheme://'], 'foo://some/path')).toBeUndefined();
+
+  expect(extractPathFromURL(['scheme://'], 'foo:some/path')).toBeUndefined();
+
+  expect(extractPathFromURL(['scheme://'], 'foo:///some/path')).toBeUndefined();
+
+  expect(extractPathFromURL(['scheme:///'], 'foo:some/path')).toBeUndefined();
+
+  expect(extractPathFromURL(['scheme:'], 'foo:some/path')).toBeUndefined();
+
+  expect(extractPathFromURL(['scheme:'], 'foo://some/path')).toBeUndefined();
+
+  expect(extractPathFromURL(['scheme:'], 'foo:///some/path')).toBeUndefined();
+});
+
+test('returns undefined for non-matching path', () => {
+  expect(
+    extractPathFromURL(['scheme://foo'], 'scheme://some/path')
+  ).toBeUndefined();
+
+  expect(
+    extractPathFromURL(['scheme://foo'], 'scheme:some/path')
+  ).toBeUndefined();
+
+  expect(
+    extractPathFromURL(['scheme://foo'], 'scheme:///some/path')
+  ).toBeUndefined();
+
+  expect(
+    extractPathFromURL(['scheme:///foo'], 'scheme:some/path')
+  ).toBeUndefined();
+
+  expect(
+    extractPathFromURL(['scheme:foo'], 'scheme:some/path')
+  ).toBeUndefined();
+
+  expect(
+    extractPathFromURL(['scheme:foo'], 'scheme://some/path')
+  ).toBeUndefined();
+
+  expect(
+    extractPathFromURL(['scheme:foo'], 'scheme:///some/path')
+  ).toBeUndefined();
+});
+
+test('returns undefined for non-matching host', () => {
+  expect(
+    extractPathFromURL(['scheme://example.com'], 'scheme://foo.com/some/path')
+  ).toBeUndefined();
+
+  expect(
+    extractPathFromURL(['scheme://example.com'], 'scheme:foo.com/some/path')
+  ).toBeUndefined();
+
+  expect(
+    extractPathFromURL(['scheme://example.com'], 'scheme:///foo.com/some/path')
+  ).toBeUndefined();
+
+  expect(
+    extractPathFromURL(['scheme:///example.com'], 'scheme:foo.com/some/path')
+  ).toBeUndefined();
+
+  expect(
+    extractPathFromURL(['scheme:example.com'], 'scheme:foo.com/some/path')
+  ).toBeUndefined();
+
+  expect(
+    extractPathFromURL(['scheme:example.com'], 'scheme://foo.com/some/path')
+  ).toBeUndefined();
+
+  expect(
+    extractPathFromURL(['scheme:example.com'], 'scheme:///foo.com/some/path')
+  ).toBeUndefined();
+
+  expect(
+    extractPathFromURL(
+      ['https://example.com'],
+      'https://example.com.evil.com/some/path'
+    )
+  ).toBeUndefined();
+});
+
+test('returns undefined for non-matching host with wildcard', () => {
+  expect(
+    extractPathFromURL(
+      ['scheme://*.example.com'],
+      'scheme://test.foo.com/some/path'
+    )
+  ).toBeUndefined();
+
+  expect(
+    extractPathFromURL(
+      ['scheme://*.example.com'],
+      'scheme:test.foo.com/some/path'
+    )
+  ).toBeUndefined();
+
+  expect(
+    extractPathFromURL(
+      ['scheme://*.example.com'],
+      'scheme:///test.foo.com/some/path'
+    )
+  ).toBeUndefined();
+
+  expect(
+    extractPathFromURL(
+      ['scheme:///*.example.com'],
+      'scheme:test.foo.com/some/path'
+    )
+  ).toBeUndefined();
+
+  expect(
+    extractPathFromURL(
+      ['scheme:*.example.com'],
+      'scheme:test.foo.com/some/path'
+    )
+  ).toBeUndefined();
+
+  expect(
+    extractPathFromURL(
+      ['scheme:*.example.com'],
+      'scheme://test.foo.com/some/path'
+    )
+  ).toBeUndefined();
+
+  expect(
+    extractPathFromURL(
+      ['scheme:*.example.com'],
+      'scheme:///test.foo.com/some/path'
+    )
+  ).toBeUndefined();
+
+  expect(
+    extractPathFromURL(
+      ['https://*.example.com'],
+      'https://test.example.com.evil.com/some/path'
+    )
+  ).toBeUndefined();
+});
+
+test('returns undefined for path prefix collisions', () => {
+  expect(
+    extractPathFromURL(
+      ['https://example.com/app'],
+      'https://example.com/application/path'
+    )
+  ).toBeUndefined();
+
+  expect(
+    extractPathFromURL(
+      ['https://example.com/app'],
+      'https://example.com/apply/path'
+    )
+  ).toBeUndefined();
+});
+
+test('returns a valid search query when it has a url as param', () => {
+  expect(
+    extractPathFromURL(
+      ['https://mysite.com'],
+      'https://mysite.com/readPolicy?url=https://test.com'
+    )
+  ).toBe('/readPolicy?url=https://test.com');
+
+  expect(
+    extractPathFromURL(
+      ['https://mysite.com'],
+      'https://mysite.com/readPolicy?url=https://test.com?param=1'
+    )
+  ).toBe('/readPolicy?url=https://test.com?param=1');
+});
+
+test('supports wildcard prefix that matches any scheme', () => {
+  // Test with various schemes
+  expect(extractPathFromURL(['*'], 'myapp:some/path')).toBe('/some/path');
+  expect(extractPathFromURL(['*'], 'myapp://some/path')).toBe('/some/path');
+  expect(extractPathFromURL(['*'], 'myapp:///some/path')).toBe('/some/path');
+
+  expect(extractPathFromURL(['*'], 'customscheme:path/to/resource')).toBe(
+    '/path/to/resource'
+  );
+});
+
+test('supports wildcard prefix that matches any URL', () => {
+  expect(extractPathFromURL(['*'], 'http://mysite.com/some/path')).toBe(
+    '/some/path'
+  );
+  expect(extractPathFromURL(['*'], 'https://mysite.com/some/path')).toBe(
+    '/some/path'
+  );
+  expect(
+    extractPathFromURL(['*'], 'http://subdomain.mysite.com/some/path')
+  ).toBe('/some/path');
+  expect(
+    extractPathFromURL(['*'], 'https://subdomain.mysite.com/some/path')
+  ).toBe('/some/path');
+
+  expect(
+    extractPathFromURL(['*'], 'https://example.com/path?param=value')
+  ).toBe('/path?param=value');
+
+  expect(extractPathFromURL(['*'], 'https://example.com')).toBe('/');
+  expect(extractPathFromURL(['*'], 'https://example.com/')).toBe('/');
+});
+
+test('supports wildcard prefix that matches IP addresses and ports', () => {
+  expect(extractPathFromURL(['*'], 'http://127.0.0.1:19000/some/path')).toBe(
+    '/some/path'
+  );
+  expect(extractPathFromURL(['*'], 'https://127.0.0.1:8080/some/path')).toBe(
+    '/some/path'
+  );
+
+  expect(extractPathFromURL(['*'], 'http://[::1]:8080/some/path')).toBe(
+    '/some/path'
+  );
+  expect(extractPathFromURL(['*'], 'https://[::1]:3000/api/test')).toBe(
+    '/api/test'
+  );
+
+  expect(extractPathFromURL(['*'], 'http://192.168.1.1:3000/admin')).toBe(
+    '/admin'
+  );
+  expect(extractPathFromURL(['*'], 'https://10.0.0.1:8443/secure/path')).toBe(
+    '/secure/path'
+  );
+
+  expect(extractPathFromURL(['*'], 'http://127.0.0.1:19000')).toBe('/');
+  expect(extractPathFromURL(['*'], 'http://127.0.0.1:19000/')).toBe('/');
+
+  expect(
+    extractPathFromURL(['*'], 'http://127.0.0.1:19000/path?param=value')
+  ).toBe('/path?param=value');
+  expect(
+    extractPathFromURL(['*'], 'https://192.168.1.100:8080/api?token=123&id=456')
+  ).toBe('/api?token=123&id=456');
+});
+
+test('wildcard prefix does not match when no scheme is present', () => {
+  expect(extractPathFromURL(['*'], 'some/path/without/scheme')).toBeUndefined();
+});

package/src/__tests__/linking.test.ts

@@ -0,0 +1,163 @@
+import { getStateFromPath } from '@react-navigation/core';
+import { afterEach, expect, test, vi } from 'vitest';
+
+import {
+  getInitialURL,
+  INIT_DATA_KEY,
+  RN_URL_EVENT,
+  subscribe,
+  URL_EVENT,
+} from '../linking';
+
+type Listener = (...args: any[]) => void;
+
+/** Stands in for `lynx.__initData` and `GlobalEventEmitter`. */
+function setupLynx(initNavigation?: Record<string, unknown>) {
+  const listeners = new Map<string, Set<Listener>>();
+
+  const emitter = {
+    addListener: (event: string, listener: Listener) => {
+      const set = listeners.get(event) ?? new Set();
+      set.add(listener);
+      listeners.set(event, set);
+    },
+    removeListener: (event: string, listener: Listener) => {
+      listeners.get(event)?.delete(listener);
+    },
+  };
+
+  const lynx = {
+    __initData: initNavigation
+      ? { [INIT_DATA_KEY]: initNavigation }
+      : ({} as Record<string, unknown>),
+    getJSModule: (name: string) =>
+      name === 'GlobalEventEmitter' ? emitter : undefined,
+  };
+
+  vi.stubGlobal('lynx', lynx);
+
+  return {
+    /** What the host does on `updateMetaData`. */
+    updateInitData(navigation: Record<string, unknown>) {
+      lynx.__initData = { [INIT_DATA_KEY]: navigation };
+      listeners.get('onDataChanged')?.forEach((l) => l());
+    },
+    emitUrl(url: string, event: string = URL_EVENT) {
+      listeners.get(event)?.forEach((l) => l({ url }));
+    },
+    listenerCount: (event: string) => listeners.get(event)?.size ?? 0,
+  };
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+test('reads the launch route out of initData', () => {
+  setupLynx({ route: '/users/42?tab=posts' });
+
+  expect(getInitialURL()).toBe('/users/42?tab=posts');
+});
+
+test('reports no launch route when the host set none', () => {
+  setupLynx();
+
+  expect(getInitialURL()).toBeUndefined();
+});
+
+test('an initData update delivers the new route', () => {
+  const host = setupLynx({ route: '/', nonce: 1 });
+  const listener = vi.fn();
+
+  subscribe(listener);
+  host.updateInitData({ route: '/settings', nonce: 2 });
+
+  expect(listener).toHaveBeenCalledWith('/settings');
+});
+
+test('the route the card started with is not delivered again', () => {
+  const host = setupLynx({ route: '/users/42', nonce: 1 });
+  const listener = vi.fn();
+
+  subscribe(listener);
+  // An unrelated initData change - a data refresh, say - must not re-navigate.
+  host.updateInitData({ route: '/users/42', nonce: 1 });
+
+  expect(listener).not.toHaveBeenCalled();
+});
+
+test('navigating twice to the same route works when the nonce moves', () => {
+  const host = setupLynx({ route: '/', nonce: 1 });
+  const listener = vi.fn();
+
+  subscribe(listener);
+  host.updateInitData({ route: '/users/42', nonce: 2 });
+  host.updateInitData({ route: '/users/42', nonce: 3 });
+
+  expect(listener).toHaveBeenCalledTimes(2);
+  expect(listener).toHaveBeenNthCalledWith(2, '/users/42');
+});
+
+test('a url event delivers the route', () => {
+  const host = setupLynx();
+  const listener = vi.fn();
+
+  subscribe(listener);
+  host.emitUrl('/settings');
+
+  expect(listener).toHaveBeenCalledWith('/settings');
+});
+
+test('the event name is namespaced, since GlobalEventEmitter is shared', () => {
+  expect(URL_EVENT).toBe('reactnavigation.url');
+});
+
+test('still accepts the bare `url` event React Native hosts emit', () => {
+  const host = setupLynx();
+  const listener = vi.fn();
+
+  subscribe(listener);
+  host.emitUrl('/settings', RN_URL_EVENT);
+
+  expect(listener).toHaveBeenCalledWith('/settings');
+});
+
+test('unsubscribing detaches every listener', () => {
+  const host = setupLynx({ route: '/' });
+
+  const unsubscribe = subscribe(vi.fn());
+
+  expect(host.listenerCount('onDataChanged')).toBe(1);
+  expect(host.listenerCount(URL_EVENT)).toBe(1);
+  expect(host.listenerCount(RN_URL_EVENT)).toBe(1);
+
+  unsubscribe();
+
+  expect(host.listenerCount('onDataChanged')).toBe(0);
+  expect(host.listenerCount(URL_EVENT)).toBe(0);
+  expect(host.listenerCount(RN_URL_EVENT)).toBe(0);
+});
+
+test('survives a host that offers no GlobalEventEmitter', () => {
+  vi.stubGlobal('lynx', { __initData: {} });
+
+  expect(() => subscribe(vi.fn())()).not.toThrow();
+});
+
+test('the route it produces is what core turns into navigation state', () => {
+  setupLynx({ route: '/users/42?tab=posts' });
+
+  const state = getStateFromPath(getInitialURL()!, {
+    screens: { Home: '', Profile: 'users/:id' },
+  });
+
+  expect(state).toEqual({
+    routes: [
+      {
+        name: 'Profile',
+        params: { id: '42', tab: 'posts' },
+        path: '/users/42?tab=posts',
+      },
+    ],
+  });
+});

package/src/extractPathFromURL.ts

@@ -0,0 +1,42 @@
+import escapeStringRegexp from 'escape-string-regexp';
+
+import type { LinkingPrefix } from './useLinking';
+
+/** Verbatim from `@react-navigation/native`, which cannot be imported here. */
+export function extractPathFromURL(prefixes: LinkingPrefix[], url: string) {
+  for (const prefix of prefixes) {
+    let prefixRegex;
+
+    if (prefix === '*') {
+      prefixRegex = /^(((https?:\/\/)[^/]+)|([^/]+:(\/\/)?))/;
+    } else {
+      const protocol = prefix.match(/^[^:]+:/)?.[0] ?? '';
+      const host = prefix
+        .replace(new RegExp(`^${escapeStringRegexp(protocol)}`), '')
+        .replace(/\/+/g, '/') // Replace multiple slash (//) with single ones
+        .replace(/^\//, ''); // Remove extra leading slash
+
+      prefixRegex = new RegExp(
+        `^${escapeStringRegexp(protocol)}(/)*${host
+          .split('.')
+          .map((it) => (it === '*' ? '[^/?#]+' : escapeStringRegexp(it)))
+          .join('\\.')}${
+          host === '' || host.endsWith('/') ? '' : '(?=$|[/?#])'
+        }`
+      );
+    }
+
+    const [originAndPath = '', ...searchParams] = url.split('?');
+
+    if (prefixRegex.test(originAndPath)) {
+      const result = originAndPath
+        .replace(prefixRegex, '')
+        .replace(/\/+/g, '/')
+        .concat(searchParams.length ? `?${searchParams.join('?')}` : '');
+
+      return result.startsWith('/') ? result : `/${result}`;
+    }
+  }
+
+  return undefined;
+}

package/src/index.tsx

@@ -10,4 +10,14 @@ export {
 export { DarkTheme } from './theming/DarkTheme';
 export { LightTheme as DefaultTheme } from './theming/LightTheme';
 
+export {
+  getInitialURL,
+  INIT_DATA_KEY,
+  RN_URL_EVENT,
+  subscribe,
+  URL_EVENT,
+  type NavigationInitData,
+} from './linking';
+export type { LinkingOptions, LinkingPrefix } from './useLinking';
+
 export * from '@react-navigation/core';

package/src/linking.ts

@@ -0,0 +1,101 @@
+/**
+ * The Lynx half of React Navigation's linking: a card is not the process that
+ * receives the URL, so the host hands it over either through
+ * `initData.__navigation` or through a global event.
+ */
+
+export const INIT_DATA_KEY = '__navigation';
+
+/**
+ * Namespaced, unlike React Native's bare `url`: `GlobalEventEmitter` is one
+ * namespace shared by the whole card and its host.
+ */
+export const URL_EVENT = 'reactnavigation.url';
+
+export const RN_URL_EVENT = 'url';
+
+export type NavigationInitData = {
+  route?: string | undefined;
+  /** Anything that changes per navigation; see `subscribe`. */
+  nonce?: string | number | undefined;
+};
+
+type GlobalEventEmitter = {
+  addListener: (event: string, listener: (...args: any[]) => void) => void;
+  removeListener: (event: string, listener: (...args: any[]) => void) => void;
+};
+
+const DATA_CHANGED_EVENT = 'onDataChanged';
+
+function readNavigationInitData(): NavigationInitData | undefined {
+  const initData = (lynx as { __initData?: Record<string, unknown> }).__initData;
+  return initData?.[INIT_DATA_KEY] as NavigationInitData | undefined;
+}
+
+function getEmitter(): GlobalEventEmitter | undefined {
+  // Background thread only, and absent under test renderers.
+  return lynx.getJSModule?.('GlobalEventEmitter') as
+    | GlobalEventEmitter
+    | undefined;
+}
+
+/**
+ * Synchronous, unlike React Native's `Linking.getInitialURL()`, so the first
+ * render already lands on the right route.
+ */
+export function getInitialURL(): string | undefined {
+  return readNavigationInitData()?.route;
+}
+
+export function subscribe(listener: (url: string) => void): () => void {
+  const emitter = getEmitter();
+
+  if (!emitter) {
+    return () => {};
+  }
+
+  let lastSeen = readNavigationInitData()?.nonce ?? getInitialURL();
+
+  const onDataChanged = () => {
+    const next = readNavigationInitData();
+
+    if (!next?.route) {
+      return;
+    }
+
+    // initData is state, not an event: without the nonce, navigating to the
+    // same route twice would leave it untouched and be dropped.
+    const marker = next.nonce ?? next.route;
+
+    if (marker === lastSeen) {
+      return;
+    }
+
+    lastSeen = marker;
+    listener(next.route);
+  };
+
+  // `sendGlobalEvent(name, JavaOnlyArray)` reaches JS as either the array's
+  // first element or the array itself, and a host may send a bare string.
+  const onUrl = (payload: unknown) => {
+    const first = Array.isArray(payload) ? payload[0] : payload;
+    const url =
+      typeof first === 'string'
+        ? first
+        : (first as { url?: string } | undefined)?.url;
+
+    if (url) {
+      listener(url);
+    }
+  };
+
+  emitter.addListener(DATA_CHANGED_EVENT, onDataChanged);
+  emitter.addListener(URL_EVENT, onUrl);
+  emitter.addListener(RN_URL_EVENT, onUrl);
+
+  return () => {
+    emitter.removeListener(DATA_CHANGED_EVENT, onDataChanged);
+    emitter.removeListener(URL_EVENT, onUrl);
+    emitter.removeListener(RN_URL_EVENT, onUrl);
+  };
+}

package/src/useLinking.ts

@@ -0,0 +1,180 @@
+import {
+  getActionFromState as getActionFromStateDefault,
+  getStateFromPath as getStateFromPathDefault,
+  type NavigationContainerRef,
+  type ParamListBase,
+  type PartialState,
+  type NavigationState,
+} from '@react-navigation/core';
+import * as React from 'react';
+
+import { extractPathFromURL } from './extractPathFromURL';
+import {
+  getInitialURL as getInitialURLDefault,
+  subscribe as subscribeDefault,
+} from './linking';
+
+// core keeps its `Options` type internal; derive it from the consumer so it
+// cannot drift.
+type LinkingConfig<ParamList extends {}> = NonNullable<
+  Parameters<typeof getStateFromPathDefault<ParamList>>[1]
+>;
+
+export type LinkingPrefix = '*' | (string & {});
+
+export type LinkingOptions<ParamList extends {}> = {
+  /** Defaults to true when a config is given. */
+  enabled?: boolean | undefined;
+  prefixes?: LinkingPrefix[] | undefined;
+  /** Rejects a URL before its prefix is stripped. */
+  filter?: ((url: string) => boolean) | undefined;
+  config?: LinkingConfig<ParamList> | undefined;
+  /** Overrides where the launch URL comes from. */
+  getInitialURL?: (() => string | undefined) | undefined;
+  /** Overrides how later URLs arrive. */
+  subscribe?:
+    | ((listener: (url: string) => void) => undefined | void | (() => void))
+    | undefined;
+  getStateFromPath?: typeof getStateFromPathDefault | undefined;
+  getActionFromState?: typeof getActionFromStateDefault | undefined;
+} & { [key: string]: unknown };
+
+/** The `getStateFromHref` contract of `@react-navigation/native`. */
+function extractPath(
+  url: string,
+  prefixes: LinkingPrefix[] | undefined,
+  filter: ((url: string) => boolean) | undefined
+) {
+  if (url.startsWith('/')) {
+    return url;
+  }
+
+  if (filter && !filter(url)) {
+    return undefined;
+  }
+
+  if (prefixes == null || prefixes.length === 0) {
+    return undefined;
+  }
+
+  return extractPathFromURL(prefixes, url);
+}
+
+/** The Lynx counterpart of `useLinking` in `@react-navigation/native`. */
+export function useLinking<ParamList extends {} = ParamListBase>(
+  ref: React.RefObject<NavigationContainerRef<ParamListBase> | null>,
+  options: LinkingOptions<ParamList> | undefined
+) {
+  const {
+    enabled = options?.config != null,
+    // Same default as React Native: strip whatever scheme the host used.
+    prefixes = ['*'],
+    filter,
+    config,
+    getInitialURL = getInitialURLDefault,
+    subscribe = subscribeDefault,
+    getStateFromPath = getStateFromPathDefault,
+    getActionFromState = getActionFromStateDefault,
+  } = options ?? {};
+
+  const optionsRef = React.useRef({
+    enabled,
+    prefixes,
+    filter,
+    config,
+    getStateFromPath,
+    getActionFromState,
+  });
+
+  React.useEffect(() => {
+    optionsRef.current = {
+      enabled,
+      prefixes,
+      filter,
+      config,
+      getStateFromPath,
+      getActionFromState,
+    };
+  });
+
+  const getStateFromURL = React.useCallback(
+    (url: string | undefined, previous: NavigationState | undefined) => {
+      const current = optionsRef.current;
+
+      if (!url) {
+        return undefined;
+      }
+
+      const path = extractPath(url, current.prefixes, current.filter);
+
+      if (path == null) {
+        return undefined;
+      }
+
+      try {
+        return current.getStateFromPath(path, current.config, previous);
+      } catch {
+        // A malformed link should not take the card down with it.
+        return undefined;
+      }
+    },
+    []
+  );
+
+  const getInitialState = React.useCallback(():
+    | PartialState<NavigationState>
+    | undefined => {
+    if (!optionsRef.current.enabled) {
+      return undefined;
+    }
+
+    return getStateFromURL(getInitialURL(), undefined);
+    // Read once on mount: a later identity change must not re-run the route.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [getStateFromURL]);
+
+  React.useEffect(() => {
+    if (!enabled) {
+      return;
+    }
+
+    const listener = (url: string) => {
+      const navigation = ref.current;
+
+      if (!navigation) {
+        return;
+      }
+
+      const rootState = navigation.getRootState();
+      const state = getStateFromURL(url, rootState);
+
+      if (!state) {
+        return;
+      }
+
+      const action = optionsRef.current.getActionFromState(
+        state,
+        optionsRef.current.config
+      );
+
+      if (action === undefined) {
+        navigation.resetRoot(state);
+        return;
+      }
+
+      try {
+        navigation.dispatch({ target: rootState?.key, ...action });
+      } catch (e) {
+        console.warn(
+          `An error occurred when trying to handle the link '${url}': ${
+            e instanceof Error ? e.message : String(e)
+          }`
+        );
+      }
+    };
+
+    return subscribe(listener) ?? undefined;
+  }, [enabled, ref, getStateFromURL, subscribe]);
+
+  return { getInitialState };
+}