@multiplatform.one/core 6.0.0

package/src/app/CreateRootLayout.native.tsx

@@ -0,0 +1,74 @@
+import { SchemeProvider, useUserScheme } from "@vxrn/color-scheme";
+import { useFonts } from "expo-font";
+import i18n from "i18next";
+import { Slot } from "one";
+import type { ComponentType, ReactNode } from "react";
+import { StyleSheet } from "react-native";
+import { GestureHandlerRootView } from "react-native-gesture-handler";
+import { SafeAreaProvider } from "react-native-safe-area-context";
+import { initReactI18next } from "react-i18next";
+import { config } from "@multiplatform.one/platform";
+import { createI18nConfig } from "@multiplatform.one/i18n";
+import { logger } from "@multiplatform.one/logger";
+import type { CreateRootLayoutConfig } from "./rootLayoutShared";
+
+export type {
+  CreateRootLayoutConfig,
+  HeadConfig,
+  RootLayoutProps,
+  RootLoaderData,
+  SentryConfig,
+} from "./rootLayoutShared";
+
+const styles = StyleSheet.create({
+  container: { flex: 1 },
+});
+
+/**
+ * Creates a root layout component for **React Native** (iOS + Android).
+ *
+ * Handles i18n initialization, color-scheme detection via `@vxrn/color-scheme`,
+ * and wraps content in `GestureHandlerRootView` → `SafeAreaProvider` →
+ * `SchemeProvider` → `AppProvider` → `RootLayout` → `<Slot />`.
+ *
+ * `head` and `sentry` config options are ignored on native.
+ */
+export function createRootLayout(cfg: CreateRootLayoutConfig): ComponentType {
+  i18n.use(initReactI18next).init(createI18nConfig(cfg.i18n)).catch(logger.error);
+  i18n.changeLanguage(config.get("I18N_DEFAULT_LANGUAGE", cfg.i18n.defaultLanguage));
+
+  const { AppProvider, RootLayout } = cfg;
+
+  function NativeRootProvider({ children }: { children: ReactNode }) {
+    const { value: systemScheme } = useUserScheme();
+
+    return <AppProvider systemTheme={systemScheme}>{children}</AppProvider>;
+  }
+  NativeRootProvider.displayName = "NativeRootProvider";
+
+  const fontsMap = cfg.fonts ?? {};
+
+  function Layout() {
+    const [fontsLoaded, fontError] = useFonts(fontsMap);
+    // Gate on fonts being ready, but never block forever: if font loading
+    // fails (e.g. asset fetch errors in a dev client), still render with the
+    // system fallback rather than leaving a permanently blank screen.
+    if (!fontsLoaded && !fontError) return null;
+    return (
+      <GestureHandlerRootView style={styles.container}>
+        <SafeAreaProvider>
+          <SchemeProvider>
+            <NativeRootProvider>
+              <RootLayout>
+                <Slot />
+              </RootLayout>
+            </NativeRootProvider>
+          </SchemeProvider>
+        </SafeAreaProvider>
+      </GestureHandlerRootView>
+    );
+  }
+  Layout.displayName = "RootLayout";
+
+  return Layout;
+}

package/src/app/CreateRootLayout.tsx

