@multiplatform.one/core 7.10.0 → 7.15.0

package/README.md

@@ -52,6 +52,31 @@ Pass `true` to a provider slot to read all settings from env config, or an
 object (`TanstackConfig`, `KeycloakConfig`, `FrappeConfig`, `Web3AppConfig`)
 to configure explicitly. Disabled slots add zero bundle weight.
 
+### Frappe catch-up and the `live` app
+
+After a reconnect, focus or `online`, the Frappe provider catches up on what it
+missed. The default, CDC, calls `live.live.api.backfill`, which exists only
+when the bench carries the `live` Frappe app (`apps/frappe/apps/live`). A bench
+without it answers 417 ("App live is not installed") on every catch-up.
+
+Such a deployment sets `FRAPPE_CATCH_UP_STRATEGY=snapshot` in the web
+container's environment. Catch-up then re-reads each mounted collection through
+`/api/resource` and makes no `live.*` request, for signed-in users and visitors
+alike. The key is public config, so the SSR document publishes it per request:
+one image serves a bench with `live` and one without, no rebuild. Unset, or
+`cdc`, keeps CDC. Writes through the SDK (`createDoc`, `updateDoc`,
+`deleteDoc`) still call `live`, so this makes a bench without it work for
+reads, not writes. Snapshot mode also refuses progressive subscriptions, so a
+screen built on `useFrappeInfiniteList` fails under it.
+
+An app can fix the choice in code instead, through `frappe.syncOptions`, which
+`createApp` hands to `FrappeProvider` as is. A `catchUpStrategy` set there wins
+over the env.
+
+```tsx
+createApp({ frappe: { syncOptions: { catchUpStrategy: "snapshot" } } });
+```
+
 ## License
 
 Apache-2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multiplatform.one/core",
