@multiplatform.one/router 6.1.0 → 6.3.0

package/dist/jsx/seam/oneAdapter.native.js

@@ -0,0 +1,141 @@
+"use strict";
+
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all) __defProp(target, name, {
+    get: all[name],
+    enumerable: true
+  });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from)) if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    });
+  }
+  return to;
+};
+var __toCommonJS = mod => __copyProps(__defProp({}, "__esModule", {
+  value: true
+}), mod);
+var oneAdapter_exports = {};
+__export(oneAdapter_exports, {
+  Link: () => Link,
+  LoadProgressBar: () => LoadProgressBar,
+  Slot: () => Slot,
+  getUserScheme: () => import_color_scheme.getUserScheme,
+  onUserSchemeChange: () => import_color_scheme.onUserSchemeChange,
+  setUserScheme: () => import_color_scheme.setUserScheme,
+  useBlocker: () => useBlocker,
+  useLoader: () => useLoader,
+  useLocalSearchParams: () => useLocalSearchParams,
+  useMatches: () => useMatches,
+  useParams: () => useParams,
+  usePathname: () => usePathname,
+  useRouter: () => useRouter,
+  useUserScheme: () => import_color_scheme.useUserScheme
+});
+module.exports = __toCommonJS(oneAdapter_exports);
+var import_jsx_runtime = require("react/jsx-runtime");
+var import_react = require("react");
+var import_navigator = require("./navigator.native.js");
+var import_color_scheme = require("@vxrn/color-scheme");
+function useLoader(_loader) {
+  var tag = (0, import_react.useContext)(import_navigator.RouteTagContext);
+  var fromRoute = (0, import_react.useSyncExternalStore)(import_navigator.stackNavigator.subscribe, function () {
+    return import_navigator.stackNavigator.loaderSnapshot(tag);
+  });
+  return fromRoute;
+}
+var ROUTER = {
+  push: import_navigator.stackNavigator.push,
+  navigate: import_navigator.stackNavigator.push,
+  replace: import_navigator.stackNavigator.replace,
+  back: import_navigator.stackNavigator.back,
+  canGoBack: function canGoBack() {
+    return import_navigator.stackNavigator.getSnapshot().canGoBack;
+  },
+  dismiss: function dismiss(count) {
+    for (var i = 0; i < (count !== null && count !== void 0 ? count : 1); i++) import_navigator.stackNavigator.back();
+  },
+  dismissAll: function dismissAll() {
+    var depth = import_navigator.stackNavigator.getSnapshot().depth;
+    for (var i = 1; i < depth; i++) import_navigator.stackNavigator.back();
+  },
+  canDismiss: function canDismiss() {
+    return import_navigator.stackNavigator.getSnapshot().canGoBack;
+  },
+  setParams: import_navigator.stackNavigator.setParams,
+  subscribe: function subscribe(listener) {
+    listener("success");
+    return function () {};
+  },
+  onLoadState: function onLoadState(listener) {
+    listener("loaded");
+    return function () {};
+  }
+};
+function useRouter() {
+  return ROUTER;
+}
+function Link(param) {
+  var {
+    href,
+    replace,
+    children,
+    style,
+    ...rest
+  } = param;
+  if (!href || !import_navigator.stackNavigator.isConfigured) return children !== null && children !== void 0 ? children : null;
+  var hrefString = (0, import_navigator.hrefToString)(href);
+  var onClick = function onClick2(event) {
+    event.preventDefault();
+    if (replace) import_navigator.stackNavigator.replace(href);else import_navigator.stackNavigator.push(href);
+  };
+  return /* @__PURE__ */(0, import_jsx_runtime.jsx)("a", {
+    href: hrefString,
+    onClick,
+    // display:contents — the anchor contributes no box, so wrapping
+    // arbitrary flex/grid children never disturbs layout (clicks still
+    // bubble through it).
+    style: {
+      display: "contents",
+      color: "inherit",
+      textDecoration: "none",
+      ...style
+    },
+    "data-seam-link": hrefString,
+    ...rest,
+    children
+  });
+}
+function Slot(_props) {
+  return null;
+}
+function useParams() {
+  return (0, import_navigator.useRouteParams)();
+}
+function useLocalSearchParams() {
+  return (0, import_navigator.useRouteParams)();
+}
+function usePathname() {
+  return (0, import_navigator.useNavState)().pathname;
+}
+function useBlocker(_shouldBlock) {
+  return {
+    state: "unblocked",
+    proceed: function proceed() {},
+    reset: function reset() {}
+  };
+}
+function LoadProgressBar(_props) {
+  return null;
+}
+function useMatches() {
+  return [];
+}
+//# sourceMappingURL=oneAdapter.native.js.map

