@mandujs/core 0.54.17 → 0.54.19

package/src/bundler/dev.ts

@@ -21,12 +21,13 @@ import {
   scanFileImports,
   DEFAULT_MAX_CLOSURE_DEPTH,
 } from "./reverse-import-graph";
-import path from "path";
-import fs from "fs";
-import { LRUCache } from "../utils/lru-cache";
-import { registerCacheSize, unregisterCacheSize } from "../observability/metrics";
-
-/**
+import path from "path";
+import fs from "fs";
+import { LRUCache } from "../utils/lru-cache";
+import { registerCacheSize, unregisterCacheSize } from "../observability/metrics";
+export { generateFastRefreshPreamble } from "./fast-refresh-preamble";
+
+/**
  * #184: 공통 디렉토리 변경 시 사용하는 sentinel.
  * `onSSRChange`에 특정 파일 경로 대신 이 상수를 전달하면 "전체 SSR 레지스트리 invalidate" 의미.
  */
@@ -135,12 +136,14 @@ export interface RebuildResult {
   error?: string;
 }
 
-export interface DevBundler {
-  /** 초기 빌드 결과 */
-  initialBuild: BundleResult;
-  /** 파일 감시 중지 */
-  close: () => void;
-}
+export interface DevBundler {
+  /** 초기 빌드 결과 */
+  initialBuild: BundleResult;
+  /** Reverse import graph initial seed completion for deterministic tests. */
+  reverseGraphReady: Promise<void>;
+  /** 파일 감시 중지 */
+  close: () => void;
+}
 
 /**
  * #180: 파일 경로 비교를 위한 정규화.
@@ -647,7 +650,8 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
   // surface typed-only stubs that have no source yet); misses simply
   // keep the legacy "silent drop" behavior so no project is made
   // worse by turning this on.
-  const reverseGraph = new ReverseImportGraph();
+  const reverseGraph = new ReverseImportGraph();
+  let reverseGraphSeedPromise: Promise<void> | null = null;
 
   /**
    * Re-scan a single file's imports and update its row in the
@@ -1239,11 +1243,15 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
    * stay silent. Dispatch is idempotent — each root is touched at
    * most once per change via the `dispatched` set.
    */