@@ -0,0 +1,66 @@
+import i18n from "i18next";
+import { LoadProgressBar, Slot } from "one";
+import { useEffect, useState, type ComponentType, type ReactNode } from "react";
+import { initReactI18next } from "react-i18next";
+import { config } from "@multiplatform.one/platform";
+import { createI18nConfig } from "@multiplatform.one/i18n";
+import { logger } from "@multiplatform.one/logger";
+import type { CreateRootLayoutConfig } from "./rootLayoutShared";
+
+export type {
+  CreateRootLayoutConfig,
+  HeadConfig,
+  RootLayoutProps,
+  RootLoaderData,
+  SentryConfig,
+} from "./rootLayoutShared";
+
+/**
+ * Creates a root layout component (universal fallback for Tauri / desktop).
+ *
+ * Handles i18n initialization, color-scheme detection via `matchMedia`,
+ * and wraps content in `LoadProgressBar` → `AppProvider` → `RootLayout` → `<Slot />`.
+ *
+ * `head` and `sentry` config options are ignored in the universal fallback.
+ */
+export function createRootLayout(cfg: CreateRootLayoutConfig): ComponentType {
+  i18n.use(initReactI18next).init(createI18nConfig(cfg.i18n)).catch(logger.error);
+  i18n.changeLanguage(config.get("I18N_DEFAULT_LANGUAGE", cfg.i18n.defaultLanguage));
+
+  const { AppProvider, RootLayout } = cfg;
+
+  function RootProvider({ children }: { children: ReactNode }) {
+    const [scheme, setScheme] = useState<"light" | "dark">("light");
+
+    useEffect(() => {
+      if (typeof window !== "undefined" && window.matchMedia) {
+        const darkModeQuery = window.matchMedia("(prefers-color-scheme: dark)");
+        setScheme(darkModeQuery.matches ? "dark" : "light");
+        const handleChange = (e: MediaQueryListEvent) => {
+          setScheme(e.matches ? "dark" : "light");
+        };
+        darkModeQuery.addEventListener("change", handleChange);
+        return () => darkModeQuery.removeEventListener("change", handleChange);
+      }
+    }, []);
+
+    return <AppProvider systemTheme={scheme}>{children}</AppProvider>;
+  }
+  RootProvider.displayName = "RootProvider";
+
+  function Layout() {
+    return (
+      <>
+        <LoadProgressBar />
+        <RootProvider>
+          <RootLayout>
+            <Slot />
+          </RootLayout>
+        </RootProvider>
+      </>
+    );
+  }
+  Layout.displayName = "RootLayout";
+
+  return Layout;
+}

package/src/app/CreateRootLayout.web.tsx

