react-native-navigation 8.8.6 → 8.8.7

package/lib/typescript/linking/types.d.ts

@@ -0,0 +1,107 @@
+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;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/typescript/linking/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/linking/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAE9C;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,qCAAqC;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,IAAI,EAAE,iBAAiB,EAAE,CAAC;IAC1B,4CAA4C;IAC5C,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,uDAAuD;IACvD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,uBAAuB;IACvB,QAAQ,EAAE,SAAS,EAAE,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,YAAY,GACpB,MAAM,GACN;IACE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB,CAAC;AAEN,MAAM,WAAW,aAAa;IAC5B,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY,CAAC;CACpC;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,8BAA8B;IAC9B,MAAM,EAAE;QACN,OAAO,EAAE,aAAa,CAAC;KACxB,CAAC;IACF;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,MAAM,GAAG,SAAS,CAAC;IACrD;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IACrC;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC;CACzB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-navigation",
-  "version": "8.8.6",
+  "version": "8.8.7",
   "description": "React Native Navigation - truly native navigation for iOS and Android",
   "license": "MIT",
   "nativePackage": true,

package/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

package/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
    */

package/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
    */

package/src/adapters/AndroidCustomRowForwarder.ts

@@ -0,0 +1,83 @@
+import { NativeModules, Platform } from 'react-native';
+
+import { Options } from '../interfaces/Options';
+
+/**
+ * Walks a Layout / Options tree looking for `bottomTabs.customRow`
+ * configuration and forwards it to the Android-only native module
+ * `RNNBottomTabsCustomRowModule`.
+ *
+ * On iOS this is a no-op — the existing native options parser already picks
+ * up `bottomTabs.customRow` and applies it to the iOS custom row.
+ *
+ * The original layout/options object is *never* modified — both pipelines
+ * (iOS native parser, Android native parser which currently ignores the
+ * field) keep seeing the same data.
+ */
+export class AndroidCustomRowForwarder {
+  forwardFromLayout(layout: any) {
+    if (!this.shouldForward()) return;
+    const config = this.findCustomRowInLayout(layout);
+    if (config) this.send(config);
+  }
+
+  forwardFromLayouts(layouts: any[]) {
+    if (!this.shouldForward()) return;
+    for (const layout of layouts) {
+      const config = this.findCustomRowInLayout(layout);
+      if (config) {
+        this.send(config);
+        return;
+      }
+    }
+  }
+
+  forwardFromOptions(options: Options | undefined) {
+    if (!this.shouldForward() || !options) return;
+    const config = this.extractFromOptions(options);
+    if (config) this.send(config);
+  }
+
+  private shouldForward(): boolean {
+    return Platform.OS === 'android';
+  }
+
+  private findCustomRowInLayout(layout: any): object | null {
+    if (!layout || typeof layout !== 'object') return null;
+    // Walk both the raw layout shape (`layout.options`) and the
+    // post-`layoutTreeParser.parse` shape (`layout.data.options`).
+    const direct =
+      this.extractFromOptions(layout.options) ??
+      this.extractFromOptions(layout.data?.options);
+    if (direct) return direct;
+    const children = layout.children;
+    if (Array.isArray(children)) {
+      for (const child of children) {
+        const found = this.findCustomRowInLayout(child);
+        if (found) return found;
+      }
+    }
+    return null;
+  }
+
+  private extractFromOptions(options: Options | undefined): object | null {
+    if (!options || typeof options !== 'object') return null;
+    const bottomTabs: any = (options as any).bottomTabs;
+    if (!bottomTabs || typeof bottomTabs !== 'object') return null;
+    const customRow = bottomTabs.customRow;
+    if (!customRow || typeof customRow !== 'object') return null;
+    return customRow;
+  }
+
+  private send(config: object): void {
+    const nativeModule = (NativeModules as any).RNNBottomTabsCustomRowModule;
+    if (!nativeModule || typeof nativeModule.configure !== 'function') {
+      return;
+    }
+    try {
+      nativeModule.configure(config);
+    } catch {
+      // Native module not ready yet; attacher will pick up config on next rescan.
+    }
+  }
+}

package/src/commands/Commands.ts

@@ -13,8 +13,11 @@ import { Store } from '../components/Store';
 import { LayoutProcessor } from '../processors/LayoutProcessor';
 import { CommandName } from '../interfaces/CommandName';
 import { OptionsCrawler } from './OptionsCrawler';
+import { AndroidCustomRowForwarder } from '../adapters/AndroidCustomRowForwarder';
 
 export class Commands {
+  private readonly androidCustomRowForwarder = new AndroidCustomRowForwarder();
+
   constructor(
     private readonly store: Store,
     private readonly nativeCommandsSender: NativeCommandsSender,
@@ -59,6 +62,8 @@ export class Commands {
       this.layoutTreeCrawler.crawl(overlayLayout, CommandName.SetRoot);
     });
 
+    this.androidCustomRowForwarder.forwardFromLayouts([root, ...modals, ...overlays]);
+
     const result = this.nativeCommandsSender.setRoot(commandId, { root, modals, overlays });
     return result;
   }
@@ -67,6 +72,8 @@ export class Commands {
     const input = cloneDeep(options);
     this.optionsProcessor.processDefaultOptions(input, CommandName.SetDefaultOptions);
 
+    this.androidCustomRowForwarder.forwardFromOptions(input);
+
     this.nativeCommandsSender.setDefaultOptions(input);
     this.commandsObserver.notify(CommandName.SetDefaultOptions, { options });
   }