package/dist/jsx/seam/oneAdapter.native.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["__defProp","Object","defineProperty","__getOwnPropDesc","getOwnPropertyDescriptor","__getOwnPropNames","getOwnPropertyNames","__hasOwnProp","prototype","hasOwnProperty","__export","target","all","name","get","enumerable","__copyProps","to","from","except","desc","key","call","__toCommonJS","mod","value","oneAdapter_exports","Link","LoadProgressBar","Slot","getUserScheme","import_color_scheme","onUserSchemeChange","setUserScheme","useBlocker","useLoader","useLocalSearchParams","useMatches","useParams","usePathname","useRouter","useUserScheme","module","exports","import_jsx_runtime","require","import_react","import_navigator","_loader","tag","useContext","RouteTagContext","fromRoute","useSyncExternalStore","stackNavigator","subscribe","loaderSnapshot","ROUTER","push","navigate","replace","back","canGoBack","getSnapshot","dismiss","count","i","dismissAll","depth","canDismiss","setParams","listener","onLoadState","param","href","children","style","rest","isConfigured","hrefString","hrefToString","onClick","onClick2","event","preventDefault","jsx"],"sources":["../../../src/seam/oneAdapter.tsx"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multiplatform.one/router",
-  "version": "6.1.0",
+  "version": "6.3.0",
   "description": "multiplatform.one router with support for react-router-dom and react-navigation",
   "keywords": [
     "react",
@@ -15,13 +15,15 @@
   "author": "BitSpur <support@risserlabs.com> (https://risserlabs.com)",
   "repository": {
     "type": "git",
-    "url": "https://gitlab.com/bitspur/multiplatform.one/multiplatform.one"
+    "url": "git+https://gitlab.com/bitspur/frappe/multiplatform.one.git",
+    "directory": "public/router"
   },
   "source": "src/index.ts",
   "files": [
     "dist",
     "src",
-    "types"
+    "types",
+    "!types/.tsbuildinfo"
   ],
   "sideEffects": false,
   "main": "src/index.ts",
@@ -31,21 +33,35 @@
     "./package.json": "./package.json",
     ".": {
       "react-native": {
+        "types": "./types/index.d.ts",
         "import": "./dist/esm/index.native.js",
         "require": "./dist/cjs/index.native.js"
       },
       "source": "./src/index.ts",
       "types": "./types/index.d.ts",
-      "import": "./dist/esm/index.js",
-      "require": "./dist/cjs/index.js",
+      "import": "./dist/esm/index.mjs",
+      "require": "./dist/cjs/index.cjs",
       "default": "./dist/cjs/index.native.js"
+    },
+    "./seam": {
+      "react-native": {
+        "types": "./types/seam/index.d.ts",
+        "import": "./dist/esm/seam/index.native.js",
+        "require": "./dist/cjs/seam/index.native.js"
+      },
+      "source": "./src/seam/index.ts",
+      "types": "./types/seam/index.d.ts",
+      "import": "./dist/esm/seam/index.mjs",
+      "require": "./dist/cjs/seam/index.cjs",
+      "default": "./dist/cjs/seam/index.native.js"
     }
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@multiplatform.one/platform": "6.1.0"
+    "@vxrn/color-scheme": "^1.16.5",
+    "@multiplatform.one/platform": "6.3.0"
   },
   "devDependencies": {
     "@react-navigation/native": "^7.2.2",
@@ -60,10 +76,11 @@
     "typescript": "~5.9.3",
     "vite": "^8.0.10",
     "vitest": "^4.1.5",
-    "@multiplatform.one/test-utils": "6.1.0",
-    "@multiplatform.one/config": "6.1.0"
+    "@multiplatform.one/config": "6.3.0",
+    "@multiplatform.one/test-utils": "6.3.0"
   },
   "peerDependencies": {
+    "@react-navigation/native": "~7.2.2",
     "one": "^1.4.10",
     "react": "^19.1.0",
     "react-router-dom": "^7.0.0"
@@ -73,7 +90,7 @@
   },
   "module:jsx": "dist/jsx",
   "scripts": {
-    "build": "rm -rf dist types 2>/dev/null && tamagui-build --ts-project ./tsconfig.build.json",
+    "build": "rm -rf dist types 2>/dev/null && tamagui-build --ts-project ./tsconfig.build.json --exclude '\\.spec\\.|\\.test\\.|\\.stories\\.'",
     "test": "vitest run --coverage --coverage.provider=v8 --coverage.reporter=text --coverage.reporter=lcov --coverage.reporter=html",
     "typecheck": "tsc --noEmit"
   }

package/src/hooks/urlStateEdges.spec.ts

@@ -0,0 +1,98 @@
+/**
+ * URL-state edge contracts not covered by useUrlState.spec.ts:
+ * `useShareableUrl` (share-link building from current params) and the
+ * defensive deserialize branches of `useUrlState` (malformed JSON falls back
+ * to defaults, scalar→array coercion for array-typed defaults).
+ */
+
+import { renderHook } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import * as router from "../router";
+import { useShareableUrl, useUrlState } from "./useUrlState";
+
+vi.mock("../router", () => ({
+  useParams: vi.fn(() => ({})),
+  useRouter: vi.fn(() => ({ setParams: vi.fn() })),
+}));
+
+const mockUseParams = router.useParams as unknown as ReturnType<typeof vi.fn>;
+const mockUseRouter = router.useRouter as unknown as ReturnType<typeof vi.fn>;
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  mockUseParams.mockReturnValue({});
+  mockUseRouter.mockReturnValue({ setParams: vi.fn() });
+});
+
+describe("useShareableUrl", () => {
+  it("builds an absolute URL carrying the current params as query string", () => {
+    mockUseParams.mockReturnValue({ tab: "settings", page: "2" });
+    const { result } = renderHook(() => useShareableUrl());
+    const url = new URL(result.current);
+    expect(url.origin).toBe(new URL(window.location.href).origin);
+    expect(url.searchParams.get("tab")).toBe("settings");
+    expect(url.searchParams.get("page")).toBe("2");
+  });
+
+  it("repeats array params as multiple query entries", () => {
+    mockUseParams.mockReturnValue({ tags: ["a", "b"] });
+    const { result } = renderHook(() => useShareableUrl());
+    const url = new URL(result.current);
+    expect(url.searchParams.getAll("tags")).toEqual(["a", "b"]);
+  });
+
+  it("drops empty and undefined params from the shared link", () => {
+    mockUseParams.mockReturnValue({ keep: "yes", empty: "", missing: undefined });
+    const { result } = renderHook(() => useShareableUrl());
+    const url = new URL(result.current);
+    expect(url.searchParams.get("keep")).toBe("yes");
+    expect(url.searchParams.has("empty")).toBe(false);
+    expect(url.searchParams.has("missing")).toBe(false);
+  });
+
+  it("replaces any existing location query instead of appending to it", () => {
+    mockUseParams.mockReturnValue({ only: "param" });
+    const { result } = renderHook(() => useShareableUrl());
+    const url = new URL(result.current);
+    expect([...url.searchParams.keys()]).toEqual(["only"]);
+  });
+
+  it("falls back to the bare URL when the router host throws", () => {
+    mockUseParams.mockImplementation(() => {
+      throw new Error("no router context");
+    });
+    const { result } = renderHook(() => useShareableUrl());
+    const url = new URL(result.current);
+    expect([...url.searchParams.keys()]).toEqual([]);
+  });
+});
+
+describe("useUrlState deserialize edge cases", () => {
+  it("falls back to the default when an object param carries malformed JSON", () => {
+    mockUseParams.mockReturnValue({ config: "{not-json" });
+    const defaults = { config: { theme: "light" } };
+    const { result } = renderHook(() => useUrlState(defaults));
+    expect(result.current[0]).toEqual({ config: { theme: "light" } });
+  });
+
+  it("coerces a single string into an array for array-typed defaults", () => {
+    mockUseParams.mockReturnValue({ tags: "solo" });
+    const defaults = { tags: [] as string[] };
+    const { result } = renderHook(() => useUrlState(defaults));
+    expect(result.current[0]).toEqual({ tags: ["solo"] });
+  });
+
+  it("parses 'false' strings into boolean false for boolean defaults", () => {
+    mockUseParams.mockReturnValue({ active: "false" });
+    const defaults = { active: true };
+    const { result } = renderHook(() => useUrlState(defaults));
+    expect(result.current[0]).toEqual({ active: false });
+  });
+
+  it("ignores params that have no matching default key", () => {
+    mockUseParams.mockReturnValue({ unknown: "x", name: "known" });
+    const defaults = { name: "" };
+    const { result } = renderHook(() => useUrlState(defaults));
+    expect(result.current[0]).toEqual({ name: "known" });
+  });
+});

