@mandujs/core 0.21.0 → 0.22.0

package/src/client/router.ts

@@ -4,6 +4,7 @@
  */
 
 import type { ReactNode } from "react";
+import { startTransition } from "react";
 import {
   getManduData,
   getManduRoute,
@@ -36,11 +37,11 @@ export interface RouterState {
   navigation: NavigationState;
 }
 
-export interface ActionResult {
-  ok: boolean;
-  actionData?: unknown;
-  loaderData?: unknown;
-}
+export interface ActionResult {
+  ok: boolean;
+  actionData?: unknown;
+  loaderData?: unknown;
+}
 
 export interface NavigateOptions {
   /** history.replaceState 사용 여부 */
@@ -224,7 +225,7 @@ let activeNavigationController: AbortController | null = null;
 /**
  * 페이지 네비게이션
  */
-export async function navigate(
+export async function navigate(
   to: string,
   options: NavigateOptions = {}
 ): Promise<void> {
@@ -251,36 +252,36 @@ export async function navigate(
     // shouldRevalidate 체크 — false면 fetch 없이 URL만 변경
     if (!skipRevalidation && globalShouldRevalidate) {
       const currentUrl = new URL(window.location.href);
-      const shouldFetch = globalShouldRevalidate({
-        currentUrl,
-        nextUrl: url,
-        defaultShouldRevalidate: true,
-      });
-      if (!shouldFetch) {
-        const currentState = getRouterStateInternal();
-        const nextRoute = currentState.currentRoute
-          ? {
-              ...currentState.currentRoute,
-              params: extractParamsFromPath(currentState.currentRoute.pattern, url.pathname),
-            }
-          : null;
-        const historyState = nextRoute
-          ? { routeId: nextRoute.id, params: nextRoute.params }
-          : null;
-        if (replace) {
-          history.replaceState(historyState, "", to);
-        } else {
-          history.pushState(historyState, "", to);
-        }
-        setRouterStateInternal({
-          ...currentState,
-          currentRoute: nextRoute,
-          actionData: undefined,
-          navigation: { state: "idle" },
-        });
-        notifyListeners();
-        if (scroll) window.scrollTo(0, 0);
-        return;
+      const shouldFetch = globalShouldRevalidate({
+        currentUrl,
+        nextUrl: url,
+        defaultShouldRevalidate: true,
+      });
+      if (!shouldFetch) {
+        const currentState = getRouterStateInternal();
+        const nextRoute = currentState.currentRoute
+          ? {
+              ...currentState.currentRoute,
+              params: extractParamsFromPath(currentState.currentRoute.pattern, url.pathname),
+            }
+          : null;
+        const historyState = nextRoute
+          ? { routeId: nextRoute.id, params: nextRoute.params }
+          : null;
+        if (replace) {
+          history.replaceState(historyState, "", to);
+        } else {
+          history.pushState(historyState, "", to);
+        }
+        setRouterStateInternal({
+          ...currentState,
+          currentRoute: nextRoute,
+          actionData: undefined,
+          navigation: { state: "idle" },
+        });
+        notifyListeners();
+        if (scroll) window.scrollTo(0, 0);
+        return;
       }
     }
 
@@ -565,34 +566,34 @@ export async function submitAction(
     if (controller.signal.aborted) return { ok: false };
 
     // Revalidation: 서버가 loader를 재실행해서 fresh data를 보내줬으면 갱신
-    const nextActionData = result._revalidated ? result.actionData : result;
-
-    if (result._revalidated && result.loaderData !== undefined) {
-      setRouterStateInternal({
-        ...getRouterStateInternal(),
-        loaderData: result.loaderData,
-        actionData: nextActionData,
-        navigation: { state: "idle" },
-      });
+    const nextActionData = result._revalidated ? result.actionData : result;
+
+    if (result._revalidated && result.loaderData !== undefined) {
+      setRouterStateInternal({
+        ...getRouterStateInternal(),
+        loaderData: result.loaderData,
+        actionData: nextActionData,
+        navigation: { state: "idle" },
+      });
 
       const currentRoute = getRouterStateInternal().currentRoute;
       if (currentRoute) {
         setServerData(currentRoute.id, result.loaderData);
       }
     } else {
-      setRouterStateInternal({
-        ...getRouterStateInternal(),
-        actionData: nextActionData,
-        navigation: { state: "idle" },
-      });
+      setRouterStateInternal({
+        ...getRouterStateInternal(),
+        actionData: nextActionData,
+        navigation: { state: "idle" },
+      });
     }
 
-      notifyListeners();
-      return {
-        ok: response.ok,
-        actionData: nextActionData,
-        loaderData: result._revalidated ? result.loaderData as unknown : undefined,
-      };
+      notifyListeners();
+      return {
+        ok: response.ok,
+        actionData: nextActionData,
+        loaderData: result._revalidated ? result.loaderData as unknown : undefined,
+      };
   } catch (error) {
     if (controller.signal.aborted) return { ok: false };
 
@@ -620,6 +621,137 @@ export function getActionData<T = unknown>(): T | undefined {
 
 let initialized = false;
 
+/**
+ * Phase 7.3 L-01 — HDR loader payload shape predicate.
+ *
+ * Exported as an escape hatch for unit tests. Accepts only:
+ *   - `null` (loader explicitly returned "no data" — a valid outcome).
+ *   - plain `object` (the typical loader return value shape).
+ * Rejects:
+ *   - `undefined` (we require the server contract to emit `null` explicitly
+ *     when there is no data, mirroring `Response.json` behaviour).
+ *   - primitives (`string`, `number`, `boolean`, `symbol`, `bigint`).
+ *   - `Array` — React loader data is always a bag-of-props, never a bare
+ *     array. An array payload signals the server contract changed under us.
+ *
+ * This is DEFENSE-IN-DEPTH: the HDR response is always same-origin, so an
+ * attacker cannot inject here without already controlling the server. The
+ * predicate catches the real-world failure mode: a skew between server +
+ * client versions during a rolling deploy (cached old client fetches new
+ * `_data=1` response with a reshape), or a loader that drifted to return
+ * a primitive by mistake.
+ *
+ * We DO allow unknown object keys — loaders legitimately return arbitrary
+ * shapes. We only check the outer container.
+ *
+ * @internal exposed for `__tests__/hdr-l-fixes.test.ts`
+ */
+export function isValidHDRLoaderData(value: unknown): value is object | null {
+  if (value === null) return true;
+  if (typeof value !== "object") return false;
+  // Arrays are `typeof === "object"` — reject them explicitly.
+  if (Array.isArray(value)) return false;
+  return true;
+}
+
+/**
+ * Phase 7.2 — HDR (Hot Data Revalidation) hook.
+ *
+ * The dev-time HMR client script (see `bundler/dev.ts`
+ * `generateHMRClientScript`) calls this when a `.slot.ts` file
+ * changes for the currently-rendered route. We update the router's
+ * loader data inside `React.startTransition` so the component tree
+ * re-renders with new props while form inputs, scroll position, and
+ * focused elements all survive.
+ *
+ * The global is installed by `initializeRouter()` so dev and prod
+ * share the same boot path; in prod builds the HMR script is not
+ * emitted and the global is simply never called.
+ *
+ * Exposed on `window` because the HMR client script (emitted as a
+ * raw string) has no module system. Typed via `window-state.ts` if
+ * we ever lift the typing, but inline here for now.
+ *
+ * Phase 7.3 L-01: the incoming `loaderData` is schema-checked via
+ * `isValidHDRLoaderData` before we commit it to router state. This is
+ * defense-in-depth — the HDR response is same-origin and already
+ * trusted, but a version skew between server + client (cached stale
+ * client fetching a reshape loader) would otherwise crash React with
+ * an unhelpful `undefined.x` inside a fiber. On rejection we log a
+ * descriptive warning and drop the update; the next navigation or
+ * full reload will resynchronize.
+ */
+function applyHDRUpdate(routeId: string, loaderData: unknown): void {
+  const current = getRouterStateInternal();
+  const route = current.currentRoute;
+  if (!route || route.id !== routeId) {
+    // Route mismatch — the user navigated away between the
+    // slot-refetch broadcast and the fetch response. Safe to drop.
+    return;
+  }
+  // Phase 7.3 L-01: validate the loaderData shape. On failure keep the
+  // existing `loaderData` and warn so the developer notices the
+  // contract drift immediately (instead of a cryptic React crash).
+  if (!isValidHDRLoaderData(loaderData)) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      "[Mandu HDR] applyHDRUpdate rejected a loader payload that was not a plain object or null. " +
+        "This usually signals a server/client version skew — a full reload will resynchronize. " +
+        `Received: ${Array.isArray(loaderData) ? "array" : typeof loaderData}`,
+    );
+    return;
+  }
+  const nextState: RouterState = {
+    currentRoute: route,
+    loaderData,
+    actionData: current.actionData,
+    navigation: current.navigation,
+  };
+  // startTransition wraps the update so React can interrupt it if
+  // more urgent updates come in, and (crucially for HDR) does NOT
+  // trigger the "input's state is inconsistent" tearing that a plain
+  // setState would. React 19 exports startTransition as a top-level
+  // API so it's always available when the router is on the page.
+  const apply = () => {
+    setRouterStateInternal(nextState);
+    setServerData(routeId, loaderData);
+    notifyListeners();
+  };
+  try {
+    startTransition(apply);
+  } catch {
+    // Defensive: if for any reason startTransition throws (e.g. a
+    // non-React 19 build ends up with the router on the page), fall
+    // back to a direct apply. Prop changes still propagate; only
+    // the tearing protection is lost.
+    apply();
+  }
+}
+
+/**
+ * Phase 7.3 L-03 — dev-only detection for the HDR revalidate hook.
+ *
+ * The router module is bundled into both dev and prod client bundles.
+ * We want `window.__MANDU_ROUTER_REVALIDATE__` installed ONLY in dev,
+ * because in prod no HMR client script is present to call it — so the
+ * global is pure attack surface (an XSS payload could hijack it to
+ * coerce the router into rendering arbitrary loader shapes).
+ *
+ * Mandu's bundler (`packages/core/src/bundler/build.ts`) injects
+ * `define: { "process.env.NODE_ENV": JSON.stringify(NODE_ENV) }` into
+ * every client bundle, so `process.env.NODE_ENV` is a compile-time
+ * constant in the browser. When `NODE_ENV === "production"` the `if`
+ * body below is dead-code-eliminated by Bun's minifier.
+ *
+ * Tested in `__tests__/hdr-l-fixes.test.ts` against both mocked envs.
+ */
+function shouldInstallHDRHook(): boolean {
+  // typeof-guard so tests that run without a `process` global (pure
+  // happy-dom) don't blow up.
+  if (typeof process === "undefined") return true;
+  return process.env?.NODE_ENV !== "production";
+}
+
 /**
  * 라우터 초기화
  */
@@ -637,6 +769,18 @@ export function initializeRouter(): void {
   // 링크 클릭 이벤트 위임
   document.addEventListener("click", handleLinkClick);
 
+  // Phase 7.3 L-03 — expose HDR revalidate hook ONLY in dev builds.
+  // The prod client bundle has `process.env.NODE_ENV === "production"`
+  // inlined at build time (see `bundler/build.ts` define option), so
+  // the entire install block is eliminated from production output.
+  // This closes the XSS amplification vector described in the Phase
+  // 7.2 security audit (docs/security/phase-7-2-audit.md L-03).
+  if (shouldInstallHDRHook()) {
+    (window as unknown as {
+      __MANDU_ROUTER_REVALIDATE__?: (routeId: string, loaderData: unknown) => void;
+    }).__MANDU_ROUTER_REVALIDATE__ = applyHDRUpdate;
+  }
+
   console.log("[Mandu Router] Initialized");
 }
 
@@ -660,6 +804,15 @@ export function cleanupRouter(): void {
   document.removeEventListener("click", handleLinkClick);
   listeners.current.clear();
   initialized = false;
+  // Phase 7.3 L-03: also remove the HDR hook so subsequent
+  // re-initialization after a teardown starts from a clean slate.
+  if (typeof window !== "undefined") {
+    try {
+      delete (window as unknown as { __MANDU_ROUTER_REVALIDATE__?: unknown }).__MANDU_ROUTER_REVALIDATE__;
+    } catch {
+      // some browsers refuse `delete` on globals; best-effort is fine.
+    }
+  }
 }
 
 // 자동 초기화 (DOM 준비 시)
@@ -670,3 +823,8 @@ if (typeof window !== "undefined") {
     initializeRouter();
   }
 }
+
+// Phase 7.3 L-01: export `applyHDRUpdate` itself for unit tests so we
+// can exercise the schema-check path directly without round-tripping
+// through `window.__MANDU_ROUTER_REVALIDATE__`.
+export { applyHDRUpdate as _testOnly_applyHDRUpdate };