@@ -0,0 +1,181 @@
+import i18n from "i18next";
+import { LoadProgressBar, Slot, useMatches } from "one";
+import { SchemeProvider, setUserScheme, useUserScheme } from "@vxrn/color-scheme";
+import type { ComponentType, ReactNode } from "react";
+import { CookiesProvider, Cookies } from "react-cookie";
+import { initReactI18next } from "react-i18next";
+import { config, isDev, platform } from "@multiplatform.one/platform";
+import { createI18nConfig } from "@multiplatform.one/i18n";
+import { logger } from "@multiplatform.one/logger";
+import { storage } from "@multiplatform.one/store";
+import type { CreateRootLayoutConfig, RootLoaderData } from "./rootLayoutShared";
+
+export type {
+  CreateRootLayoutConfig,
+  HeadConfig,
+  RootLayoutProps,
+  RootLoaderData,
+  SentryConfig,
+} from "./rootLayoutShared";
+
+/**
+ * Creates a root layout component for **web** (browser + SSR).
+ *
+ * Handles i18n initialization, Sentry setup, color-scheme detection via
+ * `SchemeProvider` (blocking script + localStorage – no cookie needed),
+ * `<Head>` meta tags, `<LoadProgressBar>`, and wraps content in
+ * `SchemeProvider` → `CookiesProvider` → `AppProvider` → `RootLayout` → `<Slot />`.
+ *
+ * Light/dark scheme: handled by `@vxrn/color-scheme` `SchemeProvider` which
+ * injects a blocking `<script>` that reads `localStorage` / `matchMedia`
+ * before the first paint. Works even when cookies are disabled.
+ *
+ * Theme properties (color theme, padding, borderRadius, …): synced via
+ * `mp.preset` + `mp.overrides` cookies so SSR can render with the user's full
+ * theme. The cookies are populated by `useTheme` in `@multiplatform.one/theme`.
+ */
+export function createRootLayout(cfg: CreateRootLayoutConfig): ComponentType {
+  // Eagerly patch the @vxrn/color-scheme module state BEFORE React renders.
+  //
+  // On web, useUserScheme() initializes with { value: 'light' } for SSR
+  // compatibility. This means SchemeProvider's layout effect briefly sets
+  // `t_light` on <html>, overriding the correct class that the blocking
+  // <script> already established — causing a dark→light→dark flash.
+  //
+  // By calling setUserScheme() here (synchronous, before any component
+  // renders), the module-level `currentValue` is correct when useState
+  // initializers run, so useUserScheme() returns the right value from
+  // the very first render. SchemeProvider's layout effect then sets the
+  // correct class immediately, eliminating the flash.
+  if (typeof window !== "undefined") {
+    try {
+      const storedValue = storage.getItem("vxrn-scheme");
+      const stored = typeof storedValue === "string" || storedValue === null ? storedValue : null;
+      if (stored === "light" || stored === "dark" || stored === "system") {
+        setUserScheme(stored);
+      } else {
+        // No persisted preference — default behavior is "system".
+        // Eagerly set "system" so useUserScheme() resolves from matchMedia
+        // on the very first render instead of falling back to "light".
+        // Without this, React's first render computes activeTheme="light",
+        // overriding the t_dark class the blocking script already set,
+        // then a useEffect flips it back — causing a light→dark flash.
+        setUserScheme("system");
+      }
+    } catch {
+      // storage access might throw in sandboxed contexts
+    }
+  }
+
+  i18n.use(initReactI18next).init(createI18nConfig(cfg.i18n)).catch(logger.error);
+  i18n.changeLanguage(config.get("I18N_DEFAULT_LANGUAGE", cfg.i18n.defaultLanguage));
+
+  const sentryDsn = cfg.sentry?.dsn || config.get("SENTRY_DSN");
+  if (sentryDsn && !platform.isServer) {
+    import("@sentry/react")
+      .then((Sentry) => {
+        Sentry.init({
+          dsn: sentryDsn,
+          enabled: !isDev,
+        });
+      })
+      .catch(() => {});
+  }
+
+  const { AppProvider, RootLayout } = cfg;
+
+  /**
+   * Reads the resolved color scheme from `@vxrn/color-scheme` and passes
+   * it (along with theme cookies) to the AppProvider / ThemeProvider.
+   *
+   * Because we eagerly call `setUserScheme()` above (before React renders),
+   * `useUserScheme()` returns the correct value from the very first render.
+   * No eagerScheme / warmedUp workaround needed.
+   */
+  function WebRootProvider({ children }: { children: ReactNode }) {
+    const { value: scheme } = useUserScheme();
+
+    return <AppProvider systemTheme={scheme}>{children}</AppProvider>;
+  }
+  WebRootProvider.displayName = "WebRootProvider";
+
+  function Layout() {
+    // During SSR, read the raw cookie header from the root layout loader
+    // so that CookiesProvider (and useCookies/useTheme inside the tree)
+    // can resolve the user's persisted theme properties during server
+    // rendering. Light/dark is handled separately by SchemeProvider.
+    const matches = useMatches();
+    const rootLoaderData = matches?.[0]?.loaderData as RootLoaderData | undefined;
+    const ssrCookies =
+      platform.isServer && rootLoaderData?.cookieHeader
+        ? new Cookies(rootLoaderData.cookieHeader)
+        : undefined;
+
+    // Use SSR-detected language (from loader) or fall back to i18next's current language
+    const htmlLang =
+      rootLoaderData?.detectedLanguage || i18n.language || cfg.i18n.defaultLanguage || "en";
+    // Sync i18next to the detected language during SSR so initial render matches
+    if (
+      platform.isServer &&
+      rootLoaderData?.detectedLanguage &&
+      i18n.language !== rootLoaderData.detectedLanguage
+    ) {
+      i18n.changeLanguage(rootLoaderData.detectedLanguage);
+    }
+
+    return (
+      <html lang={htmlLang}>
+        <head>
+          <meta charSet="utf-8" />
+          {/* Critical reset CSS with data-precedence so React 19 hoists it
+              to the very top of <head> – BEFORE the Tamagui atomic CSS.
+              This eliminates FOUC during streaming SSR. */}
+          <style precedence="reset" href="__critical_reset">
+            {[
+              "html{max-width:100vw;color-scheme:light dark}",
+              "body{overflow-x:hidden;margin:0;display:flex;flex-direction:column;min-width:100%;min-height:100vh}",
+              "#root,#__next{display:flex;flex-direction:column;min-width:100%;min-height:100vh}",
+              "*{box-sizing:border-box}",
+              "a{color:inherit;text-decoration:none}",
+              "h1,h2,h3,h4,h5,h6{margin:0;padding:0}",
+              "p,input,textarea,button,ul,ol,li,pre,dialog{all:unset;box-sizing:border-box}",
+              "@keyframes skeleton-pulse{0%{opacity:1}50%{opacity:0.4}100%{opacity:1}}",
+            ].join("")}
+          </style>
+          {cfg.head && (
+            <>
+              <meta httpEquiv="X-UA-Compatible" content="IE=edge" />
+              <meta
+                name="viewport"
+                content="width=device-width, initial-scale=1, maximum-scale=5"
+              />
+              {cfg.head.favicon && <link rel="icon" href={cfg.head.favicon} />}
+            </>
+          )}
+          {/* tamagui.css is imported via JS in _layout.web.tsx (takeout2 pattern) */}
+        </head>
+        <body>
+          <LoadProgressBar />
+          {/* SchemeProvider (@vxrn/color-scheme) injects a blocking inline <script> that reads
+              localStorage('vxrn-scheme'), falls back to matchMedia, and sets t_light/t_dark on <html>.
+              Edge case: when localStorage throws (e.g. Safari private mode pre-14, or undefined),
+              the script handles it gracefully, falls back to matchMedia("(prefers-color-scheme: dark)"),
+              and if matchMedia is unavailable (very old browsers) defaults to light. No runtime error,
+              no flash. We cannot modify the third-party component — this documents the inherent behavior. */}
+          <SchemeProvider>
+            <CookiesProvider cookies={ssrCookies}>
+              <WebRootProvider>
+                <RootLayout ssrSession={rootLoaderData?.session}>
+                  <Slot />
+                </RootLayout>
+              </WebRootProvider>
+            </CookiesProvider>
+          </SchemeProvider>
+        </body>
+      </html>
+    );
+  }
+  Layout.displayName = "RootLayout";
+
+  return Layout;
+}