@@ -82,6 +89,8 @@ export class Commands {
         `Navigation.mergeOptions was invoked on component with id: ${componentId} before it is mounted, this can cause UI issues and should be avoided.\n Use static options instead.`
       );
 
+    this.androidCustomRowForwarder.forwardFromOptions(input);
+
     this.nativeCommandsSender.mergeOptions(componentId, input);
     this.commandsObserver.notify(CommandName.MergeOptions, { componentId, options });
   }
@@ -101,6 +110,8 @@ export class Commands {
     this.commandsObserver.notify(CommandName.ShowModal, { commandId, layout: layoutNode });
     this.layoutTreeCrawler.crawl(layoutNode, CommandName.ShowModal);
 
+    this.androidCustomRowForwarder.forwardFromLayout(layoutNode);
+
     const result = this.nativeCommandsSender.showModal(commandId, layoutNode);
     return result;
   }
@@ -135,6 +146,8 @@ export class Commands {
     this.commandsObserver.notify(CommandName.Push, { commandId, componentId, layout });
     this.layoutTreeCrawler.crawl(layout, CommandName.Push);
 
+    this.androidCustomRowForwarder.forwardFromLayout(layout);
+
     const result = this.nativeCommandsSender.push(commandId, componentId, layout);
     return result;
   }
@@ -181,6 +194,8 @@ export class Commands {
       this.layoutTreeCrawler.crawl(layoutNode, CommandName.SetStackRoot);
     });
 
+    this.androidCustomRowForwarder.forwardFromLayouts(input);
+
     const result = this.nativeCommandsSender.setStackRoot(commandId, componentId, input);
     return result;
   }

package/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';

package/src/interfaces/Options.ts

@@ -999,6 +999,54 @@ export interface OptionsBottomTabs {
    * Control the shadow of the Bottom tabs bar
    */
   shadow?: ShadowOptions;
+  /**
+   * Visual options for the floating row that hosts custom React-component
+   * bottom tab cells. Only takes effect when every `bottomTab.component`
+   * is set on that `bottomTabs` layout.
+   *
+   * Same JS shape on iOS and Android. iOS applies options via the native
+   * parser; Android receives them through `RNNBottomTabsCustomRowModule`.
+   */
+  customRow?: BottomTabsCustomRowOptions;
+}
+
+export interface BottomTabsCustomRowOptions {
+  /**
+   * Content height of the row in points (iOS) / dp (Android). Excludes
+   * safe-area inset. Total row height = `height` + safe bottom + `bottomMargin`.
+   *
+   * Default: native tab content height; on iOS 26+ an extra 18pt when omitted.
+   */
+  height?: number;
+  /**
+   * Solid background color for the row. When set, overrides
+   * `backgroundEffect`.
+   */
+  backgroundColor?: Color;
+  /**
+   * Visual effect for the row background.
+   * - `glass`: iOS 26+ `UIGlassEffect`.
+   * - `blur`: `UIBlurEffect` with `systemChromeMaterial`.
+   * - `none`: fully transparent.
+   *
+   * Default: `glass` on iOS 26+, `blur` on older versions.
+   */
+  backgroundEffect?: 'glass' | 'blur' | 'none';
+  /**
+   * Corner radius applied to the row's background.
+   * Default: 28 on iOS 26+, 0 below.
+   */
+  cornerRadius?: number;
+  /**
+   * Horizontal inset from the screen edges.
+   * Default: 16 on iOS 26+, 0 below.
+   */
+  horizontalMargin?: number;
+  /**
+   * Distance between the row's bottom edge and the safe-area bottom.
+   * Default: 0.
+   */
+  bottomMargin?: number;
 }
 
 export interface ShadowOptions {
@@ -1035,6 +1083,45 @@ export type ImageResource = ImageSourcePropType | string | ImageSystemSource;
 export interface OptionsBottomTab {
   dotIndicator?: DotIndicatorOptions;
 
+  /**
+   * Render a React component as the tab item content (icon + text area).
+   *
+   * When set, the native icon, text and font props (`text`, `icon`,
+   * `selectedIcon`, `sfSymbol`, `sfSelectedSymbol`, `iconColor`,
+   * `selectedIconColor`, `iconWidth`, `iconHeight`, `iconInsets`,
+   * `fontFamily`, `fontWeight`, `fontSize`, `selectedFontSize`,
+   * `textColor`, `selectedTextColor`) are ignored for that tab.
+   *
+   * For the custom rendering to take effect every tab in the
+   * `bottomTabs` layout must declare a `component`. If only some
+   * tabs declare one a warning is logged and native rendering is
+   * used for all tabs.
+   *
+   * The component receives the following initial props and
+   * subsequent prop updates:
+   * - `componentId`: stable id for this tab item instance
+   * - `tabIndex`: position of the tab (0-based)
+   * - `selected`: whether this tab is currently selected
+   * - `badge`: current badge text (mirrors `bottomTab.badge`)
+   *
+   * Native still owns selection, hide/show, drawBehind, animations
+   * and the dot indicator. To switch tabs from inside the component
+   * use `Navigation.mergeOptions(parentId, { bottomTabs: { currentTabIndex } })`.
+   */
+  component?: {
+    /**
+     * The registered name of the component (passed to
+     * `Navigation.registerComponent`).
+     */
+    name: string;
+    /**
+     * Props passed once when the component is created. Updates from
+     * native (`selected`, `badge`) are delivered as separate prop
+     * updates.
+     */
+    passProps?: object;
+  };
+
   /**
    * Set the text to display below the icon
    */

package/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();
+  });
+});

package/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];
+  }
+}