From 8b5688359828d6a9724888408e30e40fd1594844 Mon Sep 17 00:00:00 2001
From: Mark de Vocht <markd@wix.com>
Date: Wed, 13 May 2026 11:42:40 +0300
Subject: [PATCH 1/3] initial commit

---
 .../android/app/src/main/AndroidManifest.xml  |   6 +
 playground/e2e/DeepLinking.test.js            |  94 +++++
 playground/ios/playground/AppDelegate.mm      | 116 +++++-
 playground/ios/playground/Info.plist          |  11 +
 playground/src/app.ts                         |  64 ++++
 playground/src/screens/NavigationScreen.tsx   |   9 +
 playground/src/testIDs.ts                     |   4 +
 src/Navigation.ts                             |  37 +-
 src/NavigationDelegate.ts                     |  22 ++
 src/index.ts                                  |   1 +
 src/linking/DeferredLinkQueue.test.ts         |  60 +++
 src/linking/DeferredLinkQueue.ts              |  55 +++
 src/linking/LinkingHandler.test.ts            | 332 ++++++++++++++++
 src/linking/LinkingHandler.ts                 | 169 +++++++++
 src/linking/ModalLayoutBuilder.test.ts        | 105 +++++
 src/linking/ModalLayoutBuilder.ts             |  60 +++
 src/linking/RouteMatcher.test.ts              | 128 +++++++
 src/linking/RouteMatcher.ts                   | 126 ++++++
 src/linking/URLParser.test.ts                 | 105 +++++
 src/linking/URLParser.ts                      |  62 +++
 src/linking/types.ts                          | 115 ++++++
 website/docs/docs/docs-deep-linking.mdx       | 358 ++++++++++++++++++
 website/sidebars.js                           |   1 +
 23 files changed, 2036 insertions(+), 4 deletions(-)
 create mode 100644 playground/e2e/DeepLinking.test.js
 create mode 100644 src/linking/DeferredLinkQueue.test.ts
 create mode 100644 src/linking/DeferredLinkQueue.ts
 create mode 100644 src/linking/LinkingHandler.test.ts
 create mode 100644 src/linking/LinkingHandler.ts
 create mode 100644 src/linking/ModalLayoutBuilder.test.ts
 create mode 100644 src/linking/ModalLayoutBuilder.ts
 create mode 100644 src/linking/RouteMatcher.test.ts
 create mode 100644 src/linking/RouteMatcher.ts
 create mode 100644 src/linking/URLParser.test.ts
 create mode 100644 src/linking/URLParser.ts
 create mode 100644 src/linking/types.ts
 create mode 100644 website/docs/docs/docs-deep-linking.mdx

diff --git a/playground/android/app/src/main/AndroidManifest.xml b/playground/android/app/src/main/AndroidManifest.xml
index 4b0248b55f1..a10ba65a27e 100644
--- a/playground/android/app/src/main/AndroidManifest.xml
+++ b/playground/android/app/src/main/AndroidManifest.xml
@@ -25,6 +25,12 @@
                 <action android:name="android.intent.action.MAIN"/>
                 <category android:name="android.intent.category.LAUNCHER"/>
             </intent-filter>
+            <intent-filter>
+                <action android:name="android.intent.action.VIEW"/>
+                <category android:name="android.intent.category.DEFAULT"/>
+                <category android:name="android.intent.category.BROWSABLE"/>
+                <data android:scheme="rnnplayground"/>
+            </intent-filter>
         </activity>
     </application>
 </manifest>
diff --git a/playground/e2e/DeepLinking.test.js b/playground/e2e/DeepLinking.test.js
new file mode 100644
index 00000000000..242760c3111
--- /dev/null
+++ b/playground/e2e/DeepLinking.test.js
@@ -0,0 +1,94 @@
+import Utils from './Utils';
+import TestIDs from '../src/testIDs';
+
+const { elementById, sleep } = Utils;
+
+const NOTIFICATION_PAYLOAD = {
+  trigger: { type: 'push' },
+  title: 'Open Pushed Screen',
+  subtitle: 'Deep link test',
+  body: 'Tap to open Pushed 42',
+  badge: 1,
+  payload: { url: 'rnnplayground://pushed/42' },
+  'content-available': 0,
+  'action-identifier': 'default',
+};
+
+const NESTED_NOTIFICATION_PAYLOAD = {
+  ...NOTIFICATION_PAYLOAD,
+  body: 'Tap to open nested Pushed 42 / detail 99',
+  payload: { url: 'rnnplayground://pushed/42/detail/99' },
+};
+
+describe.e2e('Deep linking', () => {
+  beforeEach(async () => {
+    await device.launchApp({ newInstance: true });
+    await elementById(TestIDs.NAVIGATION_TAB).tap();
+  });
+
+  it('deep-link modal can be dismissed via the close button', async () => {
+    await device.openURL({ url: 'rnnplayground://pushed/42' });
+    await expect(elementById(TestIDs.PUSHED_SCREEN_HEADER)).toBeVisible();
+    await elementById(TestIDs.DEEP_LINK_CLOSE_BTN).tap();
+    await expect(elementById(TestIDs.NAVIGATION_SCREEN)).toBeVisible();
+  });
+
+  it('nested route builds a multi-screen stack inside the modal', async () => {
+    await elementById(TestIDs.SIMULATE_NESTED_DEEP_LINK_BTN).tap();
+    // The top-of-stack header proves the second Pushed segment mounted;
+    // the nested-route -> multi-segment expansion is what produced it.
+    await expect(elementById(TestIDs.PUSHED_SCREEN_HEADER)).toBeVisible();
+  });
+
+  it('unmatched URL does not present a modal and does not crash', async () => {
+    await device.openURL({ url: 'rnnplayground://nope' });
+    await sleep(500);
+    await expect(elementById(TestIDs.PUSHED_SCREEN_HEADER)).toBeNotVisible();
+    await expect(elementById(TestIDs.NAVIGATION_SCREEN)).toBeVisible();
+  });
+
+  it('OS-delivered URL while running opens the modal', async () => {
+    await device.openURL({ url: 'rnnplayground://pushed/77' });
+    await expect(elementById(TestIDs.PUSHED_SCREEN_HEADER)).toBeVisible();
+  });
+
+  it('OS-delivered URL with query params opens the modal (reserved keys filtered)', async () => {
+    await device.openURL({ url: 'rnnplayground://pushed/77?ref=test&source=push' });
+    await expect(elementById(TestIDs.PUSHED_SCREEN_HEADER)).toBeVisible();
+  });
+
+  it('cold-start deep link presents the modal after root mounts', async () => {
+    await device.launchApp({
+      newInstance: true,
+      url: 'rnnplayground://pushed/55',
+    });
+    await expect(elementById(TestIDs.PUSHED_SCREEN_HEADER)).toBeVisible();
+  });
+
+  it('tapping a notification with a url payload opens the deep link modal', async () => {
+    if (device.getPlatform() !== 'ios') {
+      return;
+    }
+    await device.sendUserNotification(NOTIFICATION_PAYLOAD);
+    await expect(elementById(TestIDs.PUSHED_SCREEN_HEADER)).toBeVisible();
+  });
+
+  it('tapping a notification with a nested url payload builds a multi-screen modal', async () => {
+    if (device.getPlatform() !== 'ios') {
+      return;
+    }
+    await device.sendUserNotification(NESTED_NOTIFICATION_PAYLOAD);
+    await expect(elementById(TestIDs.PUSHED_SCREEN_HEADER)).toBeVisible();
+  });
+
+  it('cold-start notification tap presents the modal after root mounts', async () => {
+    if (device.getPlatform() !== 'ios') {
+      return;
+    }
+    await device.launchApp({
+      newInstance: true,
+      userNotification: NOTIFICATION_PAYLOAD,
+    });
+    await expect(elementById(TestIDs.PUSHED_SCREEN_HEADER)).toBeVisible();
+  });
+});
diff --git a/playground/ios/playground/AppDelegate.mm b/playground/ios/playground/AppDelegate.mm
index c4b62a465c6..a2eba733d16 100644
--- a/playground/ios/playground/AppDelegate.mm
+++ b/playground/ios/playground/AppDelegate.mm
@@ -1,12 +1,23 @@
 #import "AppDelegate.h"
 #import "RNNCustomViewController.h"
 #import <ReactNativeNavigation/ReactNativeNavigation.h>
+#import <React/RCTBridge.h>
+#import <React/RCTLinkingManager.h>
+#import <React/RCTRootView.h>
+#import <UserNotifications/UserNotifications.h>
+
+// URLs that arrive (notification tap, openURL) before the JS bridge is
+// ready are queued here and flushed when the bridge finishes loading.
+// Without this, cold-start notifications would post `RCTOpenURLNotification`
+// into the void because RCTLinkingManager hasn't subscribed yet.
+static NSMutableArray<NSURL *> *gPendingDeepLinkURLs = nil;
+static BOOL gJavaScriptDidLoad = NO;
 
 #if !RNN_RN_VERSION_79_OR_NEWER
-@interface AppDelegate () <RCTBridgeDelegate>
+@interface AppDelegate () <RCTBridgeDelegate, UNUserNotificationCenterDelegate>
 @end
 #else
-@interface AppDelegate ()
+@interface AppDelegate () <UNUserNotificationCenterDelegate>
 @end
 
 @interface ReactNativeDelegate : RCTDefaultReactNativeFactoryDelegate
@@ -51,10 +62,109 @@ - (BOOL)application:(UIApplication *)application
 	 callback:^UIViewController *(NSDictionary *props, RCTHost *host) {
 		return [[RNNCustomViewController alloc] initWithProps:props];
 	}];
-	
+
+	// Receive notification taps (Detox sendUserNotification & real push taps)
+	[UNUserNotificationCenter currentNotificationCenter].delegate = self;
+
+	// Flush deep links that arrived before the JS bridge was up.
+	// In legacy mode `RCTJavaScriptDidLoadNotification` fires after the
+	// bridge loads JS. In bridgeless/new-arch that notification does NOT
+	// fire, so we also listen for `RCTContentDidAppearNotification` which
+	// is posted by Fabric's root view once content has rendered — by which
+	// point RCTLinkingManager is already instantiated and listening.
+	[[NSNotificationCenter defaultCenter] addObserver:self
+                                             selector:@selector(handleJavaScriptDidLoad:)
+                                                 name:RCTJavaScriptDidLoadNotification
+                                               object:nil];
+	[[NSNotificationCenter defaultCenter] addObserver:self
+                                             selector:@selector(handleJavaScriptDidLoad:)
+                                                 name:RCTContentDidAppearNotification
+                                               object:nil];
+
 	return YES;
 }
 
+#pragma mark - Deep linking
+
+// Forward foreground URL openings (custom schemes & universal links)
+// to React Native's Linking module so JS can handle them.
+- (BOOL)application:(UIApplication *)application
+            openURL:(NSURL *)url
+            options:(NSDictionary<UIApplicationOpenURLOptionsKey, id> *)options {
+	[self dispatchDeepLinkURL:url];
+	return YES;
+}
+
+// Dispatch a deep link URL. If RCTLinkingManager hasn't subscribed yet
+// (cold-start, JS bridge still loading), queue it for replay after
+// RCTJavaScriptDidLoadNotification fires.
+- (void)dispatchDeepLinkURL:(NSURL *)url {
+	if (url == nil) { return; }
+	if (gJavaScriptDidLoad) {
+		[RCTLinkingManager application:[UIApplication sharedApplication]
+                               openURL:url
+                               options:@{}];
+		return;
+	}
+	if (gPendingDeepLinkURLs == nil) {
+		gPendingDeepLinkURLs = [NSMutableArray array];
+	}
+	[gPendingDeepLinkURLs addObject:url];
+}
+
+- (void)handleJavaScriptDidLoad:(NSNotification *)notification {
+	gJavaScriptDidLoad = YES;
+	NSArray<NSURL *> *pending = [gPendingDeepLinkURLs copy];
+	[gPendingDeepLinkURLs removeAllObjects];
+	for (NSURL *url in pending) {
+		[RCTLinkingManager application:[UIApplication sharedApplication]
+                               openURL:url
+                               options:@{}];
+	}
+}
+
+- (BOOL)application:(UIApplication *)application
+continueUserActivity:(NSUserActivity *)userActivity
+ restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> *))restorationHandler {
+	return [RCTLinkingManager application:application
+                    continueUserActivity:userActivity
+                      restorationHandler:restorationHandler];
+}
+
+#pragma mark - UNUserNotificationCenterDelegate
+
+// Surface notifications while the app is in the foreground so the user
+// (and Detox) can see them before the tap is simulated.
+//
+// NOTE: `UNNotificationPresentationOptionAlert` is intentionally included
+// alongside the iOS 14+ `.banner`/`.list` flags because Detox checks
+// `options.contains(.alert)` in DetoxUserNotificationDispatcher before
+// invoking the tap path. Dropping `.alert` would break e2e notification
+// tests on Detox even though iOS 14+ otherwise prefers banner/list.
+- (void)userNotificationCenter:(UNUserNotificationCenter *)center
+       willPresentNotification:(UNNotification *)notification
+         withCompletionHandler:(void (^)(UNNotificationPresentationOptions))completionHandler {
+	completionHandler(UNNotificationPresentationOptionAlert |
+                      UNNotificationPresentationOptionBanner |
+                      UNNotificationPresentationOptionList |
+                      UNNotificationPresentationOptionSound);
+}
+
+// Notification tap → if payload carries `url`, route it through the
+// existing Linking pipeline so deep linking reacts the same way regardless
+// of whether the URL came from the OS or a notification.
+- (void)userNotificationCenter:(UNUserNotificationCenter *)center
+didReceiveNotificationResponse:(UNNotificationResponse *)response
+         withCompletionHandler:(void (^)(void))completionHandler {
+	NSDictionary *userInfo = response.notification.request.content.userInfo;
+	NSString *urlString = userInfo[@"url"];
+	if ([urlString isKindOfClass:[NSString class]]) {
+		NSURL *url = [NSURL URLWithString:urlString];
+		[self dispatchDeepLinkURL:url];
+	}
+	completionHandler();
+}
+
 #if !RNN_RN_VERSION_79_OR_NEWER
 #pragma mark - RCTBridgeDelegate
 - (NSURL *)sourceURLForBridge:(RCTBridge *)bridge
