@multiplatform.one/core 7.0.0 → 7.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multiplatform.one/core",
-  "version": "7.0.0",
+  "version": "7.2.0",
   "description": "Core framework shell, provider composition, and layout factories for multiplatform.one",
   "keywords": [
     "app",
@@ -42,15 +42,16 @@
   },
   "dependencies": {
     "@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",
-    "@tanstack/react-pacer-devtools": "^0.7.0",
     "react-cookie": "^8.1.2",
-    "@multiplatform.one/i18n": "7.0.0",
-    "@multiplatform.one/logger": "7.0.0",
-    "@multiplatform.one/platform": "7.0.0",
-    "@multiplatform.one/store": "7.0.0",
-    "@multiplatform.one/theme": "7.0.0"
+    "@multiplatform.one/platform": "7.2.0",
+    "@multiplatform.one/logger": "7.2.0",
+    "@multiplatform.one/i18n": "7.2.0",
+    "@multiplatform.one/theme": "7.2.0",
+    "@multiplatform.one/store": "7.2.0"
   },
   "devDependencies": {
     "@sentry/react": "^10.51.0",
@@ -60,14 +61,16 @@
     "i18next": "^25.10.10",
     "one": "^1.16.5",
     "react": "19.2.5",
+    "react-dom": "19.2.5",
     "react-i18next": "^16.6.6",
     "react-native": "0.83.2",
     "react-native-gesture-handler": "~2.31.1",
     "react-native-safe-area-context": "~5.7.0",
     "tamagui": "2.7.6",
     "typescript": "~5.9.3",
-    "@multiplatform.one/frappe": "7.0.0",
-    "@multiplatform.one/web3": "7.0.0"
+    "vitest": "^4.1.5",
+    "@multiplatform.one/web3": "7.2.0",
+    "@multiplatform.one/frappe": "7.2.0"
   },
   "peerDependencies": {
     "@sentry/react": "^9.0.0",
@@ -83,10 +86,10 @@
     "react-native-gesture-handler": ">=2.0.0",
     "react-native-safe-area-context": ">=4.0.0",
     "tamagui": "^2.0.0-rc",
-    "@multiplatform.one/frappe": "^7.0.0",
-    "@multiplatform.one/frappe-ui": "^7.0.0",
-    "@multiplatform.one/keycloak": "^7.0.0",
-    "@multiplatform.one/web3": "^7.0.0"
+    "@multiplatform.one/frappe": "^7.2.0",
+    "@multiplatform.one/frappe-ui": "^7.2.0",
+    "@multiplatform.one/keycloak": "^7.2.0",
+    "@multiplatform.one/web3": "^7.2.0"
   },
   "peerDependenciesMeta": {
     "@multiplatform.one/web3": {

package/src/app/CreateApp.tsx

@@ -52,6 +52,15 @@ export function followPageOriginForLoopback(configured: string): string {
 export interface TanstackConfig {
   /** Show React Query devtools (web only, ignored on native and in Storybook). */
   debug?: boolean;
+  /**
+   * Shake the device to open the devtools shell (web only; requires
+   * `debug`). Defaults to true whenever the devtools mount. On iOS 13+
+   * WebKit the motion permission is requested once from the user's first
+   * tap; Android and desktop need no permission (desktop simply never
+   * fires devicemotion — use the Ctrl/Cmd+` shortcut there). Set false to
+   * keep the keyboard shortcut as the only trigger.
+   */
+  shakeToOpen?: boolean;
   /** Options forwarded to the QueryClient constructor. */
   queryClientOptions?: Record<string, unknown>;
   /**
@@ -70,6 +79,22 @@ export interface TanstackConfig {
    * Passed automatically by `createApp()` from the theme config.
    */
   tamaguiConfig?: unknown;
+  /**
+   * Theme COLOR names the devtools panel offers in its accent dropdown
+   * (e.g. `["", "blue", "green", "purple"]`; `""` is the base theme).
+   * The panel renders the dropdown only when this AND `onThemeColorChange`
+   * are both set, and only then does the panel's Randomize action touch the
+   * accent — otherwise the picker is inert.
+   */
+  themeColors?: string[];
+  /** The theme color the app currently has applied (`""` for the base). */
+  currentThemeColor?: string;
+  /**
+   * Apply a theme color the user picked. The app owns this because a theme
+   * color is app state, not devtools state: the panel changes nothing on its
+   * own, it hands the choice back.
+   */
+  onThemeColorChange?: (color: string) => void;
 }
 
 export interface KeycloakConfig {

package/src/app/CreateRootLayout.web.tsx

@@ -8,6 +8,7 @@ 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 { RuntimePublicConfigScript } from "./RuntimePublicConfigScript";
 import type { CreateRootLayoutConfig, RootLoaderData } from "./rootLayoutShared";
 
 export type {
@@ -142,6 +143,14 @@ export function createRootLayout(cfg: CreateRootLayoutConfig): ComponentType {
       <html lang={htmlLang}>
         <head>
           <meta charSet="utf-8" />
+          {/* RUNTIME public config, first thing after charset so it is parsed
+              and executed before the deferred app bundle constructs Config.
+              Without it the browser has NO path to config at all: Config's env
+              lookup reads process.env, which does not exist there, so a
+              container env var (MARKETPLACE_API_URL, FRAPPE_ENABLED, …) could
+              never reach the SPA and the image had to be rebuilt per
+              environment. See RuntimePublicConfigScript. */}
+          <RuntimePublicConfigScript />
           {interFonts && (
             <>
               <link

package/src/app/RuntimePublicConfigScript.spec.tsx

@@ -0,0 +1,73 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { runtimePublicConfigKey } from "@multiplatform.one/platform";
+import { renderToStaticMarkup } from "react-dom/server";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { RuntimePublicConfigScript } from "./RuntimePublicConfigScript";
+
+// vitest runs this suite in the node environment, so `window` is undefined and
+// `platform.isServer` is true — i.e. every render below is the SSR branch, the
+// one that actually writes the served document.
+function renderDocument(): string {
+  return renderToStaticMarkup(<RuntimePublicConfigScript />);
+}
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+});
+
+describe("RuntimePublicConfigScript", () => {
+  it("emits the public payload into the SSR document", () => {
+    vi.stubEnv("VITE_MP_PUBLIC_CONFIG_KEYS", JSON.stringify(["MARKETPLACE_API_URL"]));
+    vi.stubEnv("MARKETPLACE_API_URL", "https://api.marketplace.example.org");
+    const html = renderDocument();
+    // The whole point of the seam: the VALUE the SSR process holds in its own
+    // env at request time is in the bytes the browser receives. Nothing about
+    // this depends on what the image was BUILT with.
+    expect(html).toContain("<script");
+    expect(html).toContain(runtimePublicConfigKey);
+    expect(html).toContain("https://api.marketplace.example.org");
+  });
+
+  it("emits FRAPPE_ENABLED so the frappe provider can mount in the browser", () => {
+    // CreateApp.tsx: `cfg.enabled ?? config.get("FRAPPE_ENABLED") === "1"`.
+    vi.stubEnv("VITE_MP_PUBLIC_CONFIG_KEYS", JSON.stringify(["FRAPPE_ENABLED"]));
+    vi.stubEnv("FRAPPE_ENABLED", "1");
+    expect(renderDocument()).toContain('"FRAPPE_ENABLED":"1"');
+  });
+
+  it("keeps a private key out of the SSR document", () => {
+    vi.stubEnv("VITE_MP_PUBLIC_CONFIG_KEYS", JSON.stringify(["MARKETPLACE_API_URL"]));
+    vi.stubEnv("MARKETPLACE_API_URL", "https://api.marketplace.example.org");
+    vi.stubEnv("SECRET", "hunter2");
+    vi.stubEnv("DATABASE_PASSWORD", "hunter2");
+    const html = renderDocument();
+    expect(html).not.toContain("SECRET");
+    expect(html).not.toContain("DATABASE_PASSWORD");
+    expect(html).not.toContain("hunter2");
+  });
+
+  it("cannot be closed out of by a value that looks like markup", () => {
+    vi.stubEnv("VITE_MP_PUBLIC_CONFIG_KEYS", JSON.stringify(["BASE_URL"]));
+    vi.stubEnv("BASE_URL", "</script><script>alert(1)</script>");
+    const html = renderDocument();
+    expect(html).not.toContain("</script><script>");
+    expect(html).toContain("\\u003c");
+  });
+});
+
+describe("createRootLayout (web)", () => {
+  it("mounts RuntimePublicConfigScript in the document head", () => {
+    // The component only reaches a browser if the root layout renders it, and
+    // the root layout is a `one` route module that cannot be instantiated
+    // outside a router — so the mount is pinned at the source level. Delete
+    // the element from <head> and this reds.
+    const source = readFileSync(
+      join(dirname(fileURLToPath(import.meta.url)), "CreateRootLayout.web.tsx"),
+      "utf-8",
+    );
+    const head = source.slice(source.indexOf("<head>"), source.indexOf("</head>"));
+    expect(head).toContain("<RuntimePublicConfigScript />");
+  });
+});

package/src/app/RuntimePublicConfigScript.tsx

@@ -0,0 +1,54 @@
+import {
+  platform,
+  runtimePublicConfigKey,
+  serializeRuntimePublicConfig,
+} from "@multiplatform.one/platform";
+
+/**
+ * Publishes the SSR-resolved PUBLIC config into the served document.
+ *
+ * Mounted in `<head>` by `createRootLayout` (web). Deliberately the SAME shape
+ * one uses for `__one_server_context__` — an inline `<script>` assigning a
+ * `globalThis` key, `async` + `href` so React 19 keys it stably, and
+ * `suppressHydrationWarning` because the client renders an EMPTY body for the
+ * already-executed script (one's `server/ServerContextScript` does exactly
+ * this). It is a sibling payload on the established seam, not a second
+ * transport.
+ *
+ * XSS: the injected string is NOT user content. It is built by
+ * `serializeRuntimePublicConfig`, which (a) walks the BUILD-TIME public key
+ * allowlist rather than any request-derived input, and (b) emits the values
+ * through a JSON serializer that escapes `<`, `>`, U+2028 and U+2029 — so the
+ * body cannot close its own `</script>` tag or terminate a JS statement. This
+ * is the same sanitizer shape one ships as `utils/htmlEscape.safeJsonStringify`
+ * for the server-context payload. React offers no other way to emit a script
+ * body: text children of `<script>` are HTML-escaped, which would corrupt the
+ * JSON quoting.
+ *
+ * Ordering: an inline classic script in `<head>` runs during document parse,
+ * while the app bundle is a deferred module script — so `globalThis` already
+ * carries the payload by the time `@multiplatform.one/platform` constructs its
+ * `Config`.
+ *
+ * On the browser the body is empty: `serializeRuntimePublicConfig()` reads
+ * `process.env`, which only exists on the server. Rendering it client-side
+ * would publish an EMPTY payload over the real one.
+ */
+export function RuntimePublicConfigScript() {
+  return (
+    <script
+      async
+      // @ts-expect-error `href` is not on React's ScriptHTMLAttributes — React 19
+      // keys hoisted scripts by it anyway, and `one`'s ServerContextScript (the
+      // sibling payload this deliberately mirrors) carries the identical
+      // suppression on the identical line. Copying the transport means copying
+      // this, not inventing a differently-keyed script.
+      href={runtimePublicConfigKey}
+      suppressHydrationWarning
+      dangerouslySetInnerHTML={{
+        __html: platform.isServer ? serializeRuntimePublicConfig() : "",
+      }}
+    />
+  );
+}
+RuntimePublicConfigScript.displayName = "RuntimePublicConfigScript";

package/src/app/TanstackDevtools.tsx

@@ -1,15 +1,36 @@
 import React from "react";
-import { ReactQueryDevtools } from "@tanstack/react-query-devtools";
+// The `/production` subpaths carry the same implementations the main
+// entries carry in development, but WITHOUT the NODE_ENV !== "development"
+// no-op stubs the main entries dead-code themselves into in a production
+// build. This whole file is lazy-loaded and gated on `tanstackConfig.debug`,
+// so importing the real panels unconditionally is what lets a deployed
+// build that opts in (debug: true) actually show devtools.
+import { ReactQueryDevtools } from "@tanstack/react-query-devtools/production";
 import { TanStackDevtools } from "@tanstack/react-devtools";
-import { formDevtoolsPlugin } from "@tanstack/react-form-devtools";
-import { pacerDevtoolsPlugin } from "@tanstack/react-pacer-devtools";
+import { formDevtoolsPlugin } from "@tanstack/react-form-devtools/production";
+import { createReactPanel, createReactPlugin } from "@tanstack/devtools-utils/react";
+import { PacerDevtoolsCore } from "@tanstack/pacer-devtools/production";
 import { ThemeDevtoolsPanel } from "@multiplatform.one/theme";
 import { storage } from "@multiplatform.one/store";
 import { useEffect, useState } from "react";
 import type { TanstackConfig } from "./CreateApp";
+import { devtoolsOpenHotkey, useShakeToOpen } from "./devtoolsTrigger";
 
 const devtoolsSettingsKey = "tanstack_devtools_settings";
 
+// @tanstack/react-pacer-devtools' /production entry is broken upstream
+// (0.7.x): it re-exports its panel from ReactPacerDevtools.js, which pulls
+// PacerDevtoolsCore from @tanstack/pacer-devtools' MAIN entry — the
+// NODE_ENV-gated one — so its "production" plugin silently mounts the no-op
+// core in a deployed bundle. Rebuild the plugin from the genuinely ungated
+// /production core instead. devtoolsTrigger.spec.ts pins the resolved core
+// as real (its unmount throws; the NoOp's is silent).
+const [PacerDevtoolsPanel] = createReactPanel(PacerDevtoolsCore);
+const [pacerDevtoolsPlugin] = createReactPlugin({
+  name: "TanStack Pacer",
+  Component: PacerDevtoolsPanel,
+});
+
 /**
  * Sync the resolved color scheme into the TanStack Devtools settings
  * stored via the shared storage adapter. The devtools shell reads this on mount and
@@ -36,7 +57,7 @@ export interface TanstackDevtoolsProps {
 /**
  * Lazily-loaded devtools shell. All heavy devtools dependencies
  * (`@tanstack/react-devtools`, `@tanstack/react-query-devtools`,
- * `@tanstack/react-form-devtools`, `@tanstack/react-pacer-devtools`,
+ * `@tanstack/react-form-devtools`, `@tanstack/pacer-devtools`,
  * and `ThemeDevtoolsPanel`) live here so they are code-split away
  * from the production bundle.
  */
@@ -108,6 +129,11 @@ export default function TanstackDevtoolsWrapper({
 
   const frappePlugin = useFrappePlugin();
 
+  // Shake-to-open (devicemotion) — the phone-friendly counterpart to the
+  // keyboard shortcut. Ships whenever the devtools mount unless the app
+  // opts out with `tanstack: { shakeToOpen: false }`.
+  useShakeToOpen(tanstackConfig.shakeToOpen !== false);
+
   const plugins = [
     {
       id: "react-query",
@@ -119,11 +145,29 @@ export default function TanstackDevtoolsWrapper({
     {
       id: "theme",
       name: "Theme",
+      // The panel opens focused on Theme, so a shake (or the hotkey) lands
+      // straight on the theme flipper — the whole point of the trigger is
+      // to check that everything is themable. `defaultOpen` seeds the tab
+      // only on first open, when no layout is persisted yet; once the user
+      // moves to another tab their choice is restored on later opens.
+      defaultOpen: true,
       render: (_el: HTMLElement, props: { theme: "dark" | "light" }) => (
         <ThemeDevtoolsPanel
           useUserScheme={tanstackConfig.useUserScheme}
           devtoolsTheme={props.theme}
           tamaguiConfig={tanstackConfig.tamaguiConfig}
+          // The accent channel. `ThemeDevtoolsPanel` has taken these three
+          // props all along and core passed none of them, so the panel's
+          // accent dropdown never rendered and its Randomize action skipped
+          // the colour — a control that is present in the component and
+          // unreachable through the only wrapper that mounts it. They are
+          // forwarded, not invented here: a theme colour is app state, so the
+          // app supplies the list, the current value and the setter, exactly
+          // as it already supplies `useUserScheme`. Undefined stays undefined,
+          // so an app that wires nothing sees the panel it sees today.
+          themeColors={tanstackConfig.themeColors}
+          currentThemeColor={tanstackConfig.currentThemeColor}
+          onThemeColorChange={tanstackConfig.onThemeColorChange}
         />
       ),
     },
@@ -136,7 +180,7 @@ export default function TanstackDevtoolsWrapper({
       config={{
         defaultOpen: false,
         triggerHidden: true,
-        openHotkey: ["CtrlOrMeta", "`"],
+        openHotkey: [...devtoolsOpenHotkey],
         theme: resolvedScheme,
       }}
       plugins={plugins}