package/src/app/TanstackDevtools.tsx

@@ -0,0 +1,138 @@
+import React from "react";
+import { ReactQueryDevtools } from "@tanstack/react-query-devtools";
+import { TanStackDevtools } from "@tanstack/react-devtools";
+import { formDevtoolsPlugin } from "@tanstack/react-form-devtools";
+import { pacerDevtoolsPlugin } from "@tanstack/react-pacer-devtools";
+import { ThemeDevtoolsPanel } from "@multiplatform.one/theme";
+import { storage } from "@multiplatform.one/store";
+import { useEffect, useState } from "react";
+import type { TanstackConfig } from "./CreateApp";
+
+const devtoolsSettingsKey = "tanstack_devtools_settings";
+
+/**
+ * Sync the resolved color scheme into the TanStack Devtools settings
+ * stored via the shared storage adapter. The devtools shell reads this on mount and
+ * uses it for its own light/dark chrome.
+ */
+async function syncDevtoolsTheme(resolvedScheme: "light" | "dark") {
+  try {
+    const raw = await Promise.resolve(storage.getItem(devtoolsSettingsKey));
+    const settings = raw ? JSON.parse(raw) : {};
+    if (settings.theme !== resolvedScheme) {
+      settings.theme = resolvedScheme;
+      await Promise.resolve(storage.setItem(devtoolsSettingsKey, JSON.stringify(settings)));
+    }
+  } catch {
+    // sandboxed / private-mode contexts
+  }
+}
+
+export interface TanstackDevtoolsProps {
+  resolvedScheme: "light" | "dark";
+  tanstackConfig: TanstackConfig;
+}
+
+/**
+ * Lazily-loaded devtools shell. All heavy devtools dependencies
+ * (`@tanstack/react-devtools`, `@tanstack/react-query-devtools`,
+ * `@tanstack/react-form-devtools`, `@tanstack/react-pacer-devtools`,
+ * and `ThemeDevtoolsPanel`) live here so they are code-split away
+ * from the production bundle.
+ */
+/**
+ * Lazily resolves the Frappe devtools plugin. Returns null when no
+ * SyncModule is active (e.g. Frappe not configured or not yet initialized).
+ * Re-checks periodically until a SyncModule appears.
+ */
+function useFrappePlugin() {
+  const [plugin, setPlugin] = useState<ReturnType<
+    typeof import("@multiplatform.one/frappe/devtools").frappeDevtoolsPlugin
+  > | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    async function tryResolve() {
+      try {
+        const [{ frappeDevtoolsPlugin }, { __getActiveSyncModule }] = await Promise.all([
+          import("@multiplatform.one/frappe/devtools"),
+          import("@multiplatform.one/frappe"),
+        ]);
+        const sync = __getActiveSyncModule();
+        if (sync && !cancelled) {
+          setPlugin(frappeDevtoolsPlugin(sync));
+          return true;
+        }
+      } catch {
+        // frappe package not installed or not available — skip
+      }
+      return false;
+    }
+
+    // Try immediately, then poll a few times in case SyncModule is created later
+    void tryResolve().then((found) => {
+      if (found || cancelled) return;
+      let attempts = 0;
+      const interval = setInterval(async () => {
+        attempts++;
+        const found = await tryResolve();
+        if (found || cancelled || attempts >= 10) clearInterval(interval);
+      }, 2000);
+      return () => clearInterval(interval);
+    });
+
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  return plugin;
+}
+
+export default function TanstackDevtoolsWrapper({
+  resolvedScheme,
+  tanstackConfig,
+}: TanstackDevtoolsProps) {
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    void syncDevtoolsTheme(resolvedScheme);
+  }, [resolvedScheme]);
+
+  const frappePlugin = useFrappePlugin();
+
+  const plugins = [
+    {
+      id: "react-query",
+      name: "React Query",
+      render: <ReactQueryDevtools initialIsOpen={false} />,
+    },
+    formDevtoolsPlugin(),
+    pacerDevtoolsPlugin(),
+    {
+      id: "theme",
+      name: "Theme",
+      render: (_el: HTMLElement, props: { theme: "dark" | "light" }) => (
+        <ThemeDevtoolsPanel
+          useUserScheme={tanstackConfig.useUserScheme}
+          devtoolsTheme={props.theme}
+          tamaguiConfig={tanstackConfig.tamaguiConfig}
+        />
+      ),
+    },
+    ...(frappePlugin ? [frappePlugin] : []),
+  ];
+
+  return (
+    <TanStackDevtools
+      key={resolvedScheme}
+      config={{
+        defaultOpen: false,
+        triggerHidden: true,
+        openHotkey: ["CtrlOrMeta", "`"],
+        theme: resolvedScheme,
+      }}
+      plugins={plugins}
+    />
+  );
+}