-  const dispatchByTransitiveImporters = async (
-    changedFile: string,
-  ): Promise<number> => {
-    const absChanged = path.resolve(rootDir, changedFile);
-    // Refresh the changed file's OWN imports first. A leaf edit can
+  const dispatchByTransitiveImporters = async (
+    changedFile: string,
+  ): Promise<number> => {
+    const absChanged = path.resolve(rootDir, changedFile);
+    if (reverseGraphSeedPromise) {
+      await reverseGraphSeedPromise;
+    }
+
+    // Refresh the changed file's OWN imports first. A leaf edit can
     // legitimately add or remove imports (e.g. switching a barrel
     // from `./en` to `./ko`); the reverse graph must track that so
     // the NEXT unknown-file change uses the correct set.
@@ -1655,16 +1663,17 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
   // and the first user edit can't race the seed (first event goes
   // through the 100 ms debounce, by which point the scan has finished
   // for any realistic project size).
-  seedReverseGraph().catch((err) => {
-    console.warn(
-      "[Mandu HMR] reverse import-graph seed skipped:",
-      err instanceof Error ? err.message : String(err),
-    );
-  });
-
-  return {
-    initialBuild,
-    close: () => {
+  reverseGraphSeedPromise = seedReverseGraph().catch((err) => {
+    console.warn(
+      "[Mandu HMR] reverse import-graph seed skipped:",
+      err instanceof Error ? err.message : String(err),
+    );
+  });
+
+  return {
+    initialBuild,
+    reverseGraphReady: reverseGraphSeedPromise,
+    close: () => {
       // B6: clear all per-file timers to release event-loop refs.
       // Phase 17 — `LRUCache.clear()` fires the registered `onEvict`
       // (`clearTimeout(timer)`) for every entry before dropping them,
@@ -2208,90 +2217,8 @@ export function createHMRServer(
   };
 }
 
-/**
- * Phase 7.1 B-3 — HTML preamble for React Fast Refresh.
- *
- * Emitted by the SSR renderer in dev mode, **before** any island JS
- * evaluates. Two concerns, one <script>:
- *
- *   1. Install inert stubs for `$RefreshReg$` / `$RefreshSig$` on
- *      `window`. Bun's `reactFastRefresh: true` transform inserts calls
- *      to these at the top of every transformed module; if they are
- *      undefined when the module body runs, we get a runtime error and
- *      the island never hydrates. Vite's preamble does the same inline
- *      stub install for the same reason.
- *
- *   2. Fire a dynamic `import()` of the bundled glue (`_fast-refresh-
- *      runtime.js`), which in turn `await`s the real `react-refresh/
- *      runtime`, installs `window.__MANDU_HMR__`, and upgrades the
- *      stubs to live wrappers that forward to the refresh runtime. The
- *      race between "module evaluates and calls `$RefreshReg$`" and
- *      "glue has upgraded the stubs" is benign — registrations that
- *      land on the stub are simply no-ops, which at worst means the
- *      very first mount isn't tracked. Subsequent hot swaps land on
- *      the live wrappers and work normally.
- *
- * The emitted script is **inline** (no `type="module"`, no external
- * src). This is deliberate: the stubs must exist before *any* module
- * script runs, and inline execution blocks the parser. The dynamic
- * import inside the inline script is non-blocking so we don't stall
- * First Contentful Paint.
- *
- * CSP note: the inline <script> uses no `eval` or `new Function`; it
- * only calls `Object.assign`, defines functions, and initiates an
- * `import()`. All of these are permitted under `script-src 'self'
- * 'unsafe-inline'` which is Mandu's default dev CSP (production CSP
- * forbids `unsafe-inline`, but this preamble is dev-only).
- *
- * `glueUrl` and `runtimeUrl` come from the build manifest's
- * `shared.fastRefresh` block (populated only in dev). Both must be
- * absolute URLs served from the same origin as the HTML, which our
- * bundler always guarantees (`/.mandu/client/...`).
- */
-export function generateFastRefreshPreamble(
-  glueUrl: string,
-  runtimeUrl: string,
-): string {
-  // Both URLs must be non-empty. If either is missing (e.g. vendor
-  // shim build failed), the caller (ssr.ts) should skip this preamble
-  // entirely — defensive guard here keeps the output valid regardless.
-  if (!glueUrl || !runtimeUrl) {
-    return `<script>/* Mandu Fast Refresh: missing runtime assets, preamble skipped */</script>`;
-  }
-  // JSON.stringify escapes the URLs safely for inline `<script>`:
-  //   - quotes produce a valid JS string literal
-  //   - forward-slashes / backslashes are handled
-  // We also `split('</')` to avoid a stray `</script>` sequence in the
-  // URL bytes breaking the enclosing tag. This is the same defense
-  // Vite uses in its own preamble emitter.
-  const glueLit = JSON.stringify(glueUrl).split("</").join('<"+"/');
-  const runtimeLit = JSON.stringify(runtimeUrl).split("</").join('<"+"/');
-  return `<script>
-// Phase 7.1 B-3 React Fast Refresh preamble (Mandu dev-only)
-(function () {
-  if (typeof window === "undefined") return;
-  // Install inert stubs so transformed modules that run BEFORE the
-  // async runtime upgrade don't hit ReferenceError on $RefreshReg$.
-  if (!window.$RefreshReg$) window.$RefreshReg$ = function () {};
-  if (!window.$RefreshSig$) window.$RefreshSig$ = function () { return function (t) { return t; }; };
-  // Async-load the glue; failures are reported but never throw out of
-  // the preamble — a missing runtime degrades to full-reload HMR.
-  import(${glueLit})
-    .then(function (mod) {
-      var runtimeImport = function () { return import(${runtimeLit}); };
-      if (mod && typeof mod.installGlobal === "function") {
-        return mod.installGlobal({ runtimeImport: runtimeImport });
-      }
-    })
-    .catch(function (err) {
-      console.error("[Mandu Fast Refresh] preamble failed:", err);
-    });
-})();
-</script>`;
-}
-
-/**
- * HMR 클라이언트 스크립트 생성
+/**
+ * HMR 클라이언트 스크립트 생성
  * 브라우저에서 실행되어 HMR 서버와 연결.
  *
  * Phase 7.0 R1 Agent C additions:

package/src/bundler/fast-refresh-preamble.ts

@@ -0,0 +1,47 @@
+/**
+ * Small runtime-safe Fast Refresh preamble helper.
+ *
+ * Keep this separate from `bundler/dev.ts`: SSR runtimes import the helper
+ * while edge bundles must not pull the dev bundler, build graph, or TypeScript
+ * compiler into production worker output.
+ */
+export function generateFastRefreshPreamble(
+  glueUrl: string,
+  runtimeUrl: string,
+): string {
+  // Both URLs must be non-empty. If either is missing (e.g. vendor
+  // shim build failed), the caller should skip this preamble entirely.
+  if (!glueUrl || !runtimeUrl) {
+    return `<script>/* Mandu Fast Refresh: missing runtime assets, preamble skipped */</script>`;
+  }
+  // JSON.stringify escapes the URLs safely for inline `<script>`:
+  //   - quotes produce a valid JS string literal
+  //   - forward-slashes / backslashes are handled
+  // We also `split('</')` to avoid a stray `</script>` sequence in the
+  // URL bytes breaking the enclosing tag. This is the same defense
+  // Vite uses in its own preamble emitter.
+  const glueLit = JSON.stringify(glueUrl).split("</").join('<"+"/');
+  const runtimeLit = JSON.stringify(runtimeUrl).split("</").join('<"+"/');
+  return `<script>
+// Phase 7.1 B-3 React Fast Refresh preamble (Mandu dev-only)
+(function () {
+  if (typeof window === "undefined") return;
+  // Install inert stubs so transformed modules that run BEFORE the
+  // async runtime upgrade don't hit ReferenceError on $RefreshReg$.
+  if (!window.$RefreshReg$) window.$RefreshReg$ = function () {};
+  if (!window.$RefreshSig$) window.$RefreshSig$ = function () { return function (t) { return t; }; };
+  // Async-load the glue; failures are reported but never throw out of
+  // the preamble — a missing runtime degrades to full-reload HMR.
+  import(${glueLit})
+    .then(function (mod) {
+      var runtimeImport = function () { return import(${runtimeLit}); };
+      if (mod && typeof mod.installGlobal === "function") {
+        return mod.installGlobal({ runtimeImport: runtimeImport });
+      }
+    })
+    .catch(function (err) {
+      console.error("[Mandu Fast Refresh] preamble failed:", err);
+    });
+})();
+</script>`;
+}

package/src/bundler/index.ts

@@ -4,7 +4,8 @@
  */
 
 export * from "./types";
-export * from "./build";
-export * from "./dev";
+export * from "./build";
+export * from "./client-boundary-transform";
+export * from "./dev";
 export * from "./css";
 export * from "./plugins";

package/src/bundler/manifest-schema.ts

@@ -173,6 +173,15 @@ const PartialEntrySchema = z.object({
   priority: PrioritySchema,
 });
 
+const BoundaryEntrySchema = z.object({
+  route: z.string().min(1),
+  js: safeManduUrl("boundaries[].js"),
+  module: z.string().min(1),
+  exportName: z.string().min(1),
+  priority: PrioritySchema,
+  hydrate: z.string().min(1),
+});
+
 const FastRefreshSchema = z.object({
   runtime: safeManduUrl("shared.fastRefresh.runtime"),
   glue: safeManduUrl("shared.fastRefresh.glue"),
@@ -229,6 +238,7 @@ export const BundleManifestSchema = z
     bundles: z.record(z.string(), BundleEntrySchema),
     islands: z.record(z.string(), IslandEntrySchema).optional(),
     partials: z.record(z.string(), PartialEntrySchema).optional(),
+    boundaries: z.record(z.string(), BoundaryEntrySchema).optional(),
     shared: SharedSchema,
     importMap: ImportMapSchema.optional(),
   })

package/src/bundler/types.ts

@@ -77,8 +77,26 @@ export interface BundleManifest {
       priority: "immediate" | "visible" | "idle" | "interaction";
     }
   >;
-  /** 공유 청크 */
-  shared: {
+  /** Compiler-owned client boundary bundles keyed by boundary id. */
+  boundaries?: Record<
+    string,
+    {
+      /** Owning route id */
+      route: string;
+      /** JavaScript bundle path */
+      js: string;
+      /** Source client module */
+      module: string;
+      /** Client export name */
+      exportName: string;
+      /** Hydration priority */
+      priority: "immediate" | "visible" | "idle" | "interaction";
+      /** Hydration mode emitted into data-hydrate */
+      hydrate: string;
+    }
+  >;
+  /** 공유 청크 */
+  shared: {
     /** Hydration 런타임 */
     runtime: string;
     /** React 번들 경로 */

package/src/client/__tests__/props-serialization.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "bun:test";
+import { deserializeProps, serializeProps } from "../props-serialization";
+
+describe("props serialization", () => {
+  it("roundtrips complex browser hydration props through the shared deserializer", () => {
+    const input = {
+      date: new Date("2026-05-23T00:00:00.000Z"),
+      map: new Map<unknown, unknown>([
+        ["count", 3],
+        ["nested", { ok: true }],
+      ]),
+      set: new Set<unknown>(["a", "b"]),
+      url: new URL("https://mandu.dev/docs?phase=4"),
+      missing: undefined,
+      nested: {
+        list: [1, undefined, { value: "x" }],
+      },
+    };
+
+    const output = deserializeProps(serializeProps(input));
+
+    expect(output.date).toBeInstanceOf(Date);
+    expect((output.date as Date).toISOString()).toBe("2026-05-23T00:00:00.000Z");
+    expect(output.map).toBeInstanceOf(Map);
+    expect((output.map as Map<unknown, unknown>).get("count")).toBe(3);
+    expect((output.map as Map<unknown, unknown>).get("nested")).toEqual({ ok: true });
+    expect(output.set).toBeInstanceOf(Set);
+    expect(Array.from(output.set as Set<unknown>)).toEqual(["a", "b"]);
+    expect(output.url).toBeInstanceOf(URL);
+    expect((output.url as URL).href).toBe("https://mandu.dev/docs?phase=4");
+    expect(Object.prototype.hasOwnProperty.call(output, "missing")).toBe(true);
+    expect(output.missing).toBeUndefined();
+    expect(output.nested).toEqual({
+      list: [1, undefined, { value: "x" }],
+    });
+  });
+});

package/src/client/hydrate.ts

@@ -16,8 +16,8 @@
  *   2. Unit tests can import it under happy-dom/JSDOM without triggering
  *      global mutation (no `document.querySelectorAll` on module eval).
  *
- * The bundler-generated runtime (`bundler/build.ts::generateRuntimeSource`)
- * delegates strategy selection to `scheduleHydration()` here — SSR emits the
+ * The bundled runtime entry (`client/runtime-entry.ts`)
+ * delegates strategy selection to `scheduleHydration()` here — SSR emits the
  * `data-hydrate` attribute, the runtime reads it and dispatches.
  *
  * Design contract:

package/src/client/index.ts

@@ -168,7 +168,7 @@ import { Link, NavLink } from "./Link";
 
 /**
  * Mandu Client namespace
- * v0.8.0: Hydration is handled automatically (generateRuntimeSource)
+ * v0.8.0: Hydration is handled automatically (runtime-entry)
  * Note: Use `ManduClient` to avoid conflict with other Mandu exports
  */
 export const ManduClient = {

package/src/client/props-serialization.ts

@@ -0,0 +1,233 @@
+/**
+ * Browser-safe Mandu props serialization.
+ *
+ * This module intentionally has no DOM, Bun, or Node imports. Runtime entry
+ * code may read from the document, but serialization semantics live here.
+ */
+
+const TYPE_MARKERS = {
+  UNDEFINED: "\x00_",
+  DATE: "\x00D",
+  URL: "\x00U",
+  REGEXP: "\x00R",
+  MAP: "\x00M",
+  SET: "\x00S",
+  REF: "\x00$",
+  BIGINT: "\x00B",
+  SYMBOL: "\x00Y",
+  ERROR: "\x00E",
+} as const;
+
+interface SerializeContext {
+  seen: Map<object, number>;
+  refs: object[];
+}
+
+interface DeserializeContext {
+  refs: unknown[];
+}
+
+export function serializeProps(props: Record<string, unknown>): string {
+  const ctx: SerializeContext = { seen: new Map(), refs: [] };
+  return JSON.stringify(serialize(props, ctx));
+}
+
+function serialize(value: unknown, ctx: SerializeContext): unknown {
+  if (value === null) return null;
+  if (value === undefined) return TYPE_MARKERS.UNDEFINED;
+
+  if (typeof value === "boolean" || typeof value === "number") {
+    return value;
+  }
+
+  if (typeof value === "string") {
+    return value.startsWith("\x00") ? "\x00\x00" + value : value;
+  }
+
+  if (typeof value === "bigint") {
+    return TYPE_MARKERS.BIGINT + value.toString();
+  }
+
+  if (typeof value === "symbol") {
+    return TYPE_MARKERS.SYMBOL + (value.description ?? "");
+  }
+
+  if (typeof value === "function") {
+    console.warn("[Mandu Serialize] Functions cannot be serialized, skipping");
+    return undefined;
+  }
+
+  if (typeof value === "object") {
+    const existing = ctx.seen.get(value);
+    if (existing !== undefined) {
+      return TYPE_MARKERS.REF + existing;
+    }
+
+    const idx = ctx.refs.length;
+    ctx.seen.set(value, idx);
+    ctx.refs.push(value);
+  }
+
+  if (value instanceof Date) {
+    return TYPE_MARKERS.DATE + value.toISOString();
+  }
+
+  if (value instanceof URL) {
+    return TYPE_MARKERS.URL + value.href;
+  }
+
+  if (value instanceof RegExp) {
+    return TYPE_MARKERS.REGEXP + value.toString();
+  }
+
+  if (value instanceof Error) {
+    return [
+      TYPE_MARKERS.ERROR,
+      value.name,
+      value.message,
+      value.stack ?? "",
+    ];
+  }
+
+  if (value instanceof Map) {
+    const entries: [unknown, unknown][] = [];
+    for (const [key, nested] of value.entries()) {
+      entries.push([serialize(key, ctx), serialize(nested, ctx)]);
+    }
+    return [TYPE_MARKERS.MAP, ...entries];
+  }
+
+  if (value instanceof Set) {
+    const items: unknown[] = [];
+    for (const item of value) {
+      items.push(serialize(item, ctx));
+    }
+    return [TYPE_MARKERS.SET, ...items];
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((item) => serialize(item, ctx));
+  }
+
+  const result: Record<string, unknown> = {};
+  for (const [key, nested] of Object.entries(value as object)) {
+    const serialized = serialize(nested, ctx);
+    if (serialized !== undefined) {
+      result[key] = serialized;
+    }
+  }
+  return result;
+}
+
+export function deserializeProps(json: string): Record<string, unknown> {
+  const ctx: DeserializeContext = { refs: [] };
+  const parsed = JSON.parse(json);
+  return deserialize(parsed, ctx) as Record<string, unknown>;
+}
+
+function deserialize(value: unknown, ctx: DeserializeContext): unknown {
+  if (value === null) return null;
+
+  if (typeof value === "string") {
+    if (value === TYPE_MARKERS.UNDEFINED) return undefined;
+    if (value.startsWith("\x00\x00")) return value.slice(2);
+    if (value.startsWith(TYPE_MARKERS.DATE)) return new Date(value.slice(2));
+    if (value.startsWith(TYPE_MARKERS.URL)) return new URL(value.slice(2));
+    if (value.startsWith(TYPE_MARKERS.REGEXP)) {
+      const str = value.slice(2);
+      const match = str.match(/^\/(.*)\/([gimsuy]*)$/);
+      return match ? new RegExp(match[1], match[2]) : str;
+    }
+    if (value.startsWith(TYPE_MARKERS.BIGINT)) return BigInt(value.slice(2));
+    if (value.startsWith(TYPE_MARKERS.SYMBOL)) return Symbol(value.slice(2));
+    if (value.startsWith(TYPE_MARKERS.REF)) {
+      return ctx.refs[parseInt(value.slice(2), 10)];
+    }
+    return value;
+  }
+
+  if (typeof value === "boolean" || typeof value === "number") {
+    return value;
+  }
+
+  if (Array.isArray(value)) {
+    const marker = value[0];
+
+    if (marker === TYPE_MARKERS.ERROR) {
+      const [, name, message, stack] = value as [string, string, string, string];
+      const error = new Error(message);
+      error.name = name;
+      if (stack) error.stack = stack;
+      ctx.refs.push(error);
+      return error;
+    }
+
+    if (marker === TYPE_MARKERS.MAP) {
+      const map = new Map();
+      ctx.refs.push(map);
+      for (let i = 1; i < value.length; i++) {
+        const [key, nested] = value[i] as [unknown, unknown];
+        map.set(deserialize(key, ctx), deserialize(nested, ctx));
+      }
+      return map;
+    }
+
+    if (marker === TYPE_MARKERS.SET) {
+      const set = new Set();
+      ctx.refs.push(set);
+      for (let i = 1; i < value.length; i++) {
+        set.add(deserialize(value[i], ctx));
+      }
+      return set;
+    }
+
+    const arr: unknown[] = [];
+    ctx.refs.push(arr);
+    for (const item of value) {
+      arr.push(deserialize(item, ctx));
+    }
+    return arr;
+  }
+
+  if (typeof value === "object") {
+    const obj: Record<string, unknown> = {};
+    ctx.refs.push(obj);
+    for (const [key, nested] of Object.entries(value)) {
+      obj[key] = deserialize(nested, ctx);
+    }
+    return obj;
+  }
+
+  return value;
+}
+
+export function isSerializable(value: unknown): boolean {
+  if (value === null || value === undefined) return true;
+
+  const type = typeof value;
+  if (type === "boolean" || type === "number" || type === "string" || type === "bigint") {
+    return true;
+  }
+
+  if (type === "function" || type === "symbol") {
+    return false;
+  }
+
+  if (value instanceof Date || value instanceof URL || value instanceof RegExp) {
+    return true;
+  }
+
+  if (value instanceof Map || value instanceof Set) {
+    return true;
+  }
+
+  if (Array.isArray(value)) {
+    return value.every(isSerializable);
+  }
+
+  if (type === "object") {
+    return Object.values(value as object).every(isSerializable);
+  }
+
+  return false;
+}