Documentation update

Author: markdevocht

.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

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:

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`

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

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