@multiplatform.one/router 6.7.0 → 7.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multiplatform.one/router",
-  "version": "6.7.0",
+  "version": "7.1.0",
   "description": "multiplatform.one router with support for react-router-dom and react-navigation",
   "keywords": [
     "react",
@@ -62,11 +62,11 @@
   },
   "dependencies": {
     "@vxrn/color-scheme": "~1.16.5",
-    "@multiplatform.one/platform": "6.7.0"
+    "@multiplatform.one/platform": "7.1.0"
   },
   "devDependencies": {
     "@react-navigation/native": "^7.2.2",
-    "@tamagui/build": "2.0.0-rc.41",
+    "@tamagui/build": "2.7.6",
     "@testing-library/react": "^16.3.2",
     "@vitejs/plugin-react": "^6.0.1",
     "one": "^1.16.5",
@@ -77,8 +77,8 @@
     "typescript": "~5.9.3",
     "vite": "^8.0.10",
     "vitest": "^4.1.5",
-    "@multiplatform.one/test-utils": "6.7.0",
-    "@multiplatform.one/config": "6.7.0"
+    "@multiplatform.one/config": "7.1.0",
+    "@multiplatform.one/test-utils": "7.1.0"
   },
   "peerDependencies": {
     "@react-navigation/native": "~7.2.2",

package/src/seam/DomNavigationHost.spec.tsx

@@ -1,5 +1,6 @@
 import { act, render, screen } from "@testing-library/react";
-import { beforeEach, describe, expect, it } from "vitest";
+import { StrictMode, useEffect, useRef } from "react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
 import { DomNavigationHost } from "./DomNavigationHost";
 import { stackNavigator } from "./navigator";
 import { useParams } from "./oneAdapter";
@@ -108,13 +109,103 @@ describe("DomNavigationHost", () => {
     expect((container.firstElementChild as HTMLElement).style.minHeight).toBe("480px");
   });
 
-  it("restores an initial route as a root replace", () => {
+  it("restores an initial route above the root so back affordances survive", () => {
     const { container } = renderHost("/todos");
     expect(pageByTag(container, "todos").dataset.seamActive).toBe("true");
+    // The manifest root stays beneath the restored page (documented replace
+    // semantics) — a restored detail page must not dead-end its back button.
     expect(stackNavigator.getSnapshot()).toMatchObject({
       tag: "todos",
-      depth: 1,
-      canGoBack: false,
+      depth: 2,
+      canGoBack: true,
     });
+    act(() => stackNavigator.back());
+    expect(pageByTag(container, "home").dataset.seamActive).toBe("true");
+  });
+
+  // The root page's content renders BEFORE the attach effect applies
+  // initialHref — a restored route's query params must already be seeded by
+  // then, or mount-time state seeding (list filters from
+  // useLocalSearchParams) reads an empty object and the URL round-trip
+  // silently drops the restored filters.
+  it("seeds a restored route's params before the first content render", () => {
+    const firstRenderParams: Array<Record<string, unknown>> = [];
+    function SeedProbe() {
+      const params = useParams();
+      const first = useRef(true);
+      if (first.current) {
+        first.current = false;
+        firstRenderParams.push({ ...params });
+      }
+      return <span data-testid="seed-params">{String(params.q ?? "")}</span>;
+    }
+    stackNavigator.detach();
+    stackNavigator.configure(ROUTES);
+    render(
+      <DomNavigationHost
+        initialHref="/?q=fire"
+        routes={[
+          { ...ROUTES[0]!, element: <SeedProbe /> },
+          { ...ROUTES[1]!, element: <div data-testid="todos-screen" /> },
+          { ...ROUTES[2]!, element: <DetailProbe /> },
+        ]}
+      />,
+    );
+    expect(firstRenderParams[0]).toMatchObject({ q: "fire" });
+    expect(screen.getByTestId("seed-params").textContent).toBe("fire");
+  });
+
+  // The warm-deep-link drop: a navigation dispatched from a mounted screen's
+  // own effect fires BEFORE the host's attach effect (child effects run
+  // first). It must queue and apply, not vanish based on timing.
+  it("applies a deep link dispatched from a screen effect before the host attached", () => {
+    const log = vi.spyOn(console, "log").mockImplementation(() => {});
+    function RedirectingHome() {
+      useEffect(() => {
+        stackNavigator.push("/pokemon/pikachu");
+      }, []);
+      return <div data-testid="home-screen" />;
+    }
+    stackNavigator.detach();
+    stackNavigator.configure(ROUTES);
+    const { container } = render(
+      <DomNavigationHost
+        routes={[
+          { ...ROUTES[0]!, element: <RedirectingHome /> },
+          { ...ROUTES[1]!, element: <div data-testid="todos-screen" /> },
+          { ...ROUTES[2]!, element: <DetailProbe /> },
+        ]}
+      />,
+    );
+    expect(pageByTag(container, "pokemon-detail").dataset.seamActive).toBe("true");
+    expect(screen.getByTestId("detail-params").textContent).toBe("pikachu");
+    expect(stackNavigator.getSnapshot()).toMatchObject({ depth: 2, canGoBack: true });
+    log.mockRestore();
+  });
+
+  // StrictMode's mount→unmount→remount opens a detach window; the host must
+  // come back attached and both queued and post-mount navigations must land.
+  it("survives a StrictMode remount cycle and still navigates", () => {
+    const log = vi.spyOn(console, "log").mockImplementation(() => {});
+    stackNavigator.detach();
+    stackNavigator.configure(ROUTES);
+    const { container } = render(
+      <StrictMode>
+        <DomNavigationHost
+          initialHref="/todos"
+          routes={[
+            { ...ROUTES[0]!, element: <div data-testid="home-screen" /> },
+            { ...ROUTES[1]!, element: <div data-testid="todos-screen" /> },
+            { ...ROUTES[2]!, element: <DetailProbe /> },
+          ]}
+        />
+      </StrictMode>,
+    );
+    expect(pageByTag(container, "todos").dataset.seamActive).toBe("true");
+    expect(stackNavigator.getSnapshot()).toMatchObject({ tag: "todos", depth: 2 });
+    act(() => stackNavigator.push("/pokemon/mew"));
+    expect(pageByTag(container, "pokemon-detail").dataset.seamActive).toBe("true");
+    expect(screen.getByTestId("detail-params").textContent).toBe("mew");
+    log.mockRestore();
   });
 });

package/src/seam/DomNavigationHost.tsx

@@ -93,8 +93,9 @@ export interface DomRouteEntry extends RouteDef {
 export interface DomNavigationHostProps {
   routes: DomRouteEntry[];
   /** Restore a previous route on mount (e.g. from vscode.getState()) —
-   *  applied as a root replace, matching MemoryRouter initialEntries
-   *  semantics (no back stack to it). */
+   *  applied as a replace ABOVE the manifest root (see the replace
+   *  semantics in navigator.ts), so a restored detail page keeps a working
+   *  back affordance to the root instead of dead-ending. */
   initialHref?: Href;
   style?: CSSProperties;
 }
@@ -155,9 +156,16 @@ export function DomNavigationHost({
 }: DomNavigationHostProps): ReactNode {
   const hostRef = useRef<HTMLDivElement>(null);
   const adapterRef = useRef<DomStackAdapter | null>(null);
-  adapterRef.current ??= new DomStackAdapter(routes[0]?.tag ?? "", () =>
-    stackNavigator.syncFromHost(),
-  );
+  if (adapterRef.current === null) {
+    // First-render lazy init. Seeding the initial route's params here (not
+    // in the attach effect, which runs AFTER page content rendered once)
+    // lets a restored route's query params reach mount-time state seeding —
+    // e.g. a root list initializing its filters from useLocalSearchParams.
+    if (initialHref !== undefined) stackNavigator.seedInitialRoute(initialHref);
+    adapterRef.current = new DomStackAdapter(routes[0]?.tag ?? "", () =>
+      stackNavigator.syncFromHost(),
+    );
+  }
   // Mount-time value only — reattaching on href identity changes would
   // reset the live stack.
   const initialHrefRef = useRef(initialHref);
@@ -165,9 +173,10 @@ export function DomNavigationHost({
   useEffect(() => {
     const adapter = adapterRef.current;
     if (!adapter) return;
-    stackNavigator.attach(adapter);
-    const restore = initialHrefRef.current;
-    if (restore) stackNavigator.replace(restore);
+    // initialHref rides attach() so the restore lands BEFORE queued deep
+    // links flush — a navigation that arrived while unattached (child
+    // effects, remount gaps) is fresher intent and must end up on top.
+    stackNavigator.attach(adapter, { initialHref: initialHrefRef.current });
     return () => stackNavigator.detach();
   }, []);
 

package/src/seam/navigator.spec.ts

@@ -79,26 +79,158 @@ describe("StackNavigator", () => {
     expect(stackNavigator.getSnapshot()).toMatchObject({ tag: "home", depth: 1 });
   });
 
-  it("replace swaps the top of the stack", () => {
+  // Replace semantics (documented in navigator.ts): with no navigation entry
+  // above the manifest root there is nothing to discard, so replace lands the
+  // target ABOVE the root like a push — cold deep links / initialHref restores
+  // keep a working back affordance (react-navigation/expo-router synthesize
+  // the anchor route for deep links the same way; Adw.NavigationView's
+  // replace on an empty view is a push).
+  it("replace on a fresh stack layers above the root so back still works", () => {
     attachDomHost();
-    stackNavigator.replace("/todos");
+    stackNavigator.replace("/pokemon/mew");
     expect(stackNavigator.getSnapshot()).toMatchObject({
-      tag: "todos",
-      depth: 1,
-      canGoBack: false,
+      tag: "pokemon-detail",
+      pathname: "/pokemon/mew",
+      depth: 2,
+      canGoBack: true,
     });
+    stackNavigator.back();
+    expect(stackNavigator.getSnapshot()).toMatchObject({ tag: "home", depth: 1 });
   });
 
-  it("ignores navigation without an attached host or matching route", () => {
-    const log = vi.spyOn(console, "log").mockImplementation(() => {});
+  it("replace lays the root down even when the host stack is empty (GTK cold start)", () => {
+    // An Adw.NavigationView is empty until the first push; the mirror still
+    // carries the configure()-seeded root. Replace must materialize BOTH the
+    // root and the target on the host, not strand the target alone.
+    const adapter = new DomStackAdapter("", () => stackNavigator.syncFromHost());
+    stackNavigator.attach(adapter);
+    expect(adapter.get_navigation_stack().get_n_items()).toBe(0);
+    stackNavigator.replace("/pokemon/mew");
+    const model = adapter.get_navigation_stack();
+    expect(model.get_n_items()).toBe(2);
+    expect(model.get_item(0)?.get_tag()).toBe("home");
+    expect(model.get_item(1)?.get_tag()).toBe("pokemon-detail");
+    expect(stackNavigator.getSnapshot()).toMatchObject({ tag: "pokemon-detail", canGoBack: true });
+  });
+
+  it("replace swaps the top once navigation has landed", () => {
+    attachDomHost();
     stackNavigator.push("/todos");
-    expect(stackNavigator.getSnapshot().tag).toBe("home");
+    stackNavigator.replace("/pokemon/mew");
+    expect(stackNavigator.getSnapshot()).toMatchObject({
+      tag: "pokemon-detail",
+      depth: 2,
+      canGoBack: true,
+    });
+    // The replaced entry (todos) is gone: back lands on home.
+    stackNavigator.back();
+    expect(stackNavigator.getSnapshot()).toMatchObject({ tag: "home", depth: 1 });
+  });
+
+  it("replace to the showing route is a param-only refresh", () => {
+    attachDomHost();
+    stackNavigator.push("/pokemon/mew");
+    stackNavigator.replace("/pokemon/ditto");
+    expect(stackNavigator.getSnapshot()).toMatchObject({ tag: "pokemon-detail", depth: 2 });
+    expect(stackNavigator.paramsSnapshot("pokemon-detail")).toEqual({ id: "ditto" });
+  });
+
+  it("replace dedupes a target that already sits in the back stack", () => {
+    // Every tag appears at most once in the host stack (Adw treats a
+    // duplicate page as a programming error) — replacing to a page that's
+    // already beneath pops the stack to a single occurrence of it.
+    const adapter = attachDomHost();
+    stackNavigator.push("/todos");
+    stackNavigator.push("/pokemon/mew");
+    stackNavigator.replace("/todos");
+    expect(stackNavigator.getSnapshot()).toMatchObject({ tag: "todos", depth: 2 });
+    const model = adapter.get_navigation_stack();
+    expect(model.get_n_items()).toBe(2);
+    expect(model.get_item(0)?.get_tag()).toBe("home");
+    expect(model.get_item(1)?.get_tag()).toBe("todos");
+  });
+
+  it("ignores navigation to routes outside the manifest", () => {
+    const log = vi.spyOn(console, "log").mockImplementation(() => {});
     attachDomHost();
     stackNavigator.push("/not-in-manifest");
     expect(stackNavigator.getSnapshot().tag).toBe("home");
     log.mockRestore();
   });
 
+  // Warm/early deep links: navigation requests are QUEUED while no host is
+  // attached (mount ordering, StrictMode's detach→re-attach cycle, host
+  // remounts) and applied on attach — the same contract as react-navigation
+  // queueing actions dispatched before the navigator is ready. Dropping them
+  // is what made deep links no-op depending on arrival timing.
+  it("queues a deep link that arrives before a host attaches and applies it on attach", () => {
+    const log = vi.spyOn(console, "log").mockImplementation(() => {});
+    stackNavigator.push("/pokemon/mew");
+    // Nothing landed yet — no host.
+    expect(stackNavigator.getSnapshot()).toMatchObject({ tag: "home", depth: 1 });
+    attachDomHost();
+    expect(stackNavigator.getSnapshot()).toMatchObject({
+      tag: "pokemon-detail",
+      pathname: "/pokemon/mew",
+      depth: 2,
+      canGoBack: true,
+    });
+    expect(stackNavigator.paramsSnapshot("pokemon-detail")).toEqual({ id: "mew" });
+    log.mockRestore();
+  });
+
+  it("applies a deep link that arrives while the host is detached (remount cycle)", () => {
+    const log = vi.spyOn(console, "log").mockImplementation(() => {});
+    const adapter = attachDomHost();
+    stackNavigator.push("/todos");
+    stackNavigator.detach();
+    // Warm deep link lands in the detach window (e.g. StrictMode remount).
+    stackNavigator.push("/pokemon/mew");
+    expect(stackNavigator.getSnapshot()).toMatchObject({ tag: "todos", depth: 2 });
+    stackNavigator.attach(adapter);
+    expect(stackNavigator.getSnapshot()).toMatchObject({ tag: "pokemon-detail", depth: 3 });
+    log.mockRestore();
+  });
+
+  it("resolves a queued navigation's loader at apply time, not enqueue time", async () => {
+    const log = vi.spyOn(console, "log").mockImplementation(() => {});
+    const loader = vi.fn(() => Promise.resolve("fresh"));
+    stackNavigator.configure([
+      ROUTES[0]!,
+      { pattern: "/todos", tag: "todos", title: "Todos", loader },
+    ]);
+    stackNavigator.push("/todos");
+    // Queued — the loader must not run until a host can apply the result.
+    expect(loader).not.toHaveBeenCalled();
+    attachDomHost();
+    expect(loader).toHaveBeenCalledTimes(1);
+    await flush();
+    expect(stackNavigator.getSnapshot().tag).toBe("todos");
+    expect(stackNavigator.loaderSnapshot("todos")).toBe("fresh");
+    log.mockRestore();
+  });
+
+  it("applies the initial href before flushing queued deep links (freshest wins)", () => {
+    const log = vi.spyOn(console, "log").mockImplementation(() => {});
+    stackNavigator.push("/pokemon/mew");
+    const adapter = new DomStackAdapter("home", () => stackNavigator.syncFromHost());
+    stackNavigator.attach(adapter, { initialHref: "/todos" });
+    // Restore landed first ([home, todos]), then the queued deep link on top.
+    expect(stackNavigator.getSnapshot()).toMatchObject({ tag: "pokemon-detail", depth: 3 });
+    stackNavigator.back();
+    expect(stackNavigator.getSnapshot()).toMatchObject({ tag: "todos", depth: 2 });
+    log.mockRestore();
+  });
+
+  it("clears queued navigations on configure", () => {
+    const log = vi.spyOn(console, "log").mockImplementation(() => {});
+    stackNavigator.push("/todos");
+    stackNavigator.configure(ROUTES);
+    attachDomHost();
+    expect(stackNavigator.getSnapshot()).toMatchObject({ tag: "home", depth: 1 });
+    log.mockRestore();
+  });
+
   it("resolves loaders before the host action (loader bridge)", async () => {
     let resolveLoader: (value: string) => void = () => {};
     const loader = vi.fn(

package/src/seam/navigator.ts

@@ -28,6 +28,21 @@
 //     until written), read via useSyncExternalStore under the page's
 //     RouteTagContext. A backgrounded page keeps its last params — same
 //     behavior as One keeping a stack screen's route params alive.
+//   - Navigations that arrive while NO host is attached are QUEUED and
+//     flushed on attach() (react-navigation queues pre-ready actions the
+//     same way). The no-host window is real even on mounted trees: child
+//     effects run before the navigation host's attach effect, and StrictMode
+//     remounts open a detach→attach gap — deep links must survive both, not
+//     no-op based on arrival timing.
+//   - REPLACE swaps the top NAVIGATION ENTRY. The manifest root is a
+//     permanent shell, not a navigation entry: with nothing above the root
+//     there is nothing to discard, so replace lands the target ABOVE the
+//     root (like push). Cold deep links / initialHref restores therefore
+//     always leave a live back affordance — the same shape react-navigation/
+//     expo-router synthesize for deep links via the anchor/initial route,
+//     and Adw.NavigationView's replace on an empty view (which is a push).
+//     A tag appears at most once in the stack (Adw hard-errors on
+//     duplicates): replacing to a page already in the back stack pops to it.
 //
 // No host imports here: the adapter arrives duck-typed via attach(),
 // keeping this module loadable in any entry (single-screen entries pull
@@ -155,6 +170,9 @@ export class StackNavigator {
   /** Monotonic navigation sequence — a loader that resolves after a NEWER
    *  navigation started must not perform its (stale) host action. */
   private navSeq = 0;
+  /** Navigations that arrived while no host was attached — flushed FIFO on
+   *  attach() so deep links survive mount ordering and remount cycles. */
+  private pendingNavigations: Array<{ href: Href; mode: "push" | "replace" }> = [];
   private generation = 0;
   private snapshot: NavSnapshot = {
     pathname: "/",
@@ -173,6 +191,7 @@ export class StackNavigator {
     this.routes = defs.map(compileRoute);
     this.visitedTags = new Set();
     this.loaderDataByTag = new Map();
+    this.pendingNavigations = [];
     const root = defs[0];
     if (root) {
       this.stackTags = [root.tag];
@@ -194,6 +213,19 @@ export class StackNavigator {
     return this.loaderDataByTag.get(tag);
   }
 
+  /** Seed a restored route's params/pathname BEFORE the first React render
+   *  (no host action, no stack mutation). The navigation host applies
+   *  `initialHref` from its attach EFFECT, which runs after the root page's
+   *  content already rendered once — a restored route's query params would
+   *  miss any mount-time state seeding (e.g. a list initializing filters
+   *  from useLocalSearchParams). Hosts call this while lazily initializing,
+   *  when no subscribers exist yet, so the rebuild notifies nobody. */
+  seedInitialRoute(href: Href): void {
+    const hit = this.match(href);
+    if (!hit) return;
+    this.setRouteState(hit.route.tag, hit.pathname, hit.params);
+  }
+
   /** Resolve a route's loader WITHOUT navigating. For the initial page:
    *  entries can `await stackNavigator.preload("/")` during top-level await
    *  (where GJS reliably drains promise jobs) so even the root page's first
@@ -211,10 +243,18 @@ export class StackNavigator {
   }
 
   /** Bind the live host stack (an Adw.NavigationView widget on GTK, a
-   *  DomStackAdapter on DOM targets). */
-  attach(host: NavStackAdapter): void {
+   *  DomStackAdapter on DOM targets). `initialHref` (state restore) applies
+   *  as a replace BEFORE queued navigations flush: a deep link that arrived
+   *  while unattached is fresher intent than a persisted route, so it lands
+   *  on top. */
+  attach(host: NavStackAdapter, options?: { initialHref?: Href }): void {
     this.host = host;
     this.syncFromHost();
+    const initialHref = options?.initialHref;
+    if (initialHref !== undefined) this.replace(initialHref);
+    for (const { href, mode } of this.pendingNavigations.splice(0)) {
+      void this.navigate(href, mode);
+    }
   }
 
   detach(): void {
@@ -282,7 +322,12 @@ export class StackNavigator {
       return;
     }
     if (!this.host) {
-      console.log(`[stack nav] ${mode} ${hrefToString(href)} — no stack host attached, ignored`);
+      // No host YET — mount ordering (child effects run before the
+      // navigation host attaches) and remount cycles (StrictMode) both open
+      // this window. Queue and let attach() flush; loaders run at apply
+      // time so their data is fresh when the page actually shows.
+      this.pendingNavigations.push({ href, mode });
+      console.log(`[stack nav] ${mode} ${hrefToString(href)} — queued until a stack host attaches`);
       return;
     }
     const { route, pathname, params } = hit;
@@ -303,10 +348,23 @@ export class StackNavigator {
     this.visitedTags.add(route.tag);
     this.setRouteState(route.tag, pathname, params);
     if (mode === "replace") {
+      // Replace swaps the top NAVIGATION ENTRY (the layer above the
+      // permanent manifest root) — see the module design notes for the
+      // documented semantics + precedent.
       const top = this.stackTags[this.stackTags.length - 1];
-      if (top === route.tag) return;
-      const tags = [...this.stackTags.slice(0, -1), route.tag];
-      this.host.replace_with_tags(tags);
+      if (top === route.tag) return; // param-only refresh of the showing page
+      if (this.stackTags.length <= 1) {
+        // Fresh/empty stack: no navigation entry to discard — land above
+        // the root like a push so back affordances survive. replace (not
+        // push_by_tag) also materializes the root on a host whose real
+        // stack is still empty (GTK cold start).
+        this.host.replace_with_tags([...this.stackTags, route.tag]);
+        return;
+      }
+      // A tag may appear only once (Adw hard-errors on duplicates): drop an
+      // existing occurrence of the target from the back stack.
+      const below = this.stackTags.slice(0, -1).filter((tag) => tag !== route.tag);
+      this.host.replace_with_tags([...below, route.tag]);
       return;
     }
     const idx = this.stackTags.indexOf(route.tag);

package/types/seam/DomNavigationHost.d.ts

@@ -24,8 +24,9 @@ export interface DomRouteEntry extends RouteDef {
 export interface DomNavigationHostProps {
     routes: DomRouteEntry[];
     /** Restore a previous route on mount (e.g. from vscode.getState()) —
-     *  applied as a root replace, matching MemoryRouter initialEntries
-     *  semantics (no back stack to it). */
+     *  applied as a replace ABOVE the manifest root (see the replace
+     *  semantics in navigator.ts), so a restored detail page keeps a working
+     *  back affordance to the root instead of dead-ending. */
     initialHref?: Href;
     style?: CSSProperties;
 }

package/types/seam/DomNavigationHost.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DomNavigationHost.d.ts","sourceRoot":"","sources":["../../src/seam/DomNavigationHost.tsx"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEtD,OAAO,EAIL,KAAK,IAAI,EACT,KAAK,eAAe,EACpB,KAAK,QAAQ,EACd,MAAM,aAAa,CAAC;AAErB;;qBAEqB;AACrB,qBAAa,eAAgB,YAAW,eAAe;IACrD,OAAO,CAAC,KAAK,CAAW;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAa;gBAE3B,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,IAAI;IAKlD,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAK9B,GAAG,IAAI,OAAO;IAOd,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAQhC,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI;IAKvC,oBAAoB,IAAI;QACtB,WAAW,IAAI,MAAM,CAAC;QACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG;YAAE,OAAO,IAAI,MAAM,GAAG,IAAI,CAAA;SAAE,GAAG,IAAI,CAAC;KAC9D;CAQF;AAED,MAAM,WAAW,aAAc,SAAQ,QAAQ;IAC7C,OAAO,EAAE,SAAS,CAAC;CACpB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB;;2CAEuC;IACvC,WAAW,CAAC,EAAE,IAAI,CAAC;IACnB,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB;AAmDD,wBAAgB,iBAAiB,CAAC,EAChC,MAAM,EACN,WAAW,EACX,KAAK,GACN,EAAE,sBAAsB,GAAG,SAAS,CAsDpC"}
+{"version":3,"file":"DomNavigationHost.d.ts","sourceRoot":"","sources":["../../src/seam/DomNavigationHost.tsx"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEtD,OAAO,EAIL,KAAK,IAAI,EACT,KAAK,eAAe,EACpB,KAAK,QAAQ,EACd,MAAM,aAAa,CAAC;AAErB;;qBAEqB;AACrB,qBAAa,eAAgB,YAAW,eAAe;IACrD,OAAO,CAAC,KAAK,CAAW;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAa;gBAE3B,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,IAAI;IAKlD,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAK9B,GAAG,IAAI,OAAO;IAOd,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAQhC,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI;IAKvC,oBAAoB,IAAI;QACtB,WAAW,IAAI,MAAM,CAAC;QACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG;YAAE,OAAO,IAAI,MAAM,GAAG,IAAI,CAAA;SAAE,GAAG,IAAI,CAAC;KAC9D;CAQF;AAED,MAAM,WAAW,aAAc,SAAQ,QAAQ;IAC7C,OAAO,EAAE,SAAS,CAAC;CACpB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB;;;8DAG0D;IAC1D,WAAW,CAAC,EAAE,IAAI,CAAC;IACnB,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB;AAmDD,wBAAgB,iBAAiB,CAAC,EAChC,MAAM,EACN,WAAW,EACX,KAAK,GACN,EAAE,sBAAsB,GAAG,SAAS,CA8DpC"}

package/types/seam/navigator.d.ts

@@ -74,6 +74,9 @@ export declare class StackNavigator {
     /** Monotonic navigation sequence — a loader that resolves after a NEWER
      *  navigation started must not perform its (stale) host action. */
     private navSeq;
+    /** Navigations that arrived while no host was attached — flushed FIFO on
+     *  attach() so deep links survive mount ordering and remount cycles. */
+    private pendingNavigations;
     private generation;
     private snapshot;
     get isConfigured(): boolean;
@@ -84,14 +87,27 @@ export declare class StackNavigator {
     /** The route's last loader result (stable identity until the loader runs
      *  again). undefined when the route has no loader / hasn't resolved. */
     loaderSnapshot(tag: string | null): unknown;
+    /** Seed a restored route's params/pathname BEFORE the first React render
+     *  (no host action, no stack mutation). The navigation host applies
+     *  `initialHref` from its attach EFFECT, which runs after the root page's
+     *  content already rendered once — a restored route's query params would
+     *  miss any mount-time state seeding (e.g. a list initializing filters
+     *  from useLocalSearchParams). Hosts call this while lazily initializing,
+     *  when no subscribers exist yet, so the rebuild notifies nobody. */
+    seedInitialRoute(href: Href): void;
     /** Resolve a route's loader WITHOUT navigating. For the initial page:
      *  entries can `await stackNavigator.preload("/")` during top-level await
      *  (where GJS reliably drains promise jobs) so even the root page's first
      *  paint has loader data. */
     preload(href: Href): Promise<void>;
     /** Bind the live host stack (an Adw.NavigationView widget on GTK, a
-     *  DomStackAdapter on DOM targets). */
-    attach(host: NavStackAdapter): void;
+     *  DomStackAdapter on DOM targets). `initialHref` (state restore) applies
+     *  as a replace BEFORE queued navigations flush: a deep link that arrived
+     *  while unattached is fresher intent than a persisted route, so it lands
+     *  on top. */
+    attach(host: NavStackAdapter, options?: {
+        initialHref?: Href;
+    }): void;
     detach(): void;
     subscribe: (fn: () => void) => (() => void);
     getSnapshot: () => NavSnapshot;

package/types/seam/navigator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"navigator.d.ts","sourceRoot":"","sources":["../../src/seam/navigator.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"navigator.d.ts","sourceRoot":"","sources":["../../src/seam/navigator.ts"],"names":[],"mappings":"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"}