package/src/app/TanstackProvider.tsx

@@ -0,0 +1,41 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { Suspense, lazy, type PropsWithChildren } from "react";
+import { platform } from "@multiplatform.one/platform";
+import type { ProviderComponent, TanstackConfig } from "./CreateApp";
+
+const LazyDevtools = lazy(() => import("./TanstackDevtools"));
+
+export function createTanstackProvider(tanstackConfig: TanstackConfig): ProviderComponent {
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: {
+        staleTime: 30 * 1000,
+        retryDelay: (attempt) => Math.min(1000 * 2 ** attempt, 10_000),
+      },
+    },
+    ...tanstackConfig.queryClientOptions,
+  });
+
+  function TanstackProvider({ children }: PropsWithChildren) {
+    // TODO(native): TanStack Devtools does not yet support React Native. When it does,
+    // revisit this guard to also handle native (e.g. !platform.isNative) so devtools
+    // are enabled on native when supported.
+    const showDevtools = tanstackConfig.debug && !platform.isStorybook;
+
+    const scheme = tanstackConfig.useUserScheme?.();
+    const resolvedScheme = scheme?.value ?? "light";
+
+    return (
+      <QueryClientProvider client={queryClient}>
+        {showDevtools && (
+          <Suspense>
+            <LazyDevtools resolvedScheme={resolvedScheme} tanstackConfig={tanstackConfig} />
+          </Suspense>
+        )}
+        {children}
+      </QueryClientProvider>
+    );
+  }
+  TanstackProvider.displayName = "TanstackProvider";
+  return TanstackProvider;
+}