diff --git a/playground/ios/playground/Info.plist b/playground/ios/playground/Info.plist
index a55cc249cd1..64d8b689ec8 100644
--- a/playground/ios/playground/Info.plist
+++ b/playground/ios/playground/Info.plist
@@ -18,6 +18,17 @@
 	<string>1.0.0</string>
 	<key>CFBundleSignature</key>
 	<string>????</string>
+	<key>CFBundleURLTypes</key>
+	<array>
+		<dict>
+			<key>CFBundleURLName</key>
+			<string>com.reactnativenavigation.playground</string>
+			<key>CFBundleURLSchemes</key>
+			<array>
+				<string>rnnplayground</string>
+			</array>
+		</dict>
+	</array>
 	<key>CFBundleVersion</key>
 	<string>1</string>
 	<key>LSRequiresIPhoneOS</key>
diff --git a/playground/src/app.ts b/playground/src/app.ts
index e00ec855bd5..e8a077eac4e 100644
--- a/playground/src/app.ts
+++ b/playground/src/app.ts
@@ -1,3 +1,4 @@
+import { Navigation as RNNavigation } from 'react-native-navigation';
 import Navigation from './services/Navigation';
 import { registerScreens } from './screens';
 import addProcessors from './commons/Processors';
@@ -21,12 +22,75 @@ function start() {
   registerScreens();
   addProcessors();
   setDefaultOptions();
+  configureDeepLinking();
   Navigation.events().registerAppLaunchedListener(async () => {
     Navigation.dismissAllModals();
     setRoot();
   });
 }
 