-  "version": "7.10.0",
+  "version": "7.15.0",
   "description": "Core framework shell, provider composition, and layout factories for multiplatform.one",
   "keywords": [
     "app",
@@ -11,7 +11,7 @@
   "author": "BitSpur",
   "repository": {
     "type": "git",
-    "url": "git+https://gitlab.com/bitspur/frappe/multiplatform.one.git",
+    "url": "git+https://git.corp.bitspur.com/multiplatform.one/mpo.git",
     "directory": "public/core"
   },
   "source": "src/index.ts",
@@ -41,19 +41,21 @@
     "access": "public"
   },
   "dependencies": {
+    "@multiplatform.one/i18n": "7.15.0",
+    "@multiplatform.one/logger": "7.15.0",
+    "@multiplatform.one/platform": "7.15.0",
+    "@multiplatform.one/store": "7.15.0",
+    "@multiplatform.one/theme": "7.15.0",
     "@tanstack/devtools-event-client": "^0.4.3",
     "@tanstack/devtools-utils": "^0.4.0",
     "@tanstack/pacer-devtools": "1.3.0",
     "@tanstack/react-devtools": "^0.10.2",
     "@tanstack/react-form-devtools": "0.2.22",
-    "react-cookie": "^8.1.2",
-    "@multiplatform.one/i18n": "7.10.0",
-    "@multiplatform.one/theme": "7.10.0",
-    "@multiplatform.one/store": "7.10.0",
-    "@multiplatform.one/platform": "7.10.0",
-    "@multiplatform.one/logger": "7.10.0"
+    "react-cookie": "^8.1.2"
   },
   "devDependencies": {
+    "@multiplatform.one/frappe": "7.15.0",
+    "@multiplatform.one/web3": "7.15.0",
     "@sentry/react": "^10.51.0",
     "@tanstack/react-query": "^5.100.7",
     "@tanstack/react-query-devtools": "^5.100.7",
@@ -67,11 +69,13 @@
     "react-native-safe-area-context": "~5.7.0",
     "tamagui": "2.7.6",
     "typescript": "~5.9.3",
-    "vitest": "^4.1.5",
-    "@multiplatform.one/frappe": "7.10.0",
-    "@multiplatform.one/web3": "7.10.0"
+    "vitest": "^4.1.5"
   },
   "peerDependencies": {
+    "@multiplatform.one/frappe": "^7.15.0",
+    "@multiplatform.one/frappe-ui": "^7.15.0",
+    "@multiplatform.one/keycloak": "^7.15.0",
+    "@multiplatform.one/web3": "^7.15.0",
     "@sentry/react": "^9.0.0",
     "@tanstack/react-query": "^5.0.0",
     "@tanstack/react-query-devtools": "^5.0.0",
@@ -84,11 +88,7 @@
     "react-native": ">=0.83.0",
     "react-native-gesture-handler": ">=2.0.0",
     "react-native-safe-area-context": ">=4.0.0",
-    "tamagui": "^2.0.0-rc",
-    "@multiplatform.one/frappe": "^7.10.0",
-    "@multiplatform.one/frappe-ui": "^7.10.0",
-    "@multiplatform.one/web3": "^7.10.0",
-    "@multiplatform.one/keycloak": "^7.10.0"
+    "tamagui": "^2.0.0-rc"
   },
   "peerDependenciesMeta": {
     "@multiplatform.one/web3": {

package/src/app/CreateApp.frappe.spec.tsx

@@ -0,0 +1,109 @@
+import { renderToStaticMarkup } from "react-dom/server";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { ReactNode } from "react";
+import type { SyncOptions } from "@multiplatform.one/frappe";
+import type { FrappeNavigation } from "@multiplatform.one/frappe-ui";
+import { createApp, type FrappeConfig } from "./CreateApp";
+
+const { env, provided, router } = vi.hoisted(() => ({
+  env: {} as Record<string, string | undefined>,
+  provided: { navigation: undefined as FrappeNavigation | undefined },
+  router: { pushed: [] as string[], pathname: "/moves/a1b2c3" },
+}));
+
+vi.mock("@multiplatform.one/platform", () => ({
+  config: { get: (key: string) => env[key] },
+  isDev: false,
+  isWeb: true,
+}));
+vi.mock("one", () => ({
+  usePathname: () => router.pathname,
+  useRouter: () => ({ push: (href: string) => router.pushed.push(href) }),
+}));
+vi.mock("@multiplatform.one/theme", () => ({
+  ThemeProvider: ({ children }: { children: ReactNode }) => children,
+}));
+vi.mock("@multiplatform.one/frappe-ui", () => ({
+  FrappeProvider: ({
+    children,
+    syncOptions,
+    navigation,
+  }: {
+    children: ReactNode;
+    syncOptions?: SyncOptions;
+    navigation?: FrappeNavigation;
+  }) => {
+    provided.navigation = navigation;
+    return (
+      <>
+        <output>{JSON.stringify(syncOptions ?? null)}</output>
+        {children}
+      </>
+    );
+  },
+}));
+vi.mock("./TanstackProvider", () => ({ createTanstackProvider: vi.fn() }));
+vi.mock("./loadWalletProvider", () => ({ default: () => null }));
+
+function renderedSyncOptions(frappe: FrappeConfig = {}) {
+  const { AppProvider } = createApp({
+    frappe: { enabled: true, baseURL: "https://bench.test", ...frappe },
+  });
+  const html = renderToStaticMarkup(<AppProvider />);
+  const json = html.match(/<output>(.*)<\/output>/)?.[1].replace(/&quot;/g, '"');
+  return json === undefined ? undefined : JSON.parse(json);
+}
+
+afterEach(() => {
+  for (const key of Object.keys(env)) delete env[key];
+});
+
+describe("createApp frappe sync options (MPO-324)", () => {
+  it("hands the provider snapshot catch-up when FRAPPE_CATCH_UP_STRATEGY=snapshot", () => {
+    env.FRAPPE_CATCH_UP_STRATEGY = "snapshot";
+    expect(renderedSyncOptions()).toEqual({ catchUpStrategy: "snapshot" });
+  });
+
+  it("reads the strategy when the provider renders, not when the app is created", () => {
+    const { AppProvider } = createApp({ frappe: { enabled: true, baseURL: "https://bench.test" } });
+    env.FRAPPE_CATCH_UP_STRATEGY = "snapshot";
+    expect(renderToStaticMarkup(<AppProvider />)).toContain(
+      "{&quot;catchUpStrategy&quot;:&quot;snapshot&quot;}",
+    );
+  });
+
+  it("leaves CDC as the default when the env is unset or names no strategy", () => {
+    expect(renderedSyncOptions()).toBeNull();
+    env.FRAPPE_CATCH_UP_STRATEGY = "live";
+    expect(renderedSyncOptions()).toBeNull();
+  });
+
+  it("passes the app's own sync options through and adds the env strategy to them", () => {
+    expect(renderedSyncOptions({ syncOptions: { cdcInterval: 30000 } })).toEqual({
+      cdcInterval: 30000,
+    });
+    env.FRAPPE_CATCH_UP_STRATEGY = "snapshot";
+    expect(renderedSyncOptions({ syncOptions: { cdcInterval: 30000 } })).toEqual({
+      cdcInterval: 30000,
+      catchUpStrategy: "snapshot",
+    });
+  });
+
+  it("lets a catchUpStrategy the app sets win over the env", () => {
+    env.FRAPPE_CATCH_UP_STRATEGY = "snapshot";
+    expect(renderedSyncOptions({ syncOptions: { catchUpStrategy: "cdc" } })).toEqual({
+      catchUpStrategy: "cdc",
+    });
+  });
+});
+
+describe("createApp frappe navigation (MPO-333)", () => {
+  it("hands the provider One's router for routed FrappeListView and FrappeForm", () => {
+    renderedSyncOptions();
+    const navigation = provided.navigation;
+    expect(navigation).toBeDefined();
+    expect(navigation?.usePathname()).toBe("/moves/a1b2c3");
+    navigation?.useNavigate()("/moves/a1b2c3/edit");
+    expect(router.pushed).toEqual(["/moves/a1b2c3/edit"]);
+  });
+});

package/src/app/CreateApp.origin.spec.tsx

@@ -0,0 +1,182 @@
+/**
+ * Where createApp's FrappeProvider dials, per page kind (MPO-328).
+ *
+ * One renders SPA-mode pages (`/`, `/backoffice/*`) to static HTML at build
+ * time, so their runtime config payload holds the build's `.env` values, not
+ * the container's BASE_URL. Live on https://pokemon.bitspur.com that sent the
+ * backoffice Desk to http://pokemon.bitspur.com:8000 and realtime to :9000,
+ * while the server-rendered /pokemon, which carries the runtime BASE_URL,
+ * reached its own origin.
+ */
+import { renderToStaticMarkup } from "react-dom/server";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { ReactNode } from "react";
+import { createApp, followPageOriginForLoopback } from "./CreateApp";
+
+const { env, mode } = vi.hoisted(() => ({
+  env: {} as Record<string, string | undefined>,
+  mode: { dev: false },
+}));
+
+vi.mock("@multiplatform.one/platform", () => ({
+  config: { get: (key: string) => env[key] },
+  get isDev() {
+    return mode.dev;
+  },
+  isWeb: true,
+}));
+vi.mock("one", () => ({ usePathname: () => "/", useRouter: () => ({ push: () => undefined }) }));
+vi.mock("@multiplatform.one/theme", () => ({
+  ThemeProvider: ({ children }: { children: ReactNode }) => children,
+}));
+vi.mock("@multiplatform.one/frappe-ui", () => ({
+  FrappeProvider: ({
+    children,
+    baseURL,
+    socketPort,
+  }: {
+    children: ReactNode;
+    baseURL?: string;
+    socketPort?: number;
+  }) => (
+    <>
+      <output>{JSON.stringify({ baseURL, socketPort: socketPort ?? null })}</output>
+      {children}
+    </>
+  ),
+}));
+vi.mock("./TanstackProvider", () => ({ createTanstackProvider: vi.fn() }));
+vi.mock("./loadWalletProvider", () => ({ default: () => null }));
+
+function openPage(href: string) {
+  vi.stubGlobal("window", { location: new URL(href) });
+}
+
+function connection(): { baseURL?: string; socketPort: number | null } {
+  const { AppProvider } = createApp({ frappe: { enabled: true } });
+  const html = renderToStaticMarkup(<AppProvider />);
+  const json = html.match(/<output>(.*)<\/output>/)?.[1].replace(/&quot;/g, '"');
+  if (json === undefined) throw new Error("FrappeProvider did not render");
+  return JSON.parse(json);
+}
+
+afterEach(() => {
+  for (const key of Object.keys(env)) delete env[key];
+  mode.dev = false;
+  vi.unstubAllGlobals();
+});
+
+describe("createApp frappe connection by page kind (MPO-328)", () => {
+  it("an SPA shell with no runtime BASE_URL on an https origin dials its own origin", () => {
+    env.FRAPPE_SOCKETIO_PORT = "9000";
+    openPage("https://pokemon.bitspur.com/backoffice/pokemon");
+    expect(connection()).toEqual({ baseURL: "https://pokemon.bitspur.com", socketPort: null });
+  });
+
+  it("an SPA shell carrying the build's loopback BASE_URL dials its own origin too", () => {
+    env.BASE_URL = "http://localhost:8000";
+    env.FRAPPE_SOCKETIO_PORT = "9000";
+    openPage("https://pokemon.bitspur.com/backoffice/pokemon/pikachu");
+    expect(connection()).toEqual({ baseURL: "https://pokemon.bitspur.com", socketPort: null });
+  });
+
+  it("an SSR page keeps the runtime BASE_URL in the browser", () => {
+    env.BASE_URL = "https://pokemon.bitspur.com";
+    env.FRAPPE_SOCKETIO_PORT = "9000";
+    openPage("https://pokemon.bitspur.com/pokemon");
+    expect(connection()).toEqual({ baseURL: "https://pokemon.bitspur.com", socketPort: null });
+  });
+
+  it("an SSR page renders the runtime BASE_URL on the server", () => {
+    env.BASE_URL = "https://pokemon.bitspur.com";
+    env.FRAPPE_SOCKETIO_PORT = "9000";
+    expect(connection()).toEqual({ baseURL: "https://pokemon.bitspur.com", socketPort: 9000 });
+  });
+
+  it("dev on localhost:3456 dials the bench behind :8000 with the socketio port", () => {
+    mode.dev = true;
+    env.BASE_URL = "http://localhost:8000";
+    env.FRAPPE_SOCKETIO_PORT = "9000";
+    openPage("http://localhost:3456/backoffice/pokemon");
+    expect(connection()).toEqual({ baseURL: "http://localhost:8000", socketPort: 9000 });
+  });
+
+  it("dev without BASE_URL falls back to the :8000 bench", () => {
+    mode.dev = true;
+    env.FRAPPE_SOCKETIO_PORT = "9000";
+    openPage("http://localhost:3456/");
+    expect(connection()).toEqual({ baseURL: "http://localhost:8000", socketPort: 9000 });
+  });
+
+  it("dev over the LAN keeps the :8000 bench on the page host", () => {
+    mode.dev = true;
+    env.BASE_URL = "http://localhost:8000";
+    env.FRAPPE_SOCKETIO_PORT = "9000";
+    openPage("http://10.236.0.10:3456/backoffice/pokemon");
+    expect(connection()).toEqual({ baseURL: "http://10.236.0.10:8000", socketPort: 9000 });
+  });
+
+  it("native has no page location, so the resolved dev origin passes through", () => {
+    env.BASE_URL = "http://192.168.1.20:8000";
+    env.FRAPPE_SOCKETIO_PORT = "9000";
+    vi.stubGlobal("window", {});
+    expect(connection()).toEqual({ baseURL: "http://192.168.1.20:8000", socketPort: 9000 });
+  });
+});
+
+describe("followPageOriginForLoopback", () => {
+  const page = (href: string) => new URL(href);
+
+  it("takes scheme, host and port from a production page", () => {
+    expect(
+      followPageOriginForLoopback("http://localhost:8000", page("https://app.example"), false),
+    ).toBe("https://app.example");
+    expect(
+      followPageOriginForLoopback("http://127.0.0.1:8000", page("http://10.0.0.5:3000/x"), false),
+    ).toBe("http://10.0.0.5:3000");
+  });
+
+  it("keeps a configured path", () => {
+    expect(
+      followPageOriginForLoopback(
+        "http://localhost:8000/bench",
+        page("https://app.example"),
+        false,
+      ),
+    ).toBe("https://app.example/bench");
+  });
+
+  it("swaps only the host in dev", () => {
+    expect(
+      followPageOriginForLoopback("http://localhost:8000", page("http://10.0.0.5:3456"), true),
+    ).toBe("http://10.0.0.5:8000");
+  });
+
+  it("leaves a real bench host alone", () => {
+    expect(
+      followPageOriginForLoopback("https://bench.example", page("https://app.example"), false),
+    ).toBe("https://bench.example");
+  });
+
+  it("leaves a loopback page alone", () => {
+    expect(
+      followPageOriginForLoopback("http://localhost:8000", page("http://127.0.0.1:3456"), false),
+    ).toBe("http://localhost:8000");
+  });
+
+  it("keeps the dev rewrite on non-http pages", () => {
+    expect(
+      followPageOriginForLoopback(
+        "http://localhost:8000",
+        { protocol: "tauri:", hostname: "tauri.localhost", port: "" },
+        false,
+      ),
+    ).toBe("http://tauri.localhost:8000");
+  });
+
+  it("passes through without a page", () => {
+    expect(followPageOriginForLoopback("http://localhost:8000", undefined, false)).toBe(
+      "http://localhost:8000",
+    );
+  });
+});

package/src/app/CreateApp.tsx

@@ -3,15 +3,19 @@ import React, {
   createContext,
   lazy,
   useContext,
+  useMemo,
   type ComponentType,
   type PropsWithChildren,
   type ReactNode,
 } from "react";
-import { config, isWeb } from "@multiplatform.one/platform";
+import { config, isDev, isWeb } from "@multiplatform.one/platform";
 import type { ThemeConfig } from "@multiplatform.one/theme";
 import { ThemeProvider } from "@multiplatform.one/theme";
 import { FrappeProvider } from "@multiplatform.one/frappe-ui";
-import type { FixtureProvider } from "@multiplatform.one/frappe";
+import type { FixtureProvider, SyncOptions } from "@multiplatform.one/frappe";
+import { frappeSocketPort } from "./frappeSocketPort";
+import { frappeSyncOptions } from "./frappeSyncOptions";
+import { oneFrappeNavigation } from "./oneFrappeNavigation";
 import { createTanstackProvider } from "./TanstackProvider";
 // Platform-split: native -> bridge-only web3 via the `/native` subpath (no connectkit
 // in Hermes); web -> passthrough (web mounts the provider at screen scope). Importing a
@@ -23,23 +27,53 @@ export type ProviderComponent = ComponentType<PropsWithChildren>;
 
 const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
 
+/** The parts of `window.location` the loopback rewrite reads. */
+export interface PageLocation {
+  protocol: string;
+  hostname: string;
+  port: string;
+}
+
+function currentPageLocation(): PageLocation | undefined {
+  if (typeof window === "undefined" || !window.location?.hostname) return undefined;
+  return window.location;
+}
+
 /**
  * Follow the page origin when a loopback-configured backend is opened from a
- * non-loopback host. Dev configs point at `http://localhost:8000`, which is
- * correct on the dev machine but breaks the moment the app is opened via a
- * LAN IP (`http://10.x.x.x:3456` → the API and the Socket.IO handshake would
- * target the *visitor's* machine, and Chromium's Local Network Access policy
- * flags the cross-origin loopback fetch). Rewriting only the hostname keeps
- * the configured scheme and port, and only ever triggers in a browser whose
- * page host is itself not loopback — SSR and same-machine dev are untouched.
+ * non-loopback host.
+ *
+ * Dev: configs point at `http://localhost:8000`, which is correct on the dev
+ * machine but breaks the moment the app is opened via a LAN IP
+ * (`http://10.x.x.x:3456` → the API and the Socket.IO handshake would target
+ * the *visitor's* machine, and Chromium's Local Network Access policy flags
+ * the cross-origin loopback fetch). Rewriting only the hostname keeps the
+ * configured scheme and port, so the dev bench beside the dev server answers.
+ *
+ * Production: One renders SPA-mode pages (`/`, `/backoffice/*`) to static
+ * HTML at build time, so their config payload carries the build's `.env`
+ * BASE_URL, not the container's. A deployment serves the bench through its
+ * own origin (MPO-322), so scheme, host and port all follow the page, and
+ * `frappeSocketPort` then drops the baked socketio port (MPO-328).
+ *
+ * Only ever triggers in a browser whose page host is itself not loopback, so
+ * SSR, native and same-machine dev are untouched. Non-http(s) pages (Tauri,
+ * extensions) keep the dev rewrite.
  */
-export function followPageOriginForLoopback(configured: string): string {
-  if (typeof window === "undefined" || !window.location?.hostname) return configured;
+export function followPageOriginForLoopback(
+  configured: string,
+  page: PageLocation | undefined = currentPageLocation(),
+  dev: boolean = isDev,
+): string {
+  if (!page?.hostname) return configured;
   try {
     const url = new URL(configured);
-    const pageHost = window.location.hostname;
-    if (!LOOPBACK_HOSTS.has(url.hostname) || LOOPBACK_HOSTS.has(pageHost)) return configured;
-    url.hostname = pageHost;
+    if (!LOOPBACK_HOSTS.has(url.hostname) || LOOPBACK_HOSTS.has(page.hostname)) return configured;
+    url.hostname = page.hostname;
+    if (!dev && (page.protocol === "https:" || page.protocol === "http:")) {
+      url.protocol = page.protocol;
+      url.port = page.port;
+    }
     return url.toString().replace(/\/$/, "");
   } catch {
     return configured;
@@ -51,7 +85,11 @@ export function followPageOriginForLoopback(configured: string): string {
 // ---------------------------------------------------------------------------
 
 export interface TanstackConfig {
-  /** Show React Query devtools (web only, ignored on native and in Storybook). */
+  /**
+   * Show React Query devtools (web only, ignored on native and in Storybook).
+   * Omitted, they show in a dev build or when DEBUG=1, and a production
+   * visitor never loads them.
+   */
   debug?: boolean;
   /**
    * Shake the device to open the devtools shell (web only; requires
@@ -136,6 +174,12 @@ export interface FrappeConfig {
     token?: string | (() => string | Promise<string>);
     type?: string;
   };
+  /**
+   * Options for the live data engine. When `catchUpStrategy` is omitted,
+   * FRAPPE_CATCH_UP_STRATEGY (`cdc` or `snapshot`) is read at runtime; a
+   * bench without the `live` app needs `snapshot`, since CDC catch-up calls it.
+   */
+  syncOptions?: SyncOptions;
   /**
    * Fixture corpus every Frappe read and write is served from — the whole
    * app runs with no bench and no network. Setting it enables the provider
@@ -348,6 +392,11 @@ export function createApp(appConfig: CreateAppConfig) {
     const cfg: FrappeConfig = appConfig.frappe === true ? {} : appConfig.frappe;
 
     function FrappeProviderWrapper({ children }: PropsWithChildren) {
+      const configuredCatchUp = config.get("FRAPPE_CATCH_UP_STRATEGY");
+      const syncOptions = useMemo(
+        () => frappeSyncOptions(cfg.syncOptions, configuredCatchUp),
+        [configuredCatchUp],
+      );
       // A fixture corpus is an explicit opt-in, so it enables the provider
       // without FRAPPE_ENABLED=1 in .env.
       const enabled = cfg.enabled ?? (!!cfg.fixtures || config.get("FRAPPE_ENABLED") === "1");
@@ -363,7 +412,7 @@ export function createApp(appConfig: CreateAppConfig) {
         : cfg.baseURL || config.get("BASE_URL") || "http://localhost:8000";
       const baseURL = configured ? followPageOriginForLoopback(configured) : undefined;
       const socketPort =
-        cfg.socketPort ?? (Number(config.get("FRAPPE_SOCKETIO_PORT")) || undefined);
+        cfg.socketPort ?? frappeSocketPort(config.get("FRAPPE_SOCKETIO_PORT"), baseURL);
 
       // Keycloak auth uses ONE transport on every platform: the HttpClient
       // and the Socket.IO handshake send `Authorization: Bearer <keycloak
@@ -394,7 +443,9 @@ export function createApp(appConfig: CreateAppConfig) {
           realtime={cfg.realtime}
           socketPort={socketPort}
           auth={auth}
+          syncOptions={syncOptions}
           fixtures={cfg.fixtures}
+          navigation={oneFrappeNavigation}
         >
           {children}
         </FrappeProvider>

package/src/app/CreateRootLayout.hydration.spec.tsx

@@ -0,0 +1,97 @@
+// @vitest-environment jsdom
+import { renderToString } from "react-dom/server";
+import { act } from "react";
+import { hydrateRoot } from "react-dom/client";
+import { describe, expect, it, vi } from "vitest";
+import type { ReactNode } from "react";
+import { createRootLayout } from "./CreateRootLayout.web";
+
+vi.mock("one", () => ({ LoadProgressBar: () => null, Slot: () => null, useMatches: () => [] }));
+vi.mock("tamagui", async () => ({
+  useDidFinishSSR: (await import("@tamagui/use-did-finish-ssr")).useDidFinishSSR,
+}));
+const scheme = vi.hoisted(() => ({ value: "light", stored: "dark", system: "dark" }));
+vi.mock("@vxrn/color-scheme", () => ({
+  SchemeProvider: ({ children }: { children: ReactNode }) => children,
+  setUserScheme: (value: string) => {
+    scheme.value = value === "system" ? scheme.system : value;
+  },
+  useUserScheme: () => ({ value: scheme.value }),
+}));
+vi.mock("i18next", () => ({
+  default: {
+    use: () => ({ init: () => Promise.resolve() }),
+    changeLanguage: vi.fn(),
+    language: "en",
+  },
+}));
+vi.mock("react-i18next", () => ({ initReactI18next: {} }));
+vi.mock("@multiplatform.one/platform", () => ({
+  config: { get: (_key: string, fallback?: string) => fallback },
+  isDev: false,
+  platform: { isServer: true },
+}));
+vi.mock("@multiplatform.one/i18n", () => ({ createI18nConfig: () => ({}) }));
+vi.mock("@multiplatform.one/logger", () => ({ logger: { error: vi.fn() } }));
+vi.mock("@multiplatform.one/store", () => ({ storage: { getItem: () => scheme.stored } }));
+vi.mock("./RuntimePublicConfigScript", () => ({ RuntimePublicConfigScript: () => null }));
+
+describe("web root scheme hydration", () => {
+  it.each(["dark", "system", "light"])(
+    "hydrates server markup before adopting %s preference",
+    async (stored) => {
+      scheme.stored = stored;
+      scheme.system = "dark";
+      const observed: string[] = [];
+      const Provider = ({
+        systemTheme,
+        children,
+      }: {
+        systemTheme: string;
+        children?: ReactNode;
+      }) => {
+        observed.push(systemTheme);
+        return (
+          <section
+            data-scheme={systemTheme}
+            style={{ color: systemTheme === "dark" ? "white" : "black" }}
+          >
+            {children}
+          </section>
+        );
+      };
+      const Layout = createRootLayout({
+        AppProvider: Provider,
+        RootLayout: ({ children }: { children?: ReactNode }) => children,
+        i18n: { defaultLanguage: "en" },
+      } as Parameters<typeof createRootLayout>[0]);
+      scheme.value = "light";
+      document.documentElement.lang = "en";
+      document.documentElement.innerHTML = renderToString(<Layout />).replace(
+        /^<html[^>]*>|<\/html>$/g,
+        "",
+      );
+      observed.length = 0;
+      scheme.value = stored === "system" ? "dark" : stored;
+      const errors: unknown[] = [];
+      const consoleError = vi.spyOn(console, "error").mockImplementation((...args) => {
+        errors.push(args);
+      });
+      let root: ReturnType<typeof hydrateRoot>;
+      await act(async () => {
+        root = hydrateRoot(document, <Layout />, {
+          onRecoverableError: (error) => errors.push(error),
+        });
+      });
+      expect(observed[0]).toBe("light");
+      expect(document.querySelector("[data-scheme]")?.getAttribute("data-scheme")).toBe(
+        stored === "system" ? "dark" : stored,
+      );
+      expect(
+        errors.filter((error) => /hydration|hydrated|didn't match/i.test(String(error))),
+      ).toEqual([]);
+      await act(async () => root!.unmount());
+      consoleError.mockRestore();
+    },
+  );
+});