package/src/app/index.ts

@@ -0,0 +1,27 @@
+/**
+ * ## Platform File Extension Conventions
+ *
+ * The framework uses platform-specific file extensions for automatic
+ * bundler resolution. When multiple variants exist for a module, the
+ * bundler picks the most specific match for the current target:
+ *
+ * | Extension        | Target                                  |
+ * | ---------------- | --------------------------------------- |
+ * | `.web.tsx`       | Web (browser + SSR)                     |
+ * | `.native.tsx`    | React Native (iOS + Android)            |
+ * | `.ios.tsx`       | iOS only                                |
+ * | `.android.tsx`   | Android only                            |
+ * | `.tauri.tsx`     | Tauri desktop (macOS, Windows, Linux)   |
+ * | `.storybook-expo.ts` | Storybook running in Expo           |
+ * | (no suffix)      | Universal fallback / shared code        |
+ *
+ * Resolution priority (most → least specific):
+ *   `.ios.tsx` > `.native.tsx` > `.tsx` (on iOS)
+ *   `.web.tsx` > `.tsx` (on web)
+ *   `.tauri.tsx` > `.tsx` (on Tauri)
+ *
+ * When creating platform-specific variants, always keep a universal
+ * fallback file (e.g. `index.ts`) that exports the default API.
+ */
+export * from "./CreateApp";
+export * from "./CreateRootLayout";

package/src/app/loadWalletProvider.d.ts

@@ -0,0 +1,7 @@
+import type { ComponentType, PropsWithChildren } from "react";
+
+// Type stub for the platform-split loadWalletProvider (loadWalletProvider.native.ts /
+// loadWalletProvider.web.ts). The bundler resolves the concrete file per platform;
+// this lets `import LazyWalletProvider from "./loadWalletProvider"` typecheck.
+declare const WalletProvider: ComponentType<PropsWithChildren<Record<string, unknown>>>;
+export default WalletProvider;

package/src/app/loadWalletProvider.native.ts

@@ -0,0 +1,14 @@
+import { lazy } from "react";
+
+// Native loads the web3 WalletProvider through the `@multiplatform.one/web3/native`
+// subpath, whose export conditions ALL resolve to the bridge-only native build
+// (src .native variants / dist/esm/index.native.js). The bare `.` package must keep
+// its `import` condition pointing at the WEB dist (.mjs) for the web bundle — but a
+// dynamic import of the bare specifier on native resolves that same web dist and
+// drags connectkit/@reown/@walletconnect (+ their Node-builtin deps: pino,
+// thread-stream, qrcode/pngjs, …) into the Hermes bundle as dead weight. Routing
+// native through `/native` keeps that entire stack out of native, where the wallet
+// connect/modal UI lives in the WebView via the bridge instead.
+export default lazy(() =>
+  import("@multiplatform.one/web3/native").then((mod) => ({ default: mod.WalletProvider })),
+);

package/src/app/loadWalletProvider.web.ts