+function configureDeepLinking() {
+  RNNavigation.setLinking({
+    prefixes: ['rnnplayground://'],
+    config: {
+      screens: {
+        Pushed: {
+          path: 'pushed/:id',
+          screens: {
+            Pushed: 'detail/:detailId',
+          },
+        },
+        BackButton: 'back-button',
+      },
+    },
+    // Wrap the default modal so the first screen has a close button.
+    // Without this, a single-segment match would not provide a way to
+    // dismiss the modal back to the app.
+    getModal: (match) => ({
+      stack: {
+        children: match.path.map((segment, index) => ({
+          component: {
+            name: segment.screen,
+            passProps: filterReservedProps({ ...match.queryParams, ...segment.params }),
+            options:
+              index === 0
+                ? {
+                    topBar: {
+                      leftButtons: [
+                        {
+                          id: 'deepLinkClose',
+                          testID: testIDs.DEEP_LINK_CLOSE_BTN,
+                          text: 'Close',
+                        },
+                      ],
+                    },
+                  }
+                : undefined,
+          },
+        })),
+      },
+    }),
+    fallback: (url) => {
+      console.warn('Unmatched deep link:', url);
+    },
+  });
+
+  RNNavigation.events().registerNavigationButtonPressedListener(({ buttonId, componentId }) => {
+    if (buttonId === 'deepLinkClose') {
+      RNNavigation.dismissModal(componentId);
+    }
+  });
+}
+
+const RESERVED_PROPS = new Set(['ref', 'key']);
+function filterReservedProps(props: Record<string, string>): Record<string, string> {
+  const out: Record<string, string> = {};
+  Object.keys(props).forEach((k) => {
+    if (!RESERVED_PROPS.has(k)) out[k] = props[k];
+  });
+  return out;
+}
+
 function setRoot() {
   Navigation.setRoot({
     root: {
diff --git a/playground/src/screens/NavigationScreen.tsx b/playground/src/screens/NavigationScreen.tsx
index d2e4da5b6c7..b366bd6585b 100644
--- a/playground/src/screens/NavigationScreen.tsx
+++ b/playground/src/screens/NavigationScreen.tsx
@@ -1,6 +1,7 @@
 import React from 'react';
 import { Platform } from 'react-native';
 import {
+  Navigation as RNNavigation,
   NavigationComponent,
   NavigationProps,
   OptionsModalPresentationStyle,
@@ -22,6 +23,7 @@ const {
   PAGE_SHEET_MODAL_BTN,
   NAVIGATION_SCREEN,
   BACK_BUTTON_SCREEN_BTN,
+  SIMULATE_NESTED_DEEP_LINK_BTN,
 } = testIDs;
 
 interface Props extends NavigationProps {}
@@ -94,6 +96,11 @@ export default class NavigationScreen extends NavigationComponent<Props> {
         <Button label="Shared Element (Cocktails)" onPress={this.sharedElement} />
         <Button label="Shared Element (Car Dealer)" onPress={this.sharedElementAlt} />
         <Button label="Shared Element (ImageGallery)" onPress={this.sharedElementImageGallery} />
+        <Button
+          label="Simulate Nested Deep Link"
+          testID={SIMULATE_NESTED_DEEP_LINK_BTN}
+          onPress={this.simulateNestedDeepLink}
+        />
         {Platform.OS === 'ios' && (
           <Navigation.TouchablePreview
             touchableComponent={Button}
@@ -124,6 +131,8 @@ export default class NavigationScreen extends NavigationComponent<Props> {
   sharedElement = () => Navigation.showModal(Screens.CocktailsListScreen);
   sharedElementAlt = () => Navigation.push(this, Screens.CarsListScreen);
   sharedElementImageGallery = () => Navigation.push(this, Screens.ImageGalleryListScreen);
+  simulateNestedDeepLink = () =>
+    RNNavigation.handleDeepLink('rnnplayground://pushed/42/detail/99');
   preview = ({ reactTag }: { reactTag: number | null }) => {
     if (reactTag === null) {
       return;
diff --git a/playground/src/testIDs.ts b/playground/src/testIDs.ts
index d1cb6c9562f..8a6d5c7823c 100644
--- a/playground/src/testIDs.ts
+++ b/playground/src/testIDs.ts
@@ -263,6 +263,10 @@ const testIDs = {
   // BottomTab Role
   BOTTOM_TABS_ROLE_BTN: 'BOTTOM_TABS_ROLE_BTN',
   BOTTOM_TABS_ROLE_SEARCH_TAB: 'BOTTOM_TABS_ROLE_SEARCH_TAB',
+
+  // Deep Linking
+  SIMULATE_NESTED_DEEP_LINK_BTN: 'SIMULATE_NESTED_DEEP_LINK_BTN',
+  DEEP_LINK_CLOSE_BTN: 'DEEP_LINK_CLOSE_BTN',
 };
 
 export default testIDs;
diff --git a/src/Navigation.ts b/src/Navigation.ts
index 2cdcf54a8cf..fda247f82b4 100644
--- a/src/Navigation.ts
+++ b/src/Navigation.ts
@@ -28,6 +28,8 @@ import { LayoutProcessorsStore } from './processors/LayoutProcessorsStore';
 import { CommandName } from './interfaces/CommandName';
 import { OptionsCrawler } from './commands/OptionsCrawler';
 import { OptionsProcessor as OptionProcessor } from './interfaces/Processors';
+import { LinkingHandler } from './linking/LinkingHandler';
+import { LinkingConfig } from './linking/types';
 
 export class NavigationRoot {
   public readonly TouchablePreview = TouchablePreview;
@@ -45,6 +47,7 @@ export class NavigationRoot {
   private readonly componentEventsObserver: ComponentEventsObserver;
   private readonly componentWrapper: ComponentWrapper;
   private readonly optionsCrawler: OptionsCrawler;
+  private readonly linkingHandler: LinkingHandler;
 
   constructor(
     private readonly nativeCommandsSender: NativeCommandsSender,
@@ -96,6 +99,7 @@ export class NavigationRoot {
       this.commandsObserver,
       this.componentEventsObserver
     );
+    this.linkingHandler = new LinkingHandler((layout) => this.commands.showModal(layout));
 
     this.componentEventsObserver.registerOnceForAllComponentEvents();
   }
@@ -168,7 +172,9 @@ export class NavigationRoot {
    * Reset the app to a new layout
    */
   public setRoot(layout: LayoutRoot): Promise<string> {
-    return this.commands.setRoot(layout);
+    const result = this.commands.setRoot(layout);
+    result.then(() => this.linkingHandler.setRootReady()).catch(() => {});
+    return result;
   }
 
   /**
@@ -280,6 +286,35 @@ export class NavigationRoot {
     return this.commands.getLaunchArgs();
   }
 
+  /**
+   * Configure deep link handling. Maps URL prefixes and path patterns to
+   * RNN components. By default each matched link is presented as a modal
+   * (wrapped in a stack so a topBar close button can be configured); supply
+   * `getModal` to customize the modal layout or `onLink` to bypass the
+   * default behavior entirely.
+   */
+  public setLinking(config: LinkingConfig): void {
+    this.linkingHandler.configure(config);
+  }
+
+  /**
+   * Manually run a URL through the deep link pipeline as if it had been
+   * delivered by the OS. Useful for URLs received from push notifications
+   * or other non-`Linking` sources.
+   */
+  public handleDeepLink(url: string): void {
+    this.linkingHandler.handleURL(url);
+  }
+
+  /**
+   * Signal that the app is ready to process deep links (e.g. after the
+   * user has authenticated). When set to `true`, any links that were
+   * queued while not ready are replayed in order.
+   */
+  public setLinkingReady(ready: boolean): void {
+    this.linkingHandler.setLinkingReady(ready);
+  }
+
   /**
    * Obtain the events registry instance
    */
diff --git a/src/NavigationDelegate.ts b/src/NavigationDelegate.ts
index 2c27a0f62b9..714e8d2a623 100644
--- a/src/NavigationDelegate.ts
+++ b/src/NavigationDelegate.ts
@@ -10,6 +10,7 @@ import { NavigationRoot } from './Navigation';
 import { NativeCommandsSender } from './adapters/NativeCommandsSender';
 import { NativeEventsReceiver } from './adapters/NativeEventsReceiver';
 import { AppRegistryService } from './adapters/AppRegistryService';
+import { LinkingConfig } from './linking/types';
 
 export class NavigationDelegate {
   private concreteNavigation: NavigationRoot;
@@ -204,6 +205,27 @@ export class NavigationDelegate {
     return this.concreteNavigation.getLaunchArgs();
   }
 
+  /**
+   * Configure deep link handling.
+   */
+  public setLinking(config: LinkingConfig): void {
+    this.concreteNavigation.setLinking(config);
+  }
+
+  /**
+   * Manually feed a URL into the deep link pipeline.
+   */
+  public handleDeepLink(url: string): void {
+    this.concreteNavigation.handleDeepLink(url);
+  }
+
+  /**
+   * Signal readiness to process deep links. Flushes any queued links.
+   */
+  public setLinkingReady(ready: boolean): void {
+    this.concreteNavigation.setLinkingReady(ready);
+  }
+
   /**
    * Obtain the events registry instance
    */
diff --git a/src/index.ts b/src/index.ts
index 230459f720c..eab2ffd549a 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -16,3 +16,4 @@ export * from './interfaces/NavigationFunctionComponent';
 export * from './interfaces/CommandName';
 export * from './interfaces/Processors';
 export * from './interfaces/ProcessorSubscription';
+export * from './linking/types';
diff --git a/src/linking/DeferredLinkQueue.test.ts b/src/linking/DeferredLinkQueue.test.ts
new file mode 100644
index 00000000000..2fae94de721
--- /dev/null
+++ b/src/linking/DeferredLinkQueue.test.ts
@@ -0,0 +1,60 @@
+import { DeferredLinkQueue } from './DeferredLinkQueue';
+
+describe('DeferredLinkQueue', () => {
+  let uut: DeferredLinkQueue;
+  let flushed: string[];
+
+  beforeEach(() => {
+    uut = new DeferredLinkQueue();
+    flushed = [];
+    uut.setFlushCallback((url) => flushed.push(url));
+  });
+
+  it('starts not ready', () => {
+    expect(uut.isReady()).toBe(false);
+  });
+
+  it('enqueues URLs while not ready', () => {
+    uut.enqueue('myapp://a');
+    uut.enqueue('myapp://b');
+    expect(uut.pending()).toEqual(['myapp://a', 'myapp://b']);
+    expect(flushed).toEqual([]);
+  });
+
+  it('flushes queued URLs in order when becoming ready', () => {
+    uut.enqueue('myapp://a');
+    uut.enqueue('myapp://b');
+    uut.setReady(true);
+    expect(flushed).toEqual(['myapp://a', 'myapp://b']);
+    expect(uut.pending()).toEqual([]);
+  });
+
+  it('does not re-flush when already ready', () => {
+    uut.setReady(true);
+    uut.enqueue('myapp://a');
+    uut.setReady(true);
+    expect(flushed).toEqual([]);
+    expect(uut.pending()).toEqual(['myapp://a']);
+  });
+
+  it('flushes again after toggling not-ready → ready', () => {
+    uut.setReady(true);
+    uut.setReady(false);
+    uut.enqueue('myapp://x');
+    uut.setReady(true);
+    expect(flushed).toEqual(['myapp://x']);
+  });
+
+  it('clear() drops pending URLs', () => {
+    uut.enqueue('myapp://a');
+    uut.clear();
+    uut.setReady(true);
+    expect(flushed).toEqual([]);
+  });
+
+  it('flush() is a no-op when no callback is registered', () => {
+    const fresh = new DeferredLinkQueue();
+    fresh.enqueue('myapp://a');
+    expect(() => fresh.flush()).not.toThrow();
+  });
+});
diff --git a/src/linking/DeferredLinkQueue.ts b/src/linking/DeferredLinkQueue.ts
new file mode 100644
index 00000000000..42da88a956c
--- /dev/null
+++ b/src/linking/DeferredLinkQueue.ts
@@ -0,0 +1,55 @@
+/**
+ * Holds URLs while the linking pipeline is not ready and replays them in
+ * order once it becomes ready.
+ *
+ * Readiness is set by the owning `LinkingHandler` and reflects the combined
+ * state of:
+ *   - whether the first `setRoot` has resolved (so a modal can be presented),
+ *   - whether the user-supplied `isReady` predicate (if any) returns `true`.
+ */
+export class DeferredLinkQueue {
+  private queue: string[] = [];
+  private ready = false;
+  private flushCallback: ((url: string) => void) | null = null;
+
+  public setFlushCallback(callback: (url: string) => void): void {
+    this.flushCallback = callback;
+  }
+
+  public setReady(ready: boolean): void {
+    const becameReady = !this.ready && ready;
+    this.ready = ready;
+    if (becameReady) {
+      this.flush();
+    }
+  }
+
+  public isReady(): boolean {
+    return this.ready;
+  }
+
+  /**
+   * Enqueue a URL for later processing. Should only be called when the
+   * queue is not ready; the handler decides when to enqueue vs process.
+   */
+  public enqueue(url: string): void {
+    this.queue.push(url);
+  }
+
+  public flush(): void {
+    if (!this.flushCallback) return;
+    const pending = [...this.queue];
+    this.queue = [];
+    for (const url of pending) {
+      this.flushCallback(url);
+    }
+  }
+
+  public clear(): void {
+    this.queue = [];
+  }
+
+  public pending(): string[] {
+    return [...this.queue];
+  }
+}
diff --git a/src/linking/LinkingHandler.test.ts b/src/linking/LinkingHandler.test.ts
new file mode 100644
index 00000000000..cb35b4c8da4
--- /dev/null
+++ b/src/linking/LinkingHandler.test.ts
@@ -0,0 +1,332 @@
+import { LinkingHandler, LinkingAPI } from './LinkingHandler';
+import { LinkingConfig, RouteMatch } from './types';
+import { Layout } from '../interfaces/Layout';
+
+describe('LinkingHandler', () => {
+  let uut: LinkingHandler;
+  let mockShowModal: jest.Mock<Promise<string>, [Layout]>;
+  let mockLinking: jest.Mocked<LinkingAPI>;
+  let urlListener: ((event: { url: string }) => void) | null;
+
+  const baseConfig: LinkingConfig = {
+    prefixes: ['myapp://', 'https://myapp.com'],
+    config: {
+      screens: {
+        Home: 'home',
+        Profile: 'user/:id',
+        Settings: {
+          path: 'settings',
+          screens: { Notifications: 'notifications' },
+        },
+      },
+    },
+  };
+
+  beforeEach(() => {
+    mockShowModal = jest.fn().mockResolvedValue('modalId');
+    urlListener = null;
+    mockLinking = {
+      addEventListener: jest.fn((_type, handler) => {
+        urlListener = handler;
+        return { remove: jest.fn() };
+      }),
+      getInitialURL: jest.fn().mockResolvedValue(null),
+    } as unknown as jest.Mocked<LinkingAPI>;
+    uut = new LinkingHandler(mockShowModal, mockLinking);
+  });
+
+  afterEach(() => {
+    uut.teardown();
+  });
+
+  describe('resolve', () => {
+    beforeEach(() => uut.configure(baseConfig));
+
+    it('resolves a simple URL to a route match', () => {
+      expect(uut.resolve('myapp://home')).toEqual({
+        url: 'myapp://home',
+        path: [{ screen: 'Home', params: {} }],
+        queryParams: {},
+      });
+    });
+
+    it('resolves a URL with path params', () => {
+      expect(uut.resolve('myapp://user/42')).toEqual({
+        url: 'myapp://user/42',
+        path: [{ screen: 'Profile', params: { id: '42' } }],
+        queryParams: {},
+      });
+    });
+
+    it('resolves a nested route as a chain', () => {
+      const match = uut.resolve('myapp://settings/notifications');
+      expect(match?.path).toEqual([
+        { screen: 'Settings', params: {} },
+        { screen: 'Notifications', params: {} },
+      ]);
+    });
+
+    it('returns null when the prefix does not match', () => {
+      expect(uut.resolve('other://home')).toBeNull();
+    });
+
+    it('returns null when no route matches', () => {
+      expect(uut.resolve('myapp://unknown')).toBeNull();
+    });
+
+    it('returns null before configure() is called', () => {
+      const fresh = new LinkingHandler(mockShowModal, mockLinking);
+      expect(fresh.resolve('myapp://home')).toBeNull();
+    });
+  });
+
+  describe('default modal presentation', () => {
+    it('defers links until rootReady is signalled, then auto-flushes', () => {
+      uut.configure(baseConfig);
+      uut.handleURL('myapp://home');
+      expect(mockShowModal).not.toHaveBeenCalled();
+      uut.setRootReady();
+      expect(mockShowModal).toHaveBeenCalledTimes(1);
+      expect(mockShowModal).toHaveBeenCalledWith({
+        stack: {
+          children: [{ component: { name: 'Home', passProps: {} } }],
+        },
+      });
+    });
+
+    it('processes links immediately once rootReady', () => {
+      uut.configure(baseConfig);
+      uut.setRootReady();
+      uut.handleURL('myapp://user/42');
+      expect(mockShowModal).toHaveBeenCalledWith({
+        stack: {
+          children: [{ component: { name: 'Profile', passProps: { id: '42' } } }],
+        },
+      });
+    });
+
+    it('builds a push chain inside the modal stack for nested matches', () => {
+      uut.configure(baseConfig);
+      uut.setRootReady();
+      uut.handleURL('myapp://settings/notifications');
+      expect(mockShowModal).toHaveBeenCalledWith({
+        stack: {
+          children: [
+            { component: { name: 'Settings', passProps: {} } },
+            { component: { name: 'Notifications', passProps: {} } },
+          ],
+        },
+      });
+    });
+
+    it('merges query params into passProps', () => {
+      uut.configure(baseConfig);
+      uut.setRootReady();
+      uut.handleURL('myapp://user/42?source=push');
+      expect(mockShowModal).toHaveBeenCalledWith({
+        stack: {
+          children: [
+            {
+              component: {
+                name: 'Profile',
+                passProps: { id: '42', source: 'push' },
+              },
+            },
+          ],
+        },
+      });
+    });
+
+    it('filters React-reserved query params from passProps', () => {
+      uut.configure(baseConfig);
+      uut.setRootReady();
+      uut.handleURL('myapp://user/42?ref=push&key=abc&utm=foo');
+      expect(mockShowModal).toHaveBeenCalledWith({
+        stack: {
+          children: [
+            {
+              component: {
+                name: 'Profile',
+                passProps: { id: '42', utm: 'foo' },
+              },
+            },
+          ],
+        },
+      });
+    });
+  });
+
+  describe('getModal override', () => {
+    it('uses the supplied builder instead of the default', () => {
+      const customLayout: Layout = {
+        component: { name: 'Custom' },
+      };
+      const getModal = jest.fn().mockReturnValue(customLayout);
+      uut.configure({ ...baseConfig, getModal });
+      uut.setRootReady();
+      uut.handleURL('myapp://home');
+      expect(getModal).toHaveBeenCalledTimes(1);
+      const passedMatch = getModal.mock.calls[0][0];
+      expect(passedMatch.path).toEqual([{ screen: 'Home', params: {} }]);
+      expect(mockShowModal).toHaveBeenCalledWith(customLayout);
+    });
+
+    it('skips presentation when getModal returns undefined', () => {
+      const getModal = jest.fn().mockReturnValue(undefined);
+      uut.configure({ ...baseConfig, getModal });
+      uut.setRootReady();
+      uut.handleURL('myapp://home');
+      expect(getModal).toHaveBeenCalled();
+      expect(mockShowModal).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('onLink override', () => {
+    it('calls onLink and bypasses showModal entirely', () => {
+      const onLink = jest.fn();
+      uut.configure({ ...baseConfig, onLink });
+      uut.setRootReady();
+      uut.handleURL('myapp://user/42');
+      expect(onLink).toHaveBeenCalledTimes(1);
+      const passedMatch = onLink.mock.calls[0][0];
+      expect(passedMatch.path).toEqual([{ screen: 'Profile', params: { id: '42' } }]);
+      expect(mockShowModal).not.toHaveBeenCalled();
+    });
+
+    it('takes precedence over getModal', () => {
+      const onLink = jest.fn();
+      const getModal = jest.fn();
+      uut.configure({ ...baseConfig, onLink, getModal });
+      uut.setRootReady();
+      uut.handleURL('myapp://home');
+      expect(onLink).toHaveBeenCalled();
+      expect(getModal).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('fallback', () => {
+    it('is called when no prefix matches', () => {
+      const fallback = jest.fn();
+      uut.configure({ ...baseConfig, fallback });
+      uut.setRootReady();
+      uut.handleURL('other://home');
+      expect(fallback).toHaveBeenCalledWith('other://home');
+      expect(mockShowModal).not.toHaveBeenCalled();
+    });
+
+    it('is called when no route matches', () => {
+      const fallback = jest.fn();
+      uut.configure({ ...baseConfig, fallback });
+      uut.setRootReady();
+      uut.handleURL('myapp://unknown');
+      expect(fallback).toHaveBeenCalledWith('myapp://unknown');
+      expect(mockShowModal).not.toHaveBeenCalled();
+    });
+
+    it('is silent when not supplied', () => {
+      uut.configure(baseConfig);
+      uut.setRootReady();
+      expect(() => uut.handleURL('myapp://unknown')).not.toThrow();
+      expect(mockShowModal).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('isReady predicate', () => {
+    it('queues links while isReady returns false', () => {
+      let ready = false;
+      uut.configure({ ...baseConfig, isReady: () => ready });
+      uut.setRootReady();
+      uut.handleURL('myapp://home');
+      expect(mockShowModal).not.toHaveBeenCalled();
+      ready = true;
+      uut.setLinkingReady(true);
+      expect(mockShowModal).toHaveBeenCalledTimes(1);
+    });
+
+    it('setLinkingReady(true) overrides a false isReady', () => {
+      uut.configure({ ...baseConfig, isReady: () => false });
+      uut.setRootReady();
+      uut.setLinkingReady(true);
+      uut.handleURL('myapp://home');
+      expect(mockShowModal).toHaveBeenCalled();
+    });
+
+    it('setLinkingReady(false) blocks even when isReady is absent', () => {
+      uut.configure(baseConfig);
+      uut.setRootReady();
+      uut.setLinkingReady(false);
+      uut.handleURL('myapp://home');
+      expect(mockShowModal).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('Linking subscription', () => {
+    it('dispatches URL events through the pipeline', () => {
+      uut.configure(baseConfig);
+      uut.setRootReady();
+      urlListener?.({ url: 'myapp://home' });
+      expect(mockShowModal).toHaveBeenCalled();
+    });
+
+    it('reads the initial URL on configure', async () => {
+      mockLinking.getInitialURL.mockResolvedValueOnce('myapp://home');
+      uut.configure(baseConfig);
+      uut.setRootReady();
+      await Promise.resolve();
+      await Promise.resolve();
+      expect(mockShowModal).toHaveBeenCalled();
+    });
+
+    it('removes the listener on teardown', () => {
+      const remove = jest.fn();
+      (mockLinking.addEventListener as jest.Mock).mockReturnValueOnce({ remove });
+      uut.configure(baseConfig);
+      uut.teardown();
+      expect(remove).toHaveBeenCalled();
+    });
+
+    it('reconfiguring tears down the previous subscription', () => {
+      const remove = jest.fn();
+      (mockLinking.addEventListener as jest.Mock).mockReturnValueOnce({ remove });
+      uut.configure(baseConfig);
+      uut.configure(baseConfig);
+      expect(remove).toHaveBeenCalled();
+    });
+  });
+
+  describe('setRootReady', () => {
+    it('is idempotent', () => {
+      uut.configure(baseConfig);
+      uut.handleURL('myapp://home');
+      uut.setRootReady();
+      uut.setRootReady();
+      expect(mockShowModal).toHaveBeenCalledTimes(1);
+    });
+
+    it('persists across reconfigure', () => {
+      uut.setRootReady();
+      uut.configure(baseConfig);
+      uut.handleURL('myapp://home');
+      expect(mockShowModal).toHaveBeenCalled();
+    });
+  });
+
+  describe('match payload', () => {
+    it('passes the full match object to onLink', () => {
+      let captured: RouteMatch | null = null;
+      uut.configure({
+        ...baseConfig,
+        onLink: (match) => {
+          captured = match;
+        },
+      });
+      uut.setRootReady();
+      uut.handleURL('myapp://user/42?source=push');
+      expect(captured).toEqual({
+        url: 'myapp://user/42?source=push',
+        path: [{ screen: 'Profile', params: { id: '42' } }],
+        queryParams: { source: 'push' },
+      });
+    });
+  });
+});
diff --git a/src/linking/LinkingHandler.ts b/src/linking/LinkingHandler.ts
new file mode 100644
index 00000000000..7db0a50172b
--- /dev/null
+++ b/src/linking/LinkingHandler.ts
@@ -0,0 +1,169 @@
+import { Linking } from 'react-native';
+import { Layout } from '../interfaces/Layout';
+import { URLParser } from './URLParser';
+import { RouteMatcher } from './RouteMatcher';
+import { DeferredLinkQueue } from './DeferredLinkQueue';
+import { ModalLayoutBuilder } from './ModalLayoutBuilder';
+import { LinkingConfig, RouteMatch } from './types';
+
+/** A function that shows a layout as a modal. Mirrors `Commands.showModal`. */
+export type ShowModal = (layout: Layout) => Promise<string>;
+
+/**
+ * Minimal abstraction over React Native's `Linking` module so the handler
+ * can be tested without touching native bindings.
+ */
+export interface LinkingAPI {
+  addEventListener(
+    type: 'url',
+    handler: (event: { url: string }) => void
+  ): { remove: () => void };
+  getInitialURL(): Promise<string | null>;
+}
+
+/**
+ * Orchestrates deep linking:
+ *
+ *   1. Subscribes to URL events from `Linking` and the initial URL.
+ *   2. Parses + matches each URL against the configured `screens` tree.
+ *   3. Defers processing until both:
+ *        - the first `setRoot` has resolved (so a modal can be presented), and
+ *        - the user-supplied `isReady` predicate (if any) returns `true`.
+ *   4. Resolves matches in this order:
+ *        - `onLink(match)` if provided (full escape hatch), else
+ *        - `getModal(match)` if provided, else
+ *        - the default `ModalLayoutBuilder` output.
+ *      Result is presented via `showModal`.
+ *   5. Calls `fallback(url)` when a URL has no matching prefix or route.
+ */
+export class LinkingHandler {
+  private readonly urlParser: URLParser;
+  private readonly routeMatcher: RouteMatcher;
+  private readonly deferredQueue: DeferredLinkQueue;
+  private readonly modalLayoutBuilder: ModalLayoutBuilder;
+  private readonly showModal: ShowModal;
+  private readonly linkingAPI: LinkingAPI;
+
+  private config: LinkingConfig | null = null;
+  private linkingSubscription: { remove: () => void } | null = null;
+  private rootReady = false;
+  private userReadyOverride: boolean | null = null;
+
+  constructor(showModal: ShowModal, linkingAPI?: LinkingAPI) {
+    this.urlParser = new URLParser();
+    this.routeMatcher = new RouteMatcher();
+    this.deferredQueue = new DeferredLinkQueue();
+    this.modalLayoutBuilder = new ModalLayoutBuilder();
+    this.showModal = showModal;
+    this.linkingAPI = linkingAPI || (Linking as unknown as LinkingAPI);
+    this.deferredQueue.setFlushCallback((url) => this.processURL(url));
+  }
+
+  public configure(config: LinkingConfig): void {
+    this.teardown();
+    this.config = config;
+
+    const tree = this.routeMatcher.buildRouteTree(config.config.screens);
+    this.routeMatcher.setRouteTree(tree);
+
+    this.refreshReady();
+    this.subscribe();
+  }
+
+  /**
+   * Manually feed a URL into the pipeline as if it came from the OS.
+   * Useful for URLs received from push notifications or other sources.
+   */
+  public handleURL(url: string): void {
+    if (!this.config) return;
+    if (!this.isReady()) {
+      this.deferredQueue.enqueue(url);
+      return;
+    }
+    this.processURL(url);
+  }
+
+  /**
+   * Called by `NavigationRoot` after the first `setRoot` resolves. Subsequent
+   * calls are no-ops.
+   */
+  public setRootReady(): void {
+    if (this.rootReady) return;
+    this.rootReady = true;
+    this.refreshReady();
+  }
+
+  /**
+   * Public toggle for the app-supplied readiness gate. Overrides the
+   * `config.isReady` predicate from the moment it's first called.
+   */
+  public setLinkingReady(ready: boolean): void {
+    this.userReadyOverride = ready;
+    this.refreshReady();
+  }
+
+  /**
+   * Resolve a URL to a `RouteMatch` without side effects. Returns `null`
+   * when the URL doesn't match any configured prefix or route.
+   */
+  public resolve(url: string): RouteMatch | null {
+    if (!this.config) return null;
+    const parsed = this.urlParser.parse(url, this.config.prefixes);
+    if (!parsed) return null;
+    return this.routeMatcher.match(parsed.path, url, parsed.queryParams);
+  }
+
+  public teardown(): void {
+    if (this.linkingSubscription) {
+      this.linkingSubscription.remove();
+      this.linkingSubscription = null;
+    }
+    this.deferredQueue.clear();
+    this.config = null;
+    this.userReadyOverride = null;
+  }
+
+  private subscribe(): void {
+    this.linkingSubscription = this.linkingAPI.addEventListener('url', (event) => {
+      this.handleURL(event.url);
+    });
+
+    this.linkingAPI.getInitialURL().then((url) => {
+      if (url) this.handleURL(url);
+    });
+  }
+
+  private processURL(url: string): void {
+    if (!this.config) return;
+
+    const match = this.resolve(url);
+    if (!match) {
+      this.config.fallback?.(url);
+      return;
+    }
+
+    if (this.config.onLink) {
+      this.config.onLink(match);
+      return;
+    }
+
+    const layout = this.config.getModal
+      ? this.config.getModal(match)
+      : this.modalLayoutBuilder.build(match);
+
+    if (layout) {
+      this.showModal(layout);
+    }
+  }
+
+  private isReady(): boolean {
+    if (!this.rootReady) return false;
+    if (this.userReadyOverride !== null) return this.userReadyOverride;
+    if (this.config?.isReady) return this.config.isReady();
+    return true;
+  }
+
+  private refreshReady(): void {
+    this.deferredQueue.setReady(this.isReady());
+  }
+}
diff --git a/src/linking/ModalLayoutBuilder.test.ts b/src/linking/ModalLayoutBuilder.test.ts
new file mode 100644
index 00000000000..405c94ba5c5
--- /dev/null
+++ b/src/linking/ModalLayoutBuilder.test.ts
@@ -0,0 +1,105 @@
+import { ModalLayoutBuilder } from './ModalLayoutBuilder';
+
+describe('ModalLayoutBuilder', () => {
+  let uut: ModalLayoutBuilder;
+
+  beforeEach(() => {
+    uut = new ModalLayoutBuilder();
+  });
+
+  it('wraps a single-segment match in a stack', () => {
+    const layout = uut.build({
+      url: 'myapp://home',
+      path: [{ screen: 'Home', params: {} }],
+      queryParams: {},
+    });
+    expect(layout).toEqual({
+      stack: {
+        children: [
+          {
+            component: { name: 'Home', passProps: {} },
+          },
+        ],
+      },
+    });
+  });
+
+  it('builds a push chain for multi-segment matches', () => {
+    const layout = uut.build({
+      url: 'myapp://settings/notifications',
+      path: [
+        { screen: 'Settings', params: {} },
+        { screen: 'Notifications', params: {} },
+      ],
+      queryParams: {},
+    });
+    expect(layout.stack?.children).toEqual([
+      { component: { name: 'Settings', passProps: {} } },
+      { component: { name: 'Notifications', passProps: {} } },
+    ]);
+  });
+
+  it('passes path params as passProps', () => {
+    const layout = uut.build({
+      url: 'myapp://user/42',
+      path: [{ screen: 'Profile', params: { id: '42' } }],
+      queryParams: {},
+    });
+    expect(layout.stack?.children?.[0].component?.passProps).toEqual({ id: '42' });
+  });
+
+  it('merges query params into every segment, with path params taking precedence', () => {
+    const layout = uut.build({
+      url: 'myapp://user/42?id=99&source=push',
+      path: [{ screen: 'Profile', params: { id: '42' } }],
+      queryParams: { id: '99', source: 'push' },
+    });
+    expect(layout.stack?.children?.[0].component?.passProps).toEqual({
+      id: '42',
+      source: 'push',
+    });
+  });
+
+  it('applies query params to every segment of a nested match', () => {
+    const layout = uut.build({
+      url: 'myapp://settings/notifications?source=push',
+      path: [
+        { screen: 'Settings', params: {} },
+        { screen: 'Notifications', params: {} },
+      ],
+      queryParams: { source: 'push' },
+    });
+    expect(layout.stack?.children?.[0].component?.passProps).toEqual({ source: 'push' });
+    expect(layout.stack?.children?.[1].component?.passProps).toEqual({ source: 'push' });
+  });
+
+  it('filters the React-reserved "ref" query param from passProps', () => {
+    const layout = uut.build({
+      url: 'myapp://user/42?ref=notification&utm=push',
+      path: [{ screen: 'Profile', params: { id: '42' } }],
+      queryParams: { ref: 'notification', utm: 'push' },
+    });
+    expect(layout.stack?.children?.[0].component?.passProps).toEqual({
+      id: '42',
+      utm: 'push',
+    });
+  });
+
+  it('filters the React-reserved "key" query param from passProps', () => {
+    const layout = uut.build({
+      url: 'myapp://home?key=abc',
+      path: [{ screen: 'Home', params: {} }],
+      queryParams: { key: 'abc' },
+    });
+    expect(layout.stack?.children?.[0].component?.passProps).toEqual({});
+  });
+
+  it('filters reserved keys when they appear as path params too', () => {
+    const layout = uut.build({
+      url: 'myapp://r/abc',
+      path: [{ screen: 'Home', params: { ref: 'abc' } }],
+      queryParams: {},
+    });
+    expect(layout.stack?.children?.[0].component?.passProps).toEqual({});
+  });
+});
diff --git a/src/linking/ModalLayoutBuilder.ts b/src/linking/ModalLayoutBuilder.ts
new file mode 100644
index 00000000000..24d61f208aa
--- /dev/null
+++ b/src/linking/ModalLayoutBuilder.ts
@@ -0,0 +1,60 @@
+import { Layout } from '../interfaces/Layout';
+import { RouteMatch, RouteMatchSegment } from './types';
+
+/**
+ * Props that React treats specially and must never be forwarded as
+ * regular component props. If a URL contains query parameters or path
+ * parameters using these names, they are dropped from `passProps`
+ * (with a dev-mode warning) to avoid crashing the screen.
+ */
+const RESERVED_PROP_NAMES = new Set(['ref', 'key']);
+
+/**
+ * Builds the default modal layout for a matched deep link.
+ *
+ * Behavior:
+ *   - Wraps the matched chain in a `stack`. Even a single-component match
+ *     gets wrapped so the screen has a topBar where the user can mount a
+ *     close button via `topBar.leftButtons`.
+ *   - Each segment becomes a `component` child of the stack, in match order.
+ *     The first segment is the root of the stack; subsequent segments are
+ *     pushed on top.
+ *   - Path params for each segment are merged with query params and passed
+ *     as `passProps` to that segment's component. Path params win on key
+ *     collision. React-reserved keys (`ref`, `key`) are filtered out.
+ */
+export class ModalLayoutBuilder {
+  public build(match: RouteMatch): Layout {
+    return {
+      stack: {
+        children: match.path.map((segment) => ({
+          component: {
+            name: segment.screen,
+            passProps: this.mergeProps(segment, match.queryParams),
+          },
+        })),
+      },
+    };
+  }
+
+  private mergeProps(
+    segment: RouteMatchSegment,
+    queryParams: Record<string, string>
+  ): Record<string, string> {
+    const merged: Record<string, string> = { ...queryParams, ...segment.params };
+    const safe: Record<string, string> = {};
+    for (const key of Object.keys(merged)) {
+      if (RESERVED_PROP_NAMES.has(key)) {
+        if (__DEV__) {
+          console.warn(
+            `[RNN linking] Dropping reserved prop "${key}" from passProps for screen "${segment.screen}". ` +
+              `Rename the URL parameter to avoid conflicting with React-reserved names.`
+          );
+        }
+        continue;
+      }
+      safe[key] = merged[key];
+    }
+    return safe;
+  }
+}
diff --git a/src/linking/RouteMatcher.test.ts b/src/linking/RouteMatcher.test.ts
new file mode 100644
index 00000000000..5796a950c00
--- /dev/null
+++ b/src/linking/RouteMatcher.test.ts
@@ -0,0 +1,128 @@
+import { RouteMatcher } from './RouteMatcher';
+import { ScreensConfig } from './types';
+
+describe('RouteMatcher', () => {
+  let uut: RouteMatcher;
+
+  beforeEach(() => {
+    uut = new RouteMatcher();
+  });
+
+  function configure(screens: ScreensConfig) {
+    uut.setRouteTree(uut.buildRouteTree(screens));
+  }
+
+  it('matches a flat route', () => {
+    configure({ Home: 'home' });
+    expect(uut.match('home', 'myapp://home', {})).toEqual({
+      url: 'myapp://home',
+      path: [{ screen: 'Home', params: {} }],
+      queryParams: {},
+    });
+  });
+
+  it('extracts a single path parameter', () => {
+    configure({ Profile: 'user/:id' });
+    expect(uut.match('user/42', 'myapp://user/42', {})).toEqual({
+      url: 'myapp://user/42',
+      path: [{ screen: 'Profile', params: { id: '42' } }],
+      queryParams: {},
+    });
+  });
+
+  it('extracts multiple path parameters', () => {
+    configure({ Post: 'user/:userId/post/:postId' });
+    const result = uut.match('user/5/post/99', 'myapp://user/5/post/99', {});
+    expect(result?.path[0].params).toEqual({ userId: '5', postId: '99' });
+  });
+
+  it('returns null when no route matches', () => {
+    configure({ Home: 'home' });
+    expect(uut.match('unknown', 'myapp://unknown', {})).toBeNull();
+  });
+
+  it('returns null when path is longer than any pattern', () => {
+    configure({ Home: 'home' });
+    expect(uut.match('home/extra', 'myapp://home/extra', {})).toBeNull();
+  });
+
+  it('matches the first registered route on ambiguity', () => {
+    configure({
+      Profile: 'user/:id',
+      User: 'user/:userId',
+    });
+    const result = uut.match('user/42', 'myapp://user/42', {});
+    expect(result?.path[0].screen).toBe('Profile');
+  });
+
+  it('matches a nested route as a chain', () => {
+    configure({
+      Settings: {
+        path: 'settings',
+        screens: { Notifications: 'notifications' },
+      },
+    });
+    expect(uut.match('settings/notifications', 'myapp://settings/notifications', {})).toEqual({
+      url: 'myapp://settings/notifications',
+      path: [
+        { screen: 'Settings', params: {} },
+        { screen: 'Notifications', params: {} },
+      ],
+      queryParams: {},
+    });
+  });
+
+  it('matches a parent-only nested route', () => {
+    configure({
+      Settings: {
+        path: 'settings',
+        screens: { Notifications: 'notifications' },
+      },
+    });
+    expect(uut.match('settings', 'myapp://settings', {})).toEqual({
+      url: 'myapp://settings',
+      path: [{ screen: 'Settings', params: {} }],
+      queryParams: {},
+    });
+  });
+
+  it('supports grouping nodes that consume no segments', () => {
+    configure({
+      Main: {
+        screens: {
+          Feed: 'feed',
+          Search: 'search',
+        },
+      },
+    });
+    const result = uut.match('feed', 'myapp://feed', {});
+    expect(result?.path).toEqual([
+      { screen: 'Main', params: {} },
+      { screen: 'Feed', params: {} },
+    ]);
+  });
+
+  it('passes query params through to the match result', () => {
+    configure({ Home: 'home' });
+    const result = uut.match('home', 'myapp://home?ref=push', { ref: 'push' });
+    expect(result?.queryParams).toEqual({ ref: 'push' });
+  });
+
+  it('returns null when no route tree has been configured', () => {
+    expect(uut.match('home', 'myapp://home', {})).toBeNull();
+  });
+
+  it('matches nested params at multiple levels', () => {
+    configure({
+      Org: {
+        path: 'org/:orgId',
+        screens: { Project: 'project/:projectId' },
+      },
+    });
+    const result = uut.match('org/1/project/2', 'myapp://org/1/project/2', {});
+    expect(result?.path).toEqual([
+      { screen: 'Org', params: { orgId: '1' } },
+      { screen: 'Project', params: { projectId: '2' } },
+    ]);
+  });
+});
diff --git a/src/linking/RouteMatcher.ts b/src/linking/RouteMatcher.ts
new file mode 100644
index 00000000000..a9851f4f9a7
--- /dev/null
+++ b/src/linking/RouteMatcher.ts
@@ -0,0 +1,126 @@
+import {
+  ScreensConfig,
+  ScreenConfig,
+  RouteNode,
+  RouteMatch,
+  RouteMatchSegment,
+} from './types';
+
+/**
+ * Compiles a `screens` config into a tree of `RouteNode`s and resolves
+ * parsed paths to a matched `RouteMatch`.
+ *
+ * Matching is depth-first, in insertion order. The first node whose pattern
+ * (and nested children) consume the entire path wins.
+ */
+export class RouteMatcher {
+  private routeTree: RouteNode[] | null = null;
+
+  public buildRouteTree(screens: ScreensConfig): RouteNode[] {
+    const nodes: RouteNode[] = [];
+    for (const [screenName, config] of Object.entries(screens)) {
+      nodes.push(this.buildNode(screenName, config));
+    }
+    return nodes;
+  }
+
+  public setRouteTree(tree: RouteNode[]): void {
+    this.routeTree = tree;
+  }
+
+  /**
+   * Match a parsed path (e.g. `"user/42"`) against the configured tree.
+   * Returns the matched chain or `null` when no route matches.
+   */
+  public match(
+    path: string,
+    url: string,
+    queryParams: Record<string, string>
+  ): RouteMatch | null {
+    if (!this.routeTree) return null;
+
+    const pathSegments = path.split('/').filter((s) => s.length > 0);
+    const result = this.matchRecursive(pathSegments, 0, this.routeTree);
+    if (!result) return null;
+
+    return { url, path: result, queryParams };
+  }
+
+  private buildNode(screenName: string, config: ScreenConfig): RouteNode {
+    if (typeof config === 'string') {
+      return {
+        screen: screenName,
+        pattern: config,
+        segments: this.splitPattern(config),
+        children: [],
+      };
+    }
+
+    const children = config.screens ? this.buildRouteTree(config.screens) : [];
+    return {
+      screen: screenName,
+      pattern: config.path ?? null,
+      segments: config.path ? this.splitPattern(config.path) : [],
+      children,
+    };
+  }
+
+  private splitPattern(pattern: string): string[] {
+    return pattern.split('/').filter((s) => s.length > 0);
+  }
+
+  private matchRecursive(
+    pathSegments: string[],
+    offset: number,
+    nodes: RouteNode[]
+  ): RouteMatchSegment[] | null {
+    for (const node of nodes) {
+      const result = this.tryMatchNode(pathSegments, offset, node);
+      if (result) return result;
+    }
+    return null;
+  }
+
+  private tryMatchNode(
+    pathSegments: string[],
+    offset: number,
+    node: RouteNode
+  ): RouteMatchSegment[] | null {
+    if (node.pattern === null && node.segments.length === 0) {
+      if (node.children.length === 0) return null;
+      const childMatch = this.matchRecursive(pathSegments, offset, node.children);
+      if (!childMatch) return null;
+      return [{ screen: node.screen, params: {} }, ...childMatch];
+    }
+
+    const patternSegments = node.segments;
+    if (offset + patternSegments.length > pathSegments.length) {
+      return null;
+    }
+
+    const params: Record<string, string> = {};
+    for (let i = 0; i < patternSegments.length; i++) {
+      const pattern = patternSegments[i];
+      const actual = pathSegments[offset + i];
+      if (pattern.startsWith(':')) {
+        params[pattern.slice(1)] = actual;
+      } else if (pattern !== actual) {
+        return null;
+      }
+    }
+
+    const newOffset = offset + patternSegments.length;
+    const segment: RouteMatchSegment = { screen: node.screen, params };
+
+    if (newOffset === pathSegments.length) {
+      return [segment];
+    }
+
+    if (node.children.length > 0) {
+      const childMatch = this.matchRecursive(pathSegments, newOffset, node.children);
+      if (childMatch) return [segment, ...childMatch];
+    }
+
+    return null;
+  }
+}
diff --git a/src/linking/URLParser.test.ts b/src/linking/URLParser.test.ts
new file mode 100644
index 00000000000..c2bea3b4e9a
--- /dev/null
+++ b/src/linking/URLParser.test.ts
@@ -0,0 +1,105 @@
+import { URLParser } from './URLParser';
+
+describe('URLParser', () => {
+  let uut: URLParser;
+
+  beforeEach(() => {
+    uut = new URLParser();
+  });
+
+  describe('stripPrefix', () => {
+    it('returns the remainder after the matching prefix', () => {
+      expect(uut.stripPrefix('myapp://home', ['myapp://'])).toBe('home');
+    });
+
+    it('returns null when no prefix matches', () => {
+      expect(uut.stripPrefix('other://home', ['myapp://'])).toBeNull();
+    });
+
+    it('chooses the longest matching prefix', () => {
+      const result = uut.stripPrefix('https://myapp.com/v2/home', [
+        'https://myapp.com',
+        'https://myapp.com/v2',
+      ]);
+      expect(result).toBe('/home');
+    });
+  });
+
+  describe('parse', () => {
+    const prefixes = ['myapp://', 'https://myapp.com'];
+
+    it('returns null when no prefix matches', () => {
+      expect(uut.parse('other://home', prefixes)).toBeNull();
+    });
+
+    it('parses a simple path', () => {
+      expect(uut.parse('myapp://home', prefixes)).toEqual({
+        path: 'home',
+        queryParams: {},
+      });
+    });
+
+    it('trims leading and trailing slashes', () => {
+      expect(uut.parse('myapp:///home/', prefixes)).toEqual({
+        path: 'home',
+        queryParams: {},
+      });
+    });
+
+    it('parses query parameters', () => {
+      expect(uut.parse('myapp://search?q=hello&page=2', prefixes)).toEqual({
+        path: 'search',
+        queryParams: { q: 'hello', page: '2' },
+      });
+    });
+
+    it('decodes URL-encoded path segments', () => {
+      expect(uut.parse('myapp://hello%20world', prefixes)).toEqual({
+        path: 'hello world',
+        queryParams: {},
+      });
+    });
+
+    it('decodes URL-encoded query parameter keys and values', () => {
+      expect(uut.parse('myapp://search?q=hello%20world&a%20b=c', prefixes)).toEqual({
+        path: 'search',
+        queryParams: { q: 'hello world', 'a b': 'c' },
+      });
+    });
+
+    it('strips fragments before parsing the query', () => {
+      expect(uut.parse('myapp://home?x=1#section', prefixes)).toEqual({
+        path: 'home',
+        queryParams: { x: '1' },
+      });
+    });
+
+    it('strips fragments when there is no query string', () => {
+      expect(uut.parse('myapp://home#section', prefixes)).toEqual({
+        path: 'home',
+        queryParams: {},
+      });
+    });
+
+    it('treats query keys without values as empty strings', () => {
+      expect(uut.parse('myapp://home?flag', prefixes)).toEqual({
+        path: 'home',
+        queryParams: { flag: '' },
+      });
+    });
+
+    it('handles malformed encoding without throwing', () => {
+      expect(uut.parse('myapp://%E0%A4%A', prefixes)).toEqual({
+        path: '%E0%A4%A',
+        queryParams: {},
+      });
+    });
+
+    it('keeps "=" inside values intact', () => {
+      expect(uut.parse('myapp://search?token=a=b=c', prefixes)).toEqual({
+        path: 'search',
+        queryParams: { token: 'a=b=c' },
+      });
+    });
+  });
+});
diff --git a/src/linking/URLParser.ts b/src/linking/URLParser.ts
new file mode 100644
index 00000000000..9fac14589e1
--- /dev/null
+++ b/src/linking/URLParser.ts
@@ -0,0 +1,62 @@
+import { ParsedURL } from './types';
+
+/**
+ * Parses a URL string against a list of configured prefixes.
+ *
+ * Responsibilities:
+ *   - Strip the longest matching prefix (or report no match).
+ *   - Drop any `#fragment` portion.
+ *   - Decode each path segment so literal patterns compare against decoded
+ *     text (e.g. `hello%20world` matches a `hello world` pattern segment).
+ *   - Parse the query string into a plain key/value map.
+ */
+export class URLParser {
+  public stripPrefix(url: string, prefixes: string[]): string | null {
+    const sorted = [...prefixes].sort((a, b) => b.length - a.length);
+    for (const prefix of sorted) {
+      if (url.startsWith(prefix)) {
+        return url.slice(prefix.length);
+      }
+    }
+    return null;
+  }
+
+  public parse(url: string, prefixes: string[]): ParsedURL | null {
+    const stripped = this.stripPrefix(url, prefixes);
+    if (stripped === null) {
+      return null;
+    }
+
+    const withoutFragment = stripped.split('#', 1)[0];
+    const [pathPart, queryPart] = withoutFragment.split('?', 2);
+
+    const path = pathPart
+      .split('/')
+      .filter((s) => s.length > 0)
+      .map((segment) => safeDecode(segment))
+      .join('/');
+
+    const queryParams: Record<string, string> = {};
+    if (queryPart) {
+      for (const pair of queryPart.split('&')) {
+        if (!pair) continue;
+        const eqIndex = pair.indexOf('=');
+        const rawKey = eqIndex === -1 ? pair : pair.slice(0, eqIndex);
+        const rawValue = eqIndex === -1 ? '' : pair.slice(eqIndex + 1);
+        const key = safeDecode(rawKey);
+        if (!key) continue;
+        queryParams[key] = safeDecode(rawValue);
+      }
+    }
+
+    return { path, queryParams };
+  }
+}
+
+function safeDecode(value: string): string {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
diff --git a/src/linking/types.ts b/src/linking/types.ts
new file mode 100644
index 00000000000..c74c04a4bd3
--- /dev/null
+++ b/src/linking/types.ts
@@ -0,0 +1,115 @@
+import { Layout } from '../interfaces/Layout';
+
+/**
+ * A single matched segment of a deep link route.
+ */
+export interface RouteMatchSegment {
+  /** Name of the registered RNN component this segment maps to. */
+  screen: string;
+  /** Path parameters extracted from this segment's pattern (e.g. `:id`). */
+  params: Record<string, string>;
+}
+
+/**
+ * Result of matching a URL against the configured `screens` tree.
+ */
+export interface RouteMatch {
+  /** Original URL that was matched. */
+  url: string;
+  /**
+   * Ordered chain of matched screens, from outermost to innermost.
+   * For a nested route like `settings/notifications`, this contains
+   * `[{ screen: 'Settings' }, { screen: 'Notifications' }]`.
+   */
+  path: RouteMatchSegment[];
+  /** Query string parameters from the URL. */
+  queryParams: Record<string, string>;
+}
+
+/**
+ * Internal representation of a parsed URL after prefix stripping.
+ */
+export interface ParsedURL {
+  /** Decoded path with leading/trailing slashes removed. */
+  path: string;
+  /** Query string parameters. */
+  queryParams: Record<string, string>;
+}
+
+/**
+ * Internal compiled representation of a single screen entry in the route tree.
+ */
+export interface RouteNode {
+  /** Screen name (the key from `screens`). */
+  screen: string;
+  /** Path pattern as written by the user, or `null` for grouping nodes. */
+  pattern: string | null;
+  /** Pattern split into segments, ready for matching. */
+  segments: string[];
+  /** Nested children. */
+  children: RouteNode[];
+}
+
+/**
+ * Per-screen configuration. Either a path pattern string, or an object with
+ * an optional path and nested screens.
+ *
+ * Examples:
+ *   `'home'`                                   - leaf route
+ *   `'user/:id'`                               - leaf with path parameter
+ *   `{ path: 'settings', screens: {...} }`     - nested route
+ *   `{ screens: {...} }`                       - grouping node (no path)
+ */
+export type ScreenConfig =
+  | string
+  | {
+      path?: string;
+      screens?: ScreensConfig;
+    };
+
+export interface ScreensConfig {
+  [screenName: string]: ScreenConfig;
+}
+
+/**
+ * Configuration passed to `Navigation.setLinking`.
+ *
+ * When a deep link is received, RNN parses it, matches it against the
+ * `screens` tree, and by default presents the matched chain as a modal
+ * (wrapped in a stack so a topBar is available for a close button).
+ *
+ * To customize the modal layout, provide `getModal`. To bypass the modal
+ * behavior entirely (e.g. push onto an existing stack), provide `onLink`.
+ */
+export interface LinkingConfig {
+  /** URL prefixes your app handles (custom schemes and universal-link hosts). */
+  prefixes: string[];
+  /** Screen-to-path mapping. */
+  config: {
+    screens: ScreensConfig;
+  };
+  /**
+   * Customize the modal layout for a matched route. Return `undefined` to
+   * skip presenting a modal for this match (useful for conditional skipping).
+   * When omitted, the default builder wraps the matched chain in a stack.
+   */
+  getModal?: (match: RouteMatch) => Layout | undefined;
+  /**
+   * Full escape hatch. When provided, RNN does not present a modal; the
+   * handler is responsible for executing whatever navigation commands it
+   * wants (push, setRoot, dismissAllModals + showModal, etc.).
+   * When set, `getModal` is ignored.
+   */
+  onLink?: (match: RouteMatch) => void;
+  /**
+   * Called when a received URL does not match any configured route or has
+   * no matching prefix. Useful for logging or routing to a "not found" flow.
+   */
+  fallback?: (url: string) => void;
+  /**
+   * Predicate evaluated before each link is processed. When it returns
+   * `false`, the link is queued and replayed once `setLinkingReady(true)`
+   * is called. Use this to defer links until e.g. authentication completes.
+   */
+  isReady?: () => boolean;
+}
diff --git a/website/docs/docs/docs-deep-linking.mdx b/website/docs/docs/docs-deep-linking.mdx
new file mode 100644
index 00000000000..e5111eab2c0
--- /dev/null
+++ b/website/docs/docs/docs-deep-linking.mdx
@@ -0,0 +1,358 @@
+---
+id: deep-linking
+title: Deep Linking
+sidebar_label: Deep Linking
+---
+
+Deep linking opens a specific screen in your app from a URL — whether from a custom scheme (`myapp://user/42`) or a universal link (`https://myapp.com/user/42`). React Native Navigation maps URLs to screens and **presents the matched content as a modal** on top of whatever the user is currently doing, so their navigation state is preserved when they dismiss the modal.
+
+## Setting up linking
+
+Call `Navigation.setLinking()` once during app startup, alongside your `Navigation.registerComponent` calls:
+
+```js
+import { Navigation } from 'react-native-navigation';
+
+Navigation.setLinking({
+  prefixes: ['myapp://', 'https://myapp.com'],
+  config: {
+    screens: {
+      Home: 'home',
+      Profile: 'user/:id',
+      Settings: {
+        path: 'settings',
+        screens: {
+          Notifications: 'notifications',
+        },
+      },
+    },
+  },
+});
+```
+
+When a deep link arrives:
+
+1. RNN parses the URL, strips the longest matching prefix, and matches the path against the `screens` tree.
+2. The matched chain is wrapped in a `stack` and presented via `showModal`. The user can dismiss the modal to return to their previous flow.
+3. If no route matches, the optional `fallback` callback is invoked.
+
+Path parameters (`:id`) and query parameters are extracted and passed as `passProps` to each component in the modal.
+
+## Configuration
+
+### `prefixes`
+
+Array of URL prefixes your app handles. Custom schemes and universal-link hosts are both supported. The longest matching prefix wins.
+
+```js
+prefixes: ['myapp://', 'https://myapp.com', 'https://myapp.com/v2'],
+```
+
+### `config.screens`
+
+Map of screen names (must match the names you registered with `Navigation.registerComponent`) to URL path patterns.
+
+**String value** — a leaf route:
+
+```js
+screens: {
+  Home: 'home',          // matches myapp://home
+  Profile: 'user/:id',   // matches myapp://user/42, extracts { id: '42' }
+}
+```
+
+**Object value** — a route with nested children:
+
+```js
+screens: {
+  Settings: {
+    path: 'settings',
+    screens: {
+      Notifications: 'notifications',
+      Account: 'account/:section',
+    },
+  },
+}
+// myapp://settings/notifications      → stack: [Settings, Notifications]
+// myapp://settings/account/billing    → stack: [Settings, Account] with { section: 'billing' }
+```
+
+**Object value with no `path`** — a grouping node that contributes a screen to the chain but consumes no URL segments:
+
+```js
+screens: {
+  Main: {
+    screens: {
+      Feed: 'feed',     // matches myapp://feed → stack: [Main, Feed]
+      Search: 'search',
+    },
+  },
+}
+```
+
+### Path parameters
+
+Use `:paramName` in a pattern segment to capture it. Path params are merged with query params and handed to that segment's component as `passProps`. Path params win on key collision.
+
+```js
+screens: { Post: 'user/:userId/post/:postId' }
+
+// myapp://user/5/post/99
+// → Post screen receives passProps: { userId: '5', postId: '99' }
+```
+
+### Query parameters
+
+Query string values are parsed automatically and merged into every segment's `passProps`:
+
+```
+myapp://search?q=hello&page=2
+→ Search screen receives passProps: { q: 'hello', page: '2' }
+```
+
+## Customizing presentation
+
+By default, every matched link becomes a modal containing a stack with the matched chain pushed in order. If you need to customize either the layout or the navigation command itself, the config exposes two hooks.
+
+### `getModal` — customize the modal layout
+
+Provide a function that returns the `Layout` to present. Useful for adding default options, wrapping in a different layout, or skipping certain matches conditionally.
+
+```js
+Navigation.setLinking({
+  // ...
+  getModal: (match) => ({
+    stack: {
+      children: match.path.map((segment) => ({
+        component: {
+          name: segment.screen,
+          passProps: { ...match.queryParams, ...segment.params },
+          options: {
+            topBar: {
+              leftButtons: [{ id: 'close', text: 'Close' }],
+            },
+          },
+        },
+      })),
+    },
+  }),
+});
+```
+
+Return `undefined` from `getModal` to skip presenting a modal for a particular match (e.g. ignore certain paths).
+
+### `onLink` — full escape hatch
+
+For complete control — pushing onto an existing stack instead of showing a modal, dismissing existing modals first, or composing multiple commands — provide `onLink`. When supplied, RNN does not present anything itself; you call navigation commands yourself.
+
+```js
+Navigation.setLinking({
+  // ...
+  onLink: (match) => {
+    const leaf = match.path[match.path.length - 1];
+
+    if (leaf.screen === 'Profile') {
+      Navigation.push('mainStack', {
+        component: {
+          name: 'Profile',
+          passProps: { id: leaf.params.id },
+        },
+      });
+      return;
+    }
+
+    Navigation.showModal({
+      stack: {
+        children: match.path.map((segment) => ({
+          component: { name: segment.screen, passProps: segment.params },
+        })),
+      },
+    });
+  },
+});
+```
+
+When `onLink` is set, `getModal` is ignored.
+
+## Match payload
+
+Both `getModal` and `onLink` receive the same `RouteMatch` object:
+
+```ts
+interface RouteMatch {
+  url: string;
+  path: RouteMatchSegment[];
+  queryParams: Record<string, string>;
+}
+
+interface RouteMatchSegment {
+  screen: string;
+  params: Record<string, string>;
+}
+```
+
+## Fallback for unmatched URLs
+
+If a received URL has no matching prefix or doesn't match any configured route, the optional `fallback` callback is invoked. Use it for logging, analytics, or routing to a "not found" screen.
+
+```js
+Navigation.setLinking({
+  // ...
+  fallback: (url) => {
+    console.warn(`Unhandled deep link: ${url}`);
+  },
+});
+```
+
+## Deferred deep links
+
+Two readiness gates control when links are processed; both must be open before a link is dispatched.
+
+### Automatic root gate
+
+RNN automatically defers link processing until your first `Navigation.setRoot()` resolves. This handles the common case where the OS delivers an initial URL before your app has a root window — the link is queued and replayed once `setRoot` mounts the root.
+
+You don't need to opt into this behavior; it always applies.
+
+### Optional `isReady` gate
+
+For application-level gates such as authentication, supply an `isReady` predicate. The predicate is consulted on every incoming link; when it returns `false`, the link is queued. Once the gate opens, call `setLinkingReady(true)` to flush queued links in order.
+
+```js
+let isAuthenticated = false;
+
+Navigation.setLinking({
+  prefixes: ['myapp://'],
+  config: { screens: { Profile: 'user/:id' } },
+  isReady: () => isAuthenticated,
+});
+
+async function onLoginSuccess() {
+  isAuthenticated = true;
+  Navigation.setLinkingReady(true);
+}
+```
+
+`setLinkingReady(true)` overrides `isReady` once called, so you can also drive the gate purely with explicit calls if you prefer.
+
+## Manual handling
+
+Some links don't arrive via the system URL handler — push-notification payloads, branch.io tokens, App Clips. Feed them into the same pipeline with `Navigation.handleDeepLink(url)`:
+
+```js
+Navigation.handleDeepLink('myapp://user/42?ref=notification');
+```
+
+This runs the URL through parse → match → present exactly like a system-delivered link, including readiness gates.
+
+## Complete example
+
+```js
+import { Navigation } from 'react-native-navigation';
+
+Navigation.registerComponent('Home', () => require('./screens/Home').default);
+Navigation.registerComponent('Profile', () => require('./screens/Profile').default);
+Navigation.registerComponent('Settings', () => require('./screens/Settings').default);
+Navigation.registerComponent('Notifications', () => require('./screens/Notifications').default);
+
+let isLoggedIn = false;
+
+Navigation.setLinking({
+  prefixes: ['myapp://', 'https://myapp.com'],
+  config: {
+    screens: {
+      Home: 'home',
+      Profile: 'user/:id',
+      Settings: {
+        path: 'settings',
+        screens: { Notifications: 'notifications' },
+      },
+    },
+  },
+  isReady: () => isLoggedIn,
+  fallback: (url) => console.warn(`Unhandled: ${url}`),
+});
+
+Navigation.events().registerAppLaunchedListener(() => {
+  Navigation.setRoot({
+    root: { stack: { children: [{ component: { name: 'Home' } }] } },
+  });
+});
+
+export function onLoginComplete() {
+  isLoggedIn = true;
+  Navigation.setLinkingReady(true);
+}
+```
+
+With this configuration:
+
+- `myapp://home` opens the Home screen as a modal on top of the current screen.
+- `myapp://user/42` opens Profile as a modal with `{ id: '42' }` as props.
+- `myapp://settings/notifications` opens a modal containing a stack with `Settings` → `Notifications` pushed in order.
+- Links arriving before `setRoot` resolves are queued automatically and replayed.
+- Links arriving before login are queued and replayed when `onLoginComplete()` runs.
+
+## Native setup
+
+The framework consumes URLs from React Native's `Linking` API. You still configure the URL schemes and universal links at the platform level.
+
+### iOS
+
+Add your URL scheme to `Info.plist`:
+
+```xml
+<key>CFBundleURLTypes</key>
+<array>
+  <dict>
+    <key>CFBundleURLSchemes</key>
+    <array>
+      <string>myapp</string>
+    </array>
+  </dict>
+</array>
+```
+
+For universal links, add the Associated Domains entitlement and host an `apple-app-site-association` file. See [Apple's documentation](https://developer.apple.com/documentation/xcode/supporting-associated-domains).
+
+### Android
+
+Add an intent filter to your `MainActivity` in `AndroidManifest.xml`:
+
+```xml
+<activity
+  android:name=".MainActivity"
+  android:launchMode="singleTask">
+  <intent-filter>
+    <action android:name="android.intent.action.VIEW" />
+    <category android:name="android.intent.category.DEFAULT" />
+    <category android:name="android.intent.category.BROWSABLE" />
+    <data android:scheme="myapp" />
+  </intent-filter>
+</activity>
+```
+
+For App Links, add `android:autoVerify="true"` and host an `assetlinks.json`. See [Android's documentation](https://developer.android.com/training/app-links).
+
+## API reference
+
+### `Navigation.setLinking(config)`
+
+Configure deep link handling. Subsequent calls reconfigure cleanly (the previous subscription is torn down).
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `prefixes` | `string[]` | Yes | URL prefixes to match. Longest wins. |
+| `config.screens` | `ScreensConfig` | Yes | Screen-to-path mapping. |
+| `getModal` | `(match) => Layout \| undefined` | No | Build a custom modal layout for the match. |
+| `onLink` | `(match) => void` | No | Full escape hatch. Overrides default and `getModal`. |
+| `fallback` | `(url) => void` | No | Called when a URL doesn't match any prefix or route. |
+| `isReady` | `() => boolean` | No | Predicate gating link processing. |
+
+### `Navigation.handleDeepLink(url)`
+
+Feed a URL into the pipeline as if it had been delivered by the OS.
+
+### `Navigation.setLinkingReady(ready)`
+
+Set the user-controlled readiness gate. Passing `true` flushes queued links; passing `false` blocks future links until called again with `true`.
diff --git a/website/sidebars.js b/website/sidebars.js
index f6be96d697f..13b0a612896 100755
--- a/website/sidebars.js
+++ b/website/sidebars.js
@@ -14,6 +14,7 @@ module.exports = {
       'docs/passing-data-to-components',
       'docs/functionalComponents',
       'docs/customBackNavigation',
+      'docs/deep-linking',
     ],
     Layouts: ['docs/stack', 'docs/bottomTabs', 'docs/sideMenu', 'docs/externalComponent'],
     Hierarchy: ['docs/root', 'docs/modal', 'docs/overlay'],

From e5c6976d7877b6553a6519b323b11cbf6adbecac Mon Sep 17 00:00:00 2001
From: Mark de Vocht <markd@wix.com>
Date: Wed, 13 May 2026 11:54:23 +0300
Subject: [PATCH 2/3] update

---
 ios/RNNAppDelegate.h                     | 16 +++++
 ios/RNNAppDelegate.mm                    | 73 ++++++++++++++++++++
 playground/ios/playground/AppDelegate.mm | 85 +++---------------------
 3 files changed, 97 insertions(+), 77 deletions(-)

diff --git a/ios/RNNAppDelegate.h b/ios/RNNAppDelegate.h
index d67d7ce1b15..d951ed09de6 100644
--- a/ios/RNNAppDelegate.h
+++ b/ios/RNNAppDelegate.h
@@ -56,4 +56,20 @@
 @property(nonatomic) BOOL bridgelessEnabled;
 #endif
 
+/**
+ * Dispatch a deep link URL through React Native's Linking module so JS
+ * subscribers (including RNN's built-in deep linking framework) receive it.
+ *
+ * Safe to call before the JS bridge is ready: URLs that arrive early
+ * (e.g. cold-start notification taps) are queued natively and flushed
+ * automatically once Fabric/React content first appears.
+ *
+ * Custom-scheme and universal-link openings dispatched by the OS are
+ * forwarded through this method automatically; call it manually only
+ * when your app receives a deep link from a source RNN can't intercept
+ * (e.g. a custom `UNUserNotificationCenterDelegate`, a third-party push
+ * SDK callback, etc.).
+ */
+- (void)dispatchDeepLinkURL:(NSURL *)url;
+
 @end
diff --git a/ios/RNNAppDelegate.mm b/ios/RNNAppDelegate.mm
index 5e33fa9e4c2..da6914a738a 100644
--- a/ios/RNNAppDelegate.mm
+++ b/ios/RNNAppDelegate.mm
@@ -8,6 +8,8 @@
 #import <React/RCTCxxBridgeDelegate.h>
 #endif
 #import <React/RCTLegacyViewManagerInteropComponentView.h>
+#import <React/RCTLinkingManager.h>
+#import <React/RCTRootView.h>
 #import <React/RCTSurfacePresenter.h>
 #if __has_include(<React/RCTSurfacePresenterStub.h>)
 #import <React/RCTSurfacePresenterStub.h>
@@ -36,6 +38,13 @@
 
 #import <React/RCTComponentViewFactory.h>
 
+// Deep-link URLs that arrive (openURL, universal link, or external dispatch)
+// before the React runtime is ready are queued here and flushed when Fabric
+// posts `RCTContentDidAppearNotification` — by which point
+// `RCTLinkingManager` is instantiated and JS subscribers are listening.
+static NSMutableArray<NSURL *> *gRNNPendingDeepLinkURLs = nil;
+static BOOL gRNNReactRuntimeReady = NO;
+
 
 static NSString *const kRNConcurrentRoot = @"concurrentRoot";
 
@@ -92,9 +101,73 @@ - (BOOL)application:(UIApplication *)application
     [ReactNativeNavigation bootstrapWithHost:self.reactNativeFactory.rootViewFactory.reactHost];
 #endif
     
+    [self rnn_installDeepLinkObservers];
+    
     return YES;
 }
 
+#pragma mark - Deep linking
+
+// Forward OS-delivered custom-scheme URLs to React Native's Linking module.
+- (BOOL)application:(UIApplication *)application
+            openURL:(NSURL *)url
+            options:(NSDictionary<UIApplicationOpenURLOptionsKey, id> *)options {
+    [self dispatchDeepLinkURL:url];
+    return YES;
+}
+
+// Forward universal links (associated domains) to React Native's Linking
+// module by extracting the underlying https URL and routing it through the
+// same pre-bridge queue as everything else.
+- (BOOL)application:(UIApplication *)application
+   continueUserActivity:(NSUserActivity *)userActivity
+     restorationHandler:
+         (void (^)(NSArray<id<UIUserActivityRestoring>> *_Nullable))restorationHandler {
+    if ([userActivity.activityType isEqualToString:NSUserActivityTypeBrowsingWeb]) {
+        [self dispatchDeepLinkURL:userActivity.webpageURL];
+        return YES;
+    }
+    return NO;
+}
+
+- (void)dispatchDeepLinkURL:(NSURL *)url {
+    if (url == nil) {
+        return;
+    }
+    if (gRNNReactRuntimeReady) {
+        [RCTLinkingManager application:[UIApplication sharedApplication]
+                               openURL:url
+                               options:@{}];
+        return;
+    }
+    if (gRNNPendingDeepLinkURLs == nil) {
+        gRNNPendingDeepLinkURLs = [NSMutableArray array];
+    }
+    [gRNNPendingDeepLinkURLs addObject:url];
+}
+
+- (void)rnn_installDeepLinkObservers {
+    // `RCTContentDidAppearNotification` is posted by Fabric's root view
+    // once content has rendered. RNN forces bridgeless/new-arch, so the
+    // legacy `RCTJavaScriptDidLoadNotification` never fires; we rely on
+    // this Fabric signal exclusively.
+    [[NSNotificationCenter defaultCenter] addObserver:self
+                                             selector:@selector(rnn_handleReactRuntimeReady:)
+                                                 name:RCTContentDidAppearNotification
+                                               object:nil];
+}
+
+- (void)rnn_handleReactRuntimeReady:(NSNotification *)notification {
+    gRNNReactRuntimeReady = YES;
+    NSArray<NSURL *> *pending = [gRNNPendingDeepLinkURLs copy];
+    [gRNNPendingDeepLinkURLs removeAllObjects];
+    for (NSURL *url in pending) {
+        [RCTLinkingManager application:[UIApplication sharedApplication]
+                               openURL:url
+                               options:@{}];
+    }
+}
+
 
 #if !RNN_RN_VERSION_79_OR_NEWER
 - (NSURL *)sourceURLForBridge:(RCTBridge *)bridge {
diff --git a/playground/ios/playground/AppDelegate.mm b/playground/ios/playground/AppDelegate.mm
index a2eba733d16..8a31ff8b99d 100644
--- a/playground/ios/playground/AppDelegate.mm
+++ b/playground/ios/playground/AppDelegate.mm
@@ -1,18 +1,8 @@
 #import "AppDelegate.h"
 #import "RNNCustomViewController.h"
 #import <ReactNativeNavigation/ReactNativeNavigation.h>
-#import <React/RCTBridge.h>
-#import <React/RCTLinkingManager.h>
-#import <React/RCTRootView.h>
 #import <UserNotifications/UserNotifications.h>
 
-// URLs that arrive (notification tap, openURL) before the JS bridge is
-// ready are queued here and flushed when the bridge finishes loading.
-// Without this, cold-start notifications would post `RCTOpenURLNotification`
-// into the void because RCTLinkingManager hasn't subscribed yet.
-static NSMutableArray<NSURL *> *gPendingDeepLinkURLs = nil;
-static BOOL gJavaScriptDidLoad = NO;
-
 #if !RNN_RN_VERSION_79_OR_NEWER
 @interface AppDelegate () <RCTBridgeDelegate, UNUserNotificationCenterDelegate>
 @end
@@ -63,74 +53,16 @@ - (BOOL)application:(UIApplication *)application
 		return [[RNNCustomViewController alloc] initWithProps:props];
 	}];
 
-	// Receive notification taps (Detox sendUserNotification & real push taps)
+	// Demo: route notification taps through RNN's deep-linking pipeline by
+	// installing this AppDelegate as the UNUserNotificationCenter delegate.
+	// (Apps that already own this delegate via Firebase/OneSignal/etc. can
+	// instead call `[self dispatchDeepLinkURL:url]` from their existing
+	// handler — same effect.)
 	[UNUserNotificationCenter currentNotificationCenter].delegate = self;
 
-	// Flush deep links that arrived before the JS bridge was up.
-	// In legacy mode `RCTJavaScriptDidLoadNotification` fires after the
-	// bridge loads JS. In bridgeless/new-arch that notification does NOT
-	// fire, so we also listen for `RCTContentDidAppearNotification` which
-	// is posted by Fabric's root view once content has rendered — by which
-	// point RCTLinkingManager is already instantiated and listening.
-	[[NSNotificationCenter defaultCenter] addObserver:self
-                                             selector:@selector(handleJavaScriptDidLoad:)
-                                                 name:RCTJavaScriptDidLoadNotification
-                                               object:nil];
-	[[NSNotificationCenter defaultCenter] addObserver:self
-                                             selector:@selector(handleJavaScriptDidLoad:)
-                                                 name:RCTContentDidAppearNotification
-                                               object:nil];
-
 	return YES;
 }
 
-#pragma mark - Deep linking
-
-// Forward foreground URL openings (custom schemes & universal links)
-// to React Native's Linking module so JS can handle them.
-- (BOOL)application:(UIApplication *)application
-            openURL:(NSURL *)url
-            options:(NSDictionary<UIApplicationOpenURLOptionsKey, id> *)options {
-	[self dispatchDeepLinkURL:url];
-	return YES;
-}
-
-// Dispatch a deep link URL. If RCTLinkingManager hasn't subscribed yet
-// (cold-start, JS bridge still loading), queue it for replay after
-// RCTJavaScriptDidLoadNotification fires.
-- (void)dispatchDeepLinkURL:(NSURL *)url {
-	if (url == nil) { return; }
-	if (gJavaScriptDidLoad) {
-		[RCTLinkingManager application:[UIApplication sharedApplication]
-                               openURL:url
-                               options:@{}];
-		return;
-	}
-	if (gPendingDeepLinkURLs == nil) {
-		gPendingDeepLinkURLs = [NSMutableArray array];
-	}
-	[gPendingDeepLinkURLs addObject:url];
-}
-
-- (void)handleJavaScriptDidLoad:(NSNotification *)notification {
-	gJavaScriptDidLoad = YES;
-	NSArray<NSURL *> *pending = [gPendingDeepLinkURLs copy];
-	[gPendingDeepLinkURLs removeAllObjects];
-	for (NSURL *url in pending) {
-		[RCTLinkingManager application:[UIApplication sharedApplication]
-                               openURL:url
-                               options:@{}];
-	}
-}
-
-- (BOOL)application:(UIApplication *)application
-continueUserActivity:(NSUserActivity *)userActivity
- restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> *))restorationHandler {
-	return [RCTLinkingManager application:application
-                    continueUserActivity:userActivity
-                      restorationHandler:restorationHandler];
-}
-
 #pragma mark - UNUserNotificationCenterDelegate
 
 // Surface notifications while the app is in the foreground so the user
@@ -150,9 +82,9 @@ - (void)userNotificationCenter:(UNUserNotificationCenter *)center
                       UNNotificationPresentationOptionSound);
 }
 
-// Notification tap → if payload carries `url`, route it through the
-// existing Linking pipeline so deep linking reacts the same way regardless
-// of whether the URL came from the OS or a notification.
+// Notification tap → if payload carries `url`, route it through RNN's
+// deep-linking pipeline (inherited `dispatchDeepLinkURL:` queues until
+// the React runtime is ready, then forwards to RCTLinkingManager).
 - (void)userNotificationCenter:(UNUserNotificationCenter *)center
 didReceiveNotificationResponse:(UNNotificationResponse *)response
          withCompletionHandler:(void (^)(void))completionHandler {
@@ -183,4 +115,3 @@ - (NSURL *)bundleURL
 #endif
 
 @end
-

From 2bdb75002df52c59b7428d6d1a8f8178fb108e92 Mon Sep 17 00:00:00 2001
From: Mark de Vocht <markd@wix.com>
Date: Wed, 13 May 2026 11:57:19 +0300
Subject: [PATCH 3/3] Documentation update

---
 .claude/skills/rnn-codebase/SKILL.md    |  3 ++
 ARCHITECTURE.md                         |  4 ++
 ios/ARCHITECTURE.md                     |  5 ++
 src/ARCHITECTURE.md                     | 30 ++++++++++++
 website/docs/docs/docs-deep-linking.mdx | 64 +++++++++++++++++++++++--
 5 files changed, 102 insertions(+), 4 deletions(-)

diff --git a/.claude/skills/rnn-codebase/SKILL.md b/.claude/skills/rnn-codebase/SKILL.md
index 02a66a0b4fc..ddd0a9ce9d9 100644
--- a/.claude/skills/rnn-codebase/SKILL.md
+++ b/.claude/skills/rnn-codebase/SKILL.md
@@ -77,6 +77,7 @@ Each controller type has a Presenter that applies options to views:
 | React view rendering | — | `ios/RNNReactView.mm` | `react/ReactView.java` |
 | Events to JS | `src/adapters/NativeEventsReceiver.ts` | `ios/RNNEventEmitter.mm` | `react/events/EventEmitter.java` |
 | Component registration | `src/components/ComponentRegistry.ts` | — | — |
+| Deep linking (URL → screen) | `src/linking/` (`LinkingHandler`, `URLParser`, `RouteMatcher`, `DeferredLinkQueue`, `ModalLayoutBuilder`) | `ios/RNNAppDelegate.mm` (`dispatchDeepLinkURL:`, cold-start queue, `RCTContentDidAppearNotification`) | `NavigationActivity.onNewIntent` → `ReactGateway` |
 
 ### By directory
 
@@ -149,3 +150,5 @@ API layout → OptionsCrawler.crawl() → LayoutProcessor.process()
 - Options that exist in JS types may not be implemented on both platforms — check the presenter
 - `passProps` are stored in JS `Store`, not sent to native (cleared before bridge crossing)
 - The `lib/` folder is generated — never edit it, edit `src/` instead
+- Deep links are processed only after the first `setRoot()` resolves; pre-bridge URLs on iOS are queued natively in `RNNAppDelegate` and flushed on `RCTContentDidAppearNotification` (bridgeless mode — `RCTJavaScriptDidLoadNotification` does NOT fire)
+- `ModalLayoutBuilder` strips React-reserved keys (`ref`, `key`) from URL query params before they reach `passProps`, to avoid React 19 ref-validation crashes
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index c3b6a8bebdb..c1387f39769 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -75,6 +75,10 @@ Core commands available through the Navigation API:
 - **Modal**: `showModal()`, `dismissModal()`, `dismissAllModals()`
 - **Overlay**: `showOverlay()`, `dismissOverlay()`, `dismissAllOverlays()`
 - **Options**: `setDefaultOptions()`, `mergeOptions()`, `updateProps()`
+- **Linking**: `setLinking()`, `handleDeepLink()`, `setLinkingReady()` - URL-to-screen routing
+
+### Deep Linking
+URL-driven navigation is implemented entirely in the JS layer (`src/linking/`) and feeds into the standard command pipeline. Configure with `Navigation.setLinking({ prefixes, config: { screens } })`; matched URLs are presented as modals by default (preserving the user's current navigation state). Customize via `getModal`/`onLink` hooks; gate processing on auth via `isReady`/`setLinkingReady`. Native plumbing — `application:openURL:`, `application:continueUserActivity:`, cold-start URL queueing — lives in `RNNAppDelegate` (iOS) and `NavigationActivity.onNewIntent` (Android), so subclassing the base classes is sufficient. See [Deep Linking docs](https://wix.github.io/react-native-navigation/docs/deep-linking).
 
 ### Options System
 Styling and behavior is controlled via a hierarchical options object:
diff --git a/ios/ARCHITECTURE.md b/ios/ARCHITECTURE.md
index 049c6f6580d..43a43269ba9 100644
--- a/ios/ARCHITECTURE.md
+++ b/ios/ARCHITECTURE.md
@@ -28,6 +28,11 @@ Base class that user's AppDelegate must extend. Handles React Native and navigat
 - Creates `RCTRootViewFactory` and `ReactHost`
 - Calls `[ReactNativeNavigation bootstrapWithHost:]` to initialize navigation
 - Handles RN version differences (0.77, 0.78, 0.79+) via compile-time macros
+- **Deep linking plumbing**:
+  - Implements `application:openURL:options:` and `application:continueUserActivity:restorationHandler:`; both call `-dispatchDeepLinkURL:`.
+  - `-dispatchDeepLinkURL:` posts `RCTOpenURLNotification` directly if the React runtime is ready, otherwise enqueues the URL.
+  - Observes `RCTContentDidAppearNotification` (the Fabric/bridgeless signal) to flush the queue. This solves the cold-start race where URLs (push notifications, OS link launches) arrive before `RCTLinkingManager` is listening.
+  - Subclasses can call `-dispatchDeepLinkURL:` manually from notification delegates or any other URL source; the queueing behavior is reused automatically.
 
 ### ReactNativeNavigation Bootstrap
 **File**: `ReactNativeNavigation.h/mm`
diff --git a/src/ARCHITECTURE.md b/src/ARCHITECTURE.md
index 73f804a4b91..2ac2a3b27c6 100644
--- a/src/ARCHITECTURE.md
+++ b/src/ARCHITECTURE.md
@@ -18,6 +18,7 @@ src/
 ├── components/              # React component management
 ├── events/                  # Event system
 ├── interfaces/              # TypeScript type definitions
+├── linking/                 # Deep-linking framework (URL → command)
 └── processors/              # Extensibility hooks
 ```
 
@@ -207,6 +208,35 @@ Notifies listeners of command lifecycle (start, complete).
 | `RNN.PreviewCompleted` | 3D Touch preview completed |
 | `RNN.CommandCompleted` | Navigation command finished |
 
+## Linking Layer
+
+Implements URL-to-screen routing on top of the standard command pipeline. The whole feature is JS-only; it consumes URLs from RN's `Linking` module and dispatches `showModal` (or a user-supplied command) when a match is found.
+
+**Public surface** (proxied through `NavigationDelegate`):
+- `Navigation.setLinking(config)` — configure prefixes, screen map, and customization hooks
+- `Navigation.handleDeepLink(url)` — manually feed a URL (push notifications, branch.io, App Clips)
+- `Navigation.setLinkingReady(ready)` — user-controlled gate for deferred deep links
+
+**Internal modules** (`src/linking/`):
+
+| File | Purpose |
+|------|---------|
+| `LinkingHandler.ts` | Orchestrator. Subscribes to `Linking.url`/`getInitialURL`, drives the queue, dispatches matches. Instantiated by `NavigationRoot`. |
+| `URLParser.ts` | Strips prefix (longest match), removes fragment, decodes path segments + query params. |
+| `RouteMatcher.ts` | Compiles `ScreensConfig` into a `RouteNode` tree; matches paths to screen chains with parameter extraction. |
+| `DeferredLinkQueue.ts` | FIFO queue. Holds URLs until both gates open (root-ready + user-ready). |
+| `ModalLayoutBuilder.ts` | Default presentation: wraps the matched chain in a `stack`, merges params into `passProps`, filters React-reserved keys (`ref`, `key`). |
+| `types.ts` | Public types: `LinkingConfig`, `RouteMatch`, `ScreensConfig`, etc. (re-exported via `src/index.ts`). |
+
+**Readiness gates** — a URL is dispatched only when both are true:
+1. **Root-ready** (automatic): the first `Navigation.setRoot()` has resolved. `NavigationRoot.setRoot` calls `linkingHandler.setRootReady()` after the promise resolves.
+2. **User-ready** (optional): `config.isReady()` returns `true`, or `setLinkingReady(true)` was called.
+
+**Resolution priority** when a match is found:
+1. `config.onLink(match)` — full escape hatch, RNN does nothing else
+2. `config.getModal(match)` — custom modal layout
+3. Default `ModalLayoutBuilder` output
+
 ## Processors Layer
 
 ### OptionProcessorsStore
diff --git a/website/docs/docs/docs-deep-linking.mdx b/website/docs/docs/docs-deep-linking.mdx
index e5111eab2c0..ea3d8ecf9e0 100644
--- a/website/docs/docs/docs-deep-linking.mdx
+++ b/website/docs/docs/docs-deep-linking.mdx
@@ -110,6 +110,15 @@ myapp://search?q=hello&page=2
 → Search screen receives passProps: { q: 'hello', page: '2' }
 ```
 
+#### Reserved keys
+
+The query/path keys `ref` and `key` are **not** forwarded as `passProps`. React reserves these names (`ref` is consumed by React itself; passing a string `ref` to a component crashes under React 19's stricter validation). RNN silently drops them and logs a dev-mode warning. Rename any conflicting URL parameters before they reach your links:
+
+```
+myapp://user/42?ref=push   →  passProps: { id: '42' }       (ref dropped + warning)
+myapp://user/42?source=push →  passProps: { id: '42', source: 'push' }
+```
+
 ## Customizing presentation
 
 By default, every matched link becomes a modal containing a stack with the matched chain pushed in order. If you need to customize either the layout or the navigation command itself, the config exposes two hooks.
@@ -240,11 +249,13 @@ async function onLoginSuccess() {
 Some links don't arrive via the system URL handler — push-notification payloads, branch.io tokens, App Clips. Feed them into the same pipeline with `Navigation.handleDeepLink(url)`:
 
 ```js
-Navigation.handleDeepLink('myapp://user/42?ref=notification');
+Navigation.handleDeepLink('myapp://user/42?source=notification');
 ```
 
 This runs the URL through parse → match → present exactly like a system-delivered link, including readiness gates.
 
+If you'd rather hand the URL off natively (e.g. from a `UNUserNotificationCenterDelegate` you already maintain), call `[self dispatchDeepLinkURL:url]` inside your `RNNAppDelegate` subclass — same behavior, with cold-start queueing built in. See [Native setup → iOS → Notification taps](#ios) for an example.
+
 ## Complete example
 
 ```js
@@ -295,11 +306,11 @@ With this configuration:
 
 ## Native setup
 
-The framework consumes URLs from React Native's `Linking` API. You still configure the URL schemes and universal links at the platform level.
+The framework consumes URLs from React Native's `Linking` API. You still configure the URL schemes and universal links at the platform level — but, unlike most React Native apps, you don't need to hand-write `application:openURL:` or `application:continueUserActivity:` glue. As long as your `AppDelegate` subclasses `RNNAppDelegate`, custom-scheme openings and universal links are forwarded to JS automatically, including cold-start URLs that arrive before the React runtime is ready.
 
 ### iOS
 
-Add your URL scheme to `Info.plist`:
+**1. Register your URL scheme in `Info.plist`:**
 
 ```xml
 <key>CFBundleURLTypes</key>
@@ -313,7 +324,50 @@ Add your URL scheme to `Info.plist`:
 </array>
 ```
 
-For universal links, add the Associated Domains entitlement and host an `apple-app-site-association` file. See [Apple's documentation](https://developer.apple.com/documentation/xcode/supporting-associated-domains).
+**2. (Optional) Universal links.** Add the Associated Domains entitlement and host an `apple-app-site-association` file — see [Apple's docs](https://developer.apple.com/documentation/xcode/supporting-associated-domains). `RNNAppDelegate` already implements `application:continueUserActivity:restorationHandler:` and forwards browser-activity URLs through the same pipeline.
+
+**3. (Optional) Notification taps.** Notifications aren't routed automatically because most apps already own `UNUserNotificationCenter.current.delegate` via Firebase / OneSignal / etc. From your existing notification handler, hand the URL off to RNN:
+
+```objc
+#import "AppDelegate.h"  // your subclass of RNNAppDelegate
+#import <UserNotifications/UserNotifications.h>
+
+@interface AppDelegate () <UNUserNotificationCenterDelegate>
+@end
+
+@implementation AppDelegate
+
+- (BOOL)application:(UIApplication *)application
+didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
+  [super application:application didFinishLaunchingWithOptions:launchOptions];
+  [UNUserNotificationCenter currentNotificationCenter].delegate = self;
+  return YES;
+}
+
+- (void)userNotificationCenter:(UNUserNotificationCenter *)center
+       willPresentNotification:(UNNotification *)notification
+         withCompletionHandler:(void (^)(UNNotificationPresentationOptions))completionHandler {
+  completionHandler(UNNotificationPresentationOptionBanner |
+                    UNNotificationPresentationOptionList |
+                    UNNotificationPresentationOptionSound);
+}
+
+- (void)userNotificationCenter:(UNUserNotificationCenter *)center
+didReceiveNotificationResponse:(UNNotificationResponse *)response
+         withCompletionHandler:(void (^)(void))completionHandler {
+  NSString *urlString = response.notification.request.content.userInfo[@"url"];
+  if ([urlString isKindOfClass:[NSString class]]) {
+    [self dispatchDeepLinkURL:[NSURL URLWithString:urlString]];
+  }
+  completionHandler();
+}
+
+@end
+```
+
+`dispatchDeepLinkURL:` is inherited from `RNNAppDelegate`. It safely handles cold-start (URLs arriving before the React runtime is ready are queued and flushed automatically once content first renders) so you can call it from anywhere — push handlers, deferred-deep-link SDKs, branch.io callbacks, etc.
+
+The JS equivalent is `Navigation.handleDeepLink(url)`; use whichever fits the layer you're working at.
 
 ### Android
 
@@ -334,6 +388,8 @@ Add an intent filter to your `MainActivity` in `AndroidManifest.xml`:
 
 For App Links, add `android:autoVerify="true"` and host an `assetlinks.json`. See [Android's documentation](https://developer.android.com/training/app-links).
 
+`NavigationActivity` already forwards both cold-start (`getIntent()`) and warm (`onNewIntent`) URLs to React Native's `Linking` module — no extra Java/Kotlin needed. Notification taps that carry a deep-link URI (via `PendingIntent` with `ACTION_VIEW`) flow through the same `onNewIntent` path automatically.
+
 ## API reference
 
 ### `Navigation.setLinking(config)`