package/src/hooks/useUrlState.ts

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useMemo, useRef } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { isWeb } from "@multiplatform.one/platform";
 import { useParams, useRouter } from "../router";
 
@@ -9,6 +9,27 @@ export interface SetSearchParamsOptions {
   debounceMs?: number;
 }
 
+// The router is optional. Hosts that have none (storybook-expo, expo go) resolve these
+// bindings to undefined, so treat a missing or throwing router as "no url sync" instead
+// of crashing at mount. The branch is decided once at module load, so hook order is stable.
+const hasRouter = typeof useRouter === "function" && typeof useParams === "function";
+
+const emptyParams: SearchParams = {};
+
+interface OptionalRouter {
+  router?: ReturnType<typeof useRouter>;
+  params?: SearchParams;
+}
+
+function useOptionalRouter(): OptionalRouter {
+  if (!hasRouter) return {};
+  try {
+    return { router: useRouter(), params: useParams() as SearchParams };
+  } catch {
+    return {};
+  }
+}
+
 /**
  * Cross-platform hook for managing URL search parameters
  * Works with both React Router (web) and React Navigation (native)
@@ -20,8 +41,9 @@ export function useSearchParams(): [
     options?: SetSearchParamsOptions,
   ) => void,
 ] {
-  const router = useRouter();
-  const currentParams = useParams();
+  const [localParams, setLocalParams] = useState<SearchParams>({});
+  const { router, params } = useOptionalRouter();
+  const currentParams = params ?? localParams;
   const debounceTimerRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
 
   // Parse current params into a more usable format
@@ -53,8 +75,12 @@ export function useSearchParams(): [
           }
         });
 
-        // Use router.setParams to update the URL
-        router.setParams(cleanParams as any);
+        // Use router.setParams to update the URL, or keep it local when routerless
+        if (router && params) {
+          router.setParams(cleanParams as any);
+        } else {
+          setLocalParams(cleanParams);
+        }
       };
 
       if (debounceMs > 0) {
@@ -66,7 +92,7 @@ export function useSearchParams(): [
         updateParams();
       }
     },
-    [router, searchParams],
+    [router, params, searchParams],
   );
 
   // Cleanup debounce timer on unmount
@@ -172,7 +198,7 @@ export function useUrlState<T extends Record<string, any>>(
  * Hook for creating shareable URLs with current state
  */
 export function useShareableUrl(): string {
-  const params = useParams();
+  const params = useOptionalRouter().params ?? emptyParams;
 
   const shareableUrl = useMemo(() => {
     if (!isWeb || typeof window === "undefined") {
@@ -207,7 +233,7 @@ export function useTypedSearchParams<T extends Record<string, any>>(schema: {
     parse?: (value: string | string[] | undefined) => T[K];
   };
 }): T {
-  const params = useParams();
+  const params = useOptionalRouter().params ?? emptyParams;
 
   const typedParams = useMemo(() => {
     const result: any = {};

package/src/seam/DomNavigationHost.spec.tsx

@@ -0,0 +1,78 @@
+import { act, render, screen } from "@testing-library/react";
+import { beforeEach, describe, expect, it } from "vitest";
+import { DomNavigationHost } from "./DomNavigationHost";
+import { stackNavigator } from "./navigator";
+import { useParams } from "./oneAdapter";
+
+const ROUTES = [
+  { pattern: "/", tag: "home", title: "Home" },
+  { pattern: "/todos", tag: "todos", title: "Todos" },
+  { pattern: "/pokemon/[id]", tag: "pokemon-detail", title: "Detail" },
+];
+
+function DetailProbe() {
+  const params = useParams();
+  return <span data-testid="detail-params">{String(params.id ?? "")}</span>;
+}
+
+function renderHost(initialHref?: string) {
+  stackNavigator.detach();
+  stackNavigator.configure(ROUTES);
+  return render(
+    <DomNavigationHost
+      initialHref={initialHref}
+      routes={[
+        { ...ROUTES[0]!, element: <div data-testid="home-screen" /> },
+        { ...ROUTES[1]!, element: <div data-testid="todos-screen" /> },
+        { ...ROUTES[2]!, element: <DetailProbe /> },
+      ]}
+    />,
+  );
+}
+
+function pageByTag(container: HTMLElement, tag: string): HTMLElement {
+  const page = container.querySelector(`[data-seam-page="${tag}"]`);
+  expect(page).not.toBeNull();
+  return page as HTMLElement;
+}
+
+describe("DomNavigationHost", () => {
+  beforeEach(() => {
+    stackNavigator.detach();
+  });
+
+  it("mounts content lazily and keeps backgrounded pages mounted", () => {
+    const { container } = renderHost();
+    expect(screen.getByTestId("home-screen")).toBeTruthy();
+    // Unvisited pages are bare shells.
+    expect(screen.queryByTestId("todos-screen")).toBeNull();
+    expect(pageByTag(container, "home").dataset.seamActive).toBe("true");
+
+    act(() => stackNavigator.push("/todos"));
+    expect(screen.getByTestId("todos-screen")).toBeTruthy();
+    expect(pageByTag(container, "todos").dataset.seamActive).toBe("true");
+    expect(pageByTag(container, "home").dataset.seamActive).toBe("false");
+    // Backgrounded page keeps its content mounted (One stack semantics).
+    expect(screen.getByTestId("home-screen")).toBeTruthy();
+
+    act(() => stackNavigator.back());
+    expect(pageByTag(container, "home").dataset.seamActive).toBe("true");
+    expect(screen.getByTestId("todos-screen")).toBeTruthy();
+  });
+
+  it("provides per-page params through RouteTagContext", () => {
+    renderHost();
+    act(() => stackNavigator.push("/pokemon/mew"));
+    expect(screen.getByTestId("detail-params").textContent).toBe("mew");
+  });
+
+  it("restores an initial route as a root replace", () => {
+    const { container } = renderHost("/todos");
+    expect(pageByTag(container, "todos").dataset.seamActive).toBe("true");
+    expect(stackNavigator.getSnapshot()).toMatchObject({
+      tag: "todos",
+      depth: 1,
+      canGoBack: false,
+    });
+  });
+});

package/src/seam/DomNavigationHost.tsx

@@ -0,0 +1,150 @@
+// DOM navigation host — renders the route manifest as a stack of DOM
+// pages, one per route, driving the same seam the GTK host drives.
+//
+// The DOM equivalent of apps/one/gnome/navigation-host.tsx: every route
+// gets a permanent page wrapper (so the host stack and the seam mirror
+// stay aligned), the page's React CONTENT mounts on the route's first
+// visit (stackNavigator.isVisited) and stays mounted from then on —
+// backgrounded pages keep their state, the same lifecycle One gives stack
+// screens on web/native. Only the top-of-stack page is visible; the rest
+// are display:none.
+//
+// Usage (mirrors the GTK entries):
+//
+//   stackNavigator.configure(ROUTES);            // before render
+//   <DomNavigationHost
+//     routes={ROUTES.map((r) => ({ ...r, element: <Screen /> }))}
+//     initialHref={restoredRoute}                // optional state restore
+//   />
+//
+// Stack state flows host → seam: every adapter mutation calls
+// stackNavigator.syncFromHost(), exactly like the GTK pushed/popped/
+// replaced signal handlers.
+
+import type { CSSProperties, ReactNode } from "react";
+import { Suspense, useEffect, useRef } from "react";
+import {
+  RouteTagContext,
+  stackNavigator,
+  useNavState,
+  type Href,
+  type NavStackAdapter,
+  type RouteDef,
+} from "./navigator";
+
+/** In-memory implementation of the host-stack protocol (the seam's
+ *  NavStackAdapter mirrors Adw.NavigationView's method surface — see
+ *  navigator.ts). */
+export class DomStackAdapter implements NavStackAdapter {
+  private stack: string[];
+  private readonly onChanged: () => void;
+
+  constructor(rootTag: string, onChanged: () => void) {
+    this.stack = rootTag ? [rootTag] : [];
+    this.onChanged = onChanged;
+  }
+
+  push_by_tag(tag: string): void {
+    this.stack.push(tag);
+    this.onChanged();
+  }
+
+  pop(): boolean {
+    if (this.stack.length <= 1) return false;
+    this.stack.pop();
+    this.onChanged();
+    return true;
+  }
+
+  pop_to_tag(tag: string): boolean {
+    const idx = this.stack.lastIndexOf(tag);
+    if (idx === -1 || idx === this.stack.length - 1) return false;
+    this.stack = this.stack.slice(0, idx + 1);
+    this.onChanged();
+    return true;
+  }
+
+  replace_with_tags(tags: string[]): void {
+    this.stack = [...tags];
+    this.onChanged();
+  }
+
+  get_navigation_stack(): {
+    get_n_items(): number;
+    get_item(index: number): { get_tag(): string | null } | null;
+  } {
+    const snapshot = this.stack;
+    return {
+      get_n_items: () => snapshot.length,
+      get_item: (index: number) =>
+        index >= 0 && index < snapshot.length ? { get_tag: () => snapshot[index] ?? null } : null,
+    };
+  }
+}
+
+export interface DomRouteEntry extends RouteDef {
+  element: ReactNode;
+}
+
+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). */
+  initialHref?: Href;
+  style?: CSSProperties;
+}
+
+const PAGE_STYLE: CSSProperties = {
+  position: "absolute",
+  inset: 0,
+  display: "flex",
+  flexDirection: "column",
+  overflow: "auto",
+};
+
+export function DomNavigationHost({
+  routes,
+  initialHref,
+  style,
+}: DomNavigationHostProps): ReactNode {
+  const adapterRef = useRef<DomStackAdapter | null>(null);
+  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);
+
+  useEffect(() => {
+    const adapter = adapterRef.current;
+    if (!adapter) return;
+    stackNavigator.attach(adapter);
+    const restore = initialHrefRef.current;
+    if (restore) stackNavigator.replace(restore);
+    return () => stackNavigator.detach();
+  }, []);
+
+  const nav = useNavState();
+
+  return (
+    <div style={{ position: "relative", flex: 1, minHeight: 0, height: "100%", ...style }}>
+      {routes.map((route) => {
+        const active = nav.tag === route.tag;
+        const mounted = stackNavigator.isVisited(route.tag);
+        return (
+          <div
+            key={route.tag}
+            data-seam-page={route.tag}
+            data-seam-active={active ? "true" : "false"}
+            style={{ ...PAGE_STYLE, display: active ? "flex" : "none" }}
+          >
+            <RouteTagContext.Provider value={route.tag}>
+              <Suspense fallback={null}>{mounted ? route.element : null}</Suspense>
+            </RouteTagContext.Provider>
+          </div>
+        );
+      })}
+    </div>
+  );
+}