@@ -0,0 +1,10 @@
+import { Fragment, createElement, type ComponentType, type PropsWithChildren } from "react";
+
+// On web, CreateApp's Web3Provider returns children (the WagmiProvider is mounted at
+// screen scope in features/wallet/Web3ScreenProvider.web, below the navigator, to
+// avoid the SSR/"Another navigator is already registered" problem). So this provider
+// is NEVER rendered on web — it exists only so the shared CreateApp can import a single
+// symbol without pulling the web3 package into the core bootstrap path on web.
+const WalletProvider: ComponentType<PropsWithChildren<Record<string, unknown>>> = ({ children }) =>
+  createElement(Fragment, null, children);
+export default WalletProvider;

package/src/app/rootLayoutShared.ts

@@ -0,0 +1,60 @@
+import type { ComponentType, PropsWithChildren } from "react";
+import type { I18nConfigOptions } from "@multiplatform.one/i18n";
+import type { AppProviderProps } from "./CreateApp";
+
+export interface HeadConfig {
+  /** Path to favicon (e.g. "/favicon.svg"). */
+  favicon?: string;
+}
+
+export interface SentryConfig {
+  /** Sentry DSN. When provided, Sentry is initialized on the web client. */
+  dsn?: string;
+}
+
+/** Shape of the root layout loader data used by createRootLayout. */
+export interface RootLoaderData {
+  cookieHeader?: string;
+  /** Language detected from request (cookie or Accept-Language header). */
+  detectedLanguage?: string;
+  /** Server-side session from the auth loader (used for SSR hydration). */
+  session?: unknown;
+  [key: string]: unknown;
+}
+
+/**
+ * Props accepted by the `RootLayout` component.
+ *
+ * `ssrSession` is provided only on web during SSR so auth-related UI
+ * (e.g. user name, logout button) can render on the first paint without
+ * waiting for a client-side session fetch.
+ */
+export interface RootLayoutProps extends PropsWithChildren {
+  /** Server-side session data for SSR hydration (web only). */
+  ssrSession?: unknown;
+}
+
+/**
+ * Configuration for `createRootLayout()`.
+ *
+ * The factory initializes i18n, detects color scheme, wraps with the
+ * appropriate platform providers, and renders the RootLayout + Slot.
+ */
+export interface CreateRootLayoutConfig {
+  /** The AppProvider component returned from `createApp()`. */
+  AppProvider: ComponentType<AppProviderProps>;
+  /** Root layout shell that wraps route content (navigation chrome, header, etc.). */
+  RootLayout: ComponentType<RootLayoutProps>;
+  /** i18n configuration. i18next is initialized as a side-effect when the factory is called. */
+  i18n: I18nConfigOptions;
+  /** `<Head>` meta tags for web. Ignored on native. */
+  head?: HeadConfig;
+  /** Sentry error tracking. Initialized on the web client only. Ignored on native. */
+  sentry?: SentryConfig;
+  /**
+   * Native font map returned by `importFonts()` from `@package/fonts`.
+   * Passed to `useFonts()` so custom fonts load before the first render.
+   * Ignored on web (fonts are loaded via CSS side-effect imports).
+   */
+  fonts?: Record<string, number>;
+}

package/src/app/tanstackProvider.native.tsx

@@ -0,0 +1,13 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import type { PropsWithChildren } from "react";
+import type { ProviderComponent, TanstackConfig } from "./CreateApp";
+
+export function createTanstackProvider(tanstackConfig: TanstackConfig): ProviderComponent {
+  const queryClient = new QueryClient(tanstackConfig.queryClientOptions);
+
+  function TanstackProvider({ children }: PropsWithChildren) {
+    return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>;
+  }
+  TanstackProvider.displayName = "TanstackProvider";
+  return TanstackProvider;
+}

package/src/healthz.ts

@@ -0,0 +1,4 @@
+/** Health check handler compatible with One framework +api.ts convention. */
+export async function GET(_request: Request) {
+  return new Response(JSON.stringify({ status: "ok" }));
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./app/index";
+export * from "./layouts/index";