@mandujs/core 0.13.2 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.13.2",
+  "version": "0.16.0",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",

package/src/client/Link.tsx

@@ -1,227 +1,234 @@
-/**
- * Mandu Link Component 🔗
- * Client-side 네비게이션을 위한 Link 컴포넌트
- */
-
-import React, {
-  type AnchorHTMLAttributes,
-  type MouseEvent,
-  type ReactNode,
-  useCallback,
-  useEffect,
-  useRef,
-} from "react";
-import { navigate, prefetch } from "./router";
-
-export interface LinkProps
-  extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
-  /** 이동할 URL */
-  href: string;
-  /** history.replaceState 사용 여부 */
-  replace?: boolean;
-  /** 마우스 hover 시 prefetch 여부 */
-  prefetch?: boolean;
-  /** 스크롤 위치 복원 여부 (기본: true) */
-  scroll?: boolean;
-  /** 자식 요소 */
-  children?: ReactNode;
-}
-
-/**
- * Client-side 네비게이션 Link 컴포넌트
- *
- * @example
- * ```tsx
- * import { Link } from "@mandujs/core/client";
- *
- * // 기본 사용
- * <Link href="/about">About</Link>
- *
- * // Prefetch 활성화
- * <Link href="/users" prefetch>Users</Link>
- *
- * // Replace 모드 (뒤로가기 히스토리 없음)
- * <Link href="/login" replace>Login</Link>
- * ```
- */
-export function Link({
-  href,
-  replace = false,
-  prefetch: shouldPrefetch = false,
-  scroll = true,
-  children,
-  onClick,
-  onMouseEnter,
-  onFocus,
-  ...rest
-}: LinkProps): React.ReactElement {
-  const prefetchedRef = useRef(false);
-
-  // 클릭 핸들러
-  const handleClick = useCallback(
-    (event: MouseEvent<HTMLAnchorElement>) => {
-      // 사용자 정의 onClick 먼저 실행
-      onClick?.(event);
-
-      // 기본 동작 방지 조건
-      if (
-        event.defaultPrevented ||
-        event.button !== 0 ||
-        event.metaKey ||
-        event.altKey ||
-        event.ctrlKey ||
-        event.shiftKey
-      ) {
-        return;
-      }
-
-      // 외부 링크 체크
-      try {
-        const url = new URL(href, window.location.origin);
-        if (url.origin !== window.location.origin) {
-          return; // 외부 링크는 기본 동작
-        }
-      } catch {
-        return;
-      }
-
-      // Client-side 네비게이션
-      event.preventDefault();
-      navigate(href, { replace, scroll });
-    },
-    [href, replace, scroll, onClick]
-  );
-
-  // Prefetch 실행
-  const doPrefetch = useCallback(() => {
-    if (!shouldPrefetch || prefetchedRef.current) return;
-
-    try {
-      const url = new URL(href, window.location.origin);
-      if (url.origin === window.location.origin) {
-        prefetch(href);
-        prefetchedRef.current = true;
-      }
-    } catch {
-      // 무시
-    }
-  }, [href, shouldPrefetch]);
-
-  // 마우스 hover 핸들러
-  const handleMouseEnter = useCallback(
-    (event: MouseEvent<HTMLAnchorElement>) => {
-      onMouseEnter?.(event);
-      doPrefetch();
-    },
-    [onMouseEnter, doPrefetch]
-  );
-
-  // 포커스 핸들러 (키보드 네비게이션)
-  const handleFocus = useCallback(
-    (event: React.FocusEvent<HTMLAnchorElement>) => {
-      onFocus?.(event);
-      doPrefetch();
-    },
-    [onFocus, doPrefetch]
-  );
-
-  // Viewport 진입 시 prefetch (IntersectionObserver)
-  useEffect(() => {
-    if (!shouldPrefetch || typeof IntersectionObserver === "undefined") {
-      return;
-    }
-
-    // ref가 없으면 무시 (SSR)
-    return;
-  }, [shouldPrefetch]);
-
-  return (
-    <a
-      href={href}
-      onClick={handleClick}
-      onMouseEnter={handleMouseEnter}
-      onFocus={handleFocus}
-      data-mandu-link=""
-      {...rest}
-    >
-      {children}
-    </a>
-  );
-}
-
-/**
- * NavLink - 현재 경로와 일치할 때 활성 스타일 적용
- *
- * @example
- * ```tsx
- * import { NavLink } from "@mandujs/core/client";
- *
- * <NavLink
- *   href="/about"
- *   className={({ isActive }) => isActive ? "active" : ""}
- * >
- *   About
- * </NavLink>
- * ```
- */
-export interface NavLinkProps extends Omit<LinkProps, "className" | "style"> {
-  /** 활성 상태에 따른 className */
-  className?: string | ((props: { isActive: boolean }) => string);
-  /** 활성 상태에 따른 style */
-  style?:
-    | React.CSSProperties
-    | ((props: { isActive: boolean }) => React.CSSProperties);
-  /** 활성 상태일 때 적용할 style (style과 병합됨) */
-  activeStyle?: React.CSSProperties;
-  /** 활성 상태일 때 추가할 className */
-  activeClassName?: string;
-  /** 정확히 일치해야 활성화 (기본: false) */
-  exact?: boolean;
-}
-
-export function NavLink({
-  href,
-  className,
-  style,
-  activeStyle,
-  activeClassName,
-  exact = false,
-  ...rest
-}: NavLinkProps): React.ReactElement {
-  // 현재 경로와 비교
-  const isActive =
-    typeof window !== "undefined"
-      ? exact
-        ? window.location.pathname === href
-        : window.location.pathname.startsWith(href)
-      : false;
-
-  // className 처리
-  let resolvedClassName =
-    typeof className === "function" ? className({ isActive }) : className;
-
-  if (isActive && activeClassName) {
-    resolvedClassName = resolvedClassName
-      ? `${resolvedClassName} ${activeClassName}`
-      : activeClassName;
-  }
-
-  // style 처리
-  let resolvedStyle =
-    typeof style === "function" ? style({ isActive }) : style;
-
-  if (isActive && activeStyle) {
-    resolvedStyle = { ...resolvedStyle, ...activeStyle };
-  }
-
-  return (
-    <Link
-      href={href}
-      className={resolvedClassName}
-      style={resolvedStyle}
-      {...rest}
-    />
-  );
-}
-
-export default Link;
+/**
+ * Mandu Link Component 🔗
+ * Client-side 네비게이션을 위한 Link 컴포넌트
+ */
+
+import React, {
+  type AnchorHTMLAttributes,
+  type MouseEvent,
+  type ReactNode,
+  useCallback,
+  useEffect,
+  useRef,
+} from "react";
+import { navigate, prefetch } from "./router";
+import { autoStableManduId } from "../runtime/stable-selector";
+
+export interface LinkProps
+  extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
+  /** 이동할 URL */
+  href: string;
+  /** Stable selector id (optional). If omitted, core injects best-effort id. */
+  manduId?: string;
+  /** history.replaceState 사용 여부 */
+  replace?: boolean;
+  /** 마우스 hover 시 prefetch 여부 */
+  prefetch?: boolean;
+  /** 스크롤 위치 복원 여부 (기본: true) */
+  scroll?: boolean;
+  /** 자식 요소 */
+  children?: ReactNode;
+}
+
+/**
+ * Client-side 네비게이션 Link 컴포넌트
+ *
+ * @example
+ * ```tsx
+ * import { Link } from "@mandujs/core/client";
+ *
+ * // 기본 사용
+ * <Link href="/about">About</Link>
+ *
+ * // Prefetch 활성화
+ * <Link href="/users" prefetch>Users</Link>
+ *
+ * // Replace 모드 (뒤로가기 히스토리 없음)
+ * <Link href="/login" replace>Login</Link>
+ * ```
+ */
+export function Link({
+  href,
+  manduId,
+  replace = false,
+  prefetch: shouldPrefetch = false,
+  scroll = true,
+  children,
+  onClick,
+  onMouseEnter,
+  onFocus,
+  ...rest
+}: LinkProps): React.ReactElement {
+  const prefetchedRef = useRef(false);
+
+  // 클릭 핸들러
+  const handleClick = useCallback(
+    (event: MouseEvent<HTMLAnchorElement>) => {
+      // 사용자 정의 onClick 먼저 실행
+      onClick?.(event);
+
+      // 기본 동작 방지 조건
+      if (
+        event.defaultPrevented ||
+        event.button !== 0 ||
+        event.metaKey ||
+        event.altKey ||
+        event.ctrlKey ||
+        event.shiftKey
+      ) {
+        return;
+      }
+
+      // 외부 링크 체크
+      try {
+        const url = new URL(href, window.location.origin);
+        if (url.origin !== window.location.origin) {
+          return; // 외부 링크는 기본 동작
+        }
+      } catch {
+        return;
+      }
+
+      // Client-side 네비게이션
+      event.preventDefault();
+      navigate(href, { replace, scroll });
+    },
+    [href, replace, scroll, onClick]
+  );
+
+  // Prefetch 실행
+  const doPrefetch = useCallback(() => {
+    if (!shouldPrefetch || prefetchedRef.current) return;
+
+    try {
+      const url = new URL(href, window.location.origin);
+      if (url.origin === window.location.origin) {
+        prefetch(href);
+        prefetchedRef.current = true;
+      }
+    } catch {
+      // 무시
+    }
+  }, [href, shouldPrefetch]);
+
+  // 마우스 hover 핸들러
+  const handleMouseEnter = useCallback(
+    (event: MouseEvent<HTMLAnchorElement>) => {
+      onMouseEnter?.(event);
+      doPrefetch();
+    },
+    [onMouseEnter, doPrefetch]
+  );
+
+  // 포커스 핸들러 (키보드 네비게이션)
+  const handleFocus = useCallback(
+    (event: React.FocusEvent<HTMLAnchorElement>) => {
+      onFocus?.(event);
+      doPrefetch();
+    },
+    [onFocus, doPrefetch]
+  );
+
+  // Viewport 진입 시 prefetch (IntersectionObserver)
+  useEffect(() => {
+    if (!shouldPrefetch || typeof IntersectionObserver === "undefined") {
+      return;
+    }
+
+    // ref가 없으면 무시 (SSR)
+    return;
+  }, [shouldPrefetch]);
+
+  const stableId = manduId ?? autoStableManduId("Link");
+
+  return (
+    <a
+      href={href}
+      onClick={handleClick}
+      onMouseEnter={handleMouseEnter}
+      onFocus={handleFocus}
+      data-mandu-link=""
+      data-mandu-id={stableId}
+      {...rest}
+    >
+      {children}
+    </a>
+  );
+}
+
+/**
+ * NavLink - 현재 경로와 일치할 때 활성 스타일 적용
+ *
+ * @example
+ * ```tsx
+ * import { NavLink } from "@mandujs/core/client";
+ *
+ * <NavLink
+ *   href="/about"
+ *   className={({ isActive }) => isActive ? "active" : ""}
+ * >
+ *   About
+ * </NavLink>
+ * ```
+ */
+export interface NavLinkProps extends Omit<LinkProps, "className" | "style"> {
+  /** 활성 상태에 따른 className */
+  className?: string | ((props: { isActive: boolean }) => string);
+  /** 활성 상태에 따른 style */
+  style?:
+    | React.CSSProperties
+    | ((props: { isActive: boolean }) => React.CSSProperties);
+  /** 활성 상태일 때 적용할 style (style과 병합됨) */
+  activeStyle?: React.CSSProperties;
+  /** 활성 상태일 때 추가할 className */
+  activeClassName?: string;
+  /** 정확히 일치해야 활성화 (기본: false) */
+  exact?: boolean;
+}
+
+export function NavLink({
+  href,
+  className,
+  style,
+  activeStyle,
+  activeClassName,
+  exact = false,
+  ...rest
+}: NavLinkProps): React.ReactElement {
+  // 현재 경로와 비교
+  const isActive =
+    typeof window !== "undefined"
+      ? exact
+        ? window.location.pathname === href
+        : window.location.pathname.startsWith(href)
+      : false;
+
+  // className 처리
+  let resolvedClassName =
+    typeof className === "function" ? className({ isActive }) : className;
+
+  if (isActive && activeClassName) {
+    resolvedClassName = resolvedClassName
+      ? `${resolvedClassName} ${activeClassName}`
+      : activeClassName;
+  }
+
+  // style 처리
+  let resolvedStyle =
+    typeof style === "function" ? style({ isActive }) : style;
+
+  if (isActive && activeStyle) {
+    resolvedStyle = { ...resolvedStyle, ...activeStyle };
+  }
+
+  return (
+    <Link
+      href={href}
+      className={resolvedClassName}
+      style={resolvedStyle}
+      {...rest}
+    />
+  );
+}
+
+export default Link;

package/src/client/index.ts

@@ -1,6 +1,6 @@
-/**
- * Mandu Client Module 🏝️
- * 클라이언트 사이드 hydration 및 라우팅을 위한 API
+/**
+ * Mandu Client Module 🏝️
+ * 클라이언트 사이드 hydration 및 라우팅을 위한 API
  *
  * @example
  * ```typescript
@@ -23,8 +23,8 @@
  *   return <Link href="/about">About</Link>;
  * }
  * ```
- */
-import "./globals";
+ */
+import "./globals";
 
 // Island API
 export {
@@ -83,6 +83,9 @@ export {
 // Link Components
 export { Link, NavLink, type LinkProps, type NavLinkProps } from "./Link";
 
+// Stable interaction components
+export { ManduButton, ManduModalTrigger } from "./interaction";
+
 // Router Hooks
 export {
   useRouter,

package/src/client/interaction.tsx

@@ -0,0 +1,29 @@
+import React, { type ButtonHTMLAttributes } from "react";
+import { autoStableManduId } from "../runtime/stable-selector";
+
+export interface ManduButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  manduId?: string;
+}
+
+/**
+ * Mandu standard interaction Button.
+ * Core guarantees data-mandu-id injection (best-effort, stable rule).
+ */
+export function ManduButton({ manduId, ...props }: ManduButtonProps) {
+  const id = manduId ?? autoStableManduId("ManduButton");
+  return <button data-mandu-id={id} {...props} />;
+}
+
+export interface ManduModalTriggerProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  manduId?: string;
+  modal?: string;
+}
+
+/**
+ * Skeleton modal trigger component.
+ * ATE extractor can later recognize this signal.
+ */
+export function ManduModalTrigger({ manduId, modal, ...props }: ManduModalTriggerProps) {
+  const id = manduId ?? autoStableManduId("ManduModalTrigger");
+  return <button data-mandu-id={id} data-mandu-modal-trigger={modal ?? ""} {...props} />;
+}

package/src/contract/index.ts

@@ -17,6 +17,7 @@ export * from "./normalize";
 export * from "./registry";
 export * from "./client-safe";
 export * from "./protection";
+export * from "./route-helpers";
 
 import type { ContractDefinition, ContractInstance, ContractSchema } from "./schema";
 import type { ContractHandlers, RouteDefinition } from "./handler";

package/src/contract/route-helpers.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from "bun:test";
+import { z } from "zod";
+import { apiError, bodySchema, querySchema } from "./route-helpers";
+
+describe("route helpers", () => {
+  it("querySchema parses/coerces values", () => {
+    const parseQuery = querySchema(
+      z.object({
+        sinceId: z.coerce.number().int().nonnegative().default(0),
+        limit: z.coerce.number().int().min(1).max(100).default(20),
+      })
+    );
+
+    const result = parseQuery("?sinceId=10&limit=5");
+    expect(result).toEqual({ sinceId: 10, limit: 5 });
+  });
+
+  it("querySchema supports defaults", () => {
+    const parseQuery = querySchema(
+      z.object({
+        limit: z.coerce.number().int().min(1).max(100).default(20),
+      })
+    );
+
+    const result = parseQuery(new URLSearchParams());
+    expect(result.limit).toBe(20);
+  });
+
+  it("bodySchema parses JSON body", async () => {
+    const parseBody = bodySchema(
+      z.object({
+        text: z.string().min(1),
+      })
+    );
+
+    const request = new Request("http://localhost/api/chat/send", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ text: "mandu" }),
+    });
+
+    await expect(parseBody(request)).resolves.toEqual({ text: "mandu" });
+  });
+
+  it("bodySchema accepts +json content type", async () => {
+    const parseBody = bodySchema(z.object({ text: z.string() }));
+    const request = new Request("http://localhost/api/chat/send", {
+      method: "POST",
+      headers: { "content-type": "application/problem+json; charset=utf-8" },
+      body: JSON.stringify({ text: "mandu" }),
+    });
+
+    await expect(parseBody(request)).resolves.toEqual({ text: "mandu" });
+  });
+
+  it("bodySchema rejects non-json content type", async () => {
+    const parseBody = bodySchema(z.object({ text: z.string() }));
+    const request = new Request("http://localhost/api/chat/send", {
+      method: "POST",
+      headers: { "content-type": "text/plain" },
+      body: "text=mandu",
+    });
+
+    await expect(parseBody(request)).rejects.toThrow("application/json");
+  });
+
+  it("bodySchema normalizes invalid JSON parse failure", async () => {
+    const parseBody = bodySchema(z.object({ text: z.string() }));
+    const request = new Request("http://localhost/api/chat/send", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: "{\"text\":" ,
+    });
+
+    await expect(parseBody(request)).rejects.toThrow("Request body contains invalid JSON");
+  });
+
+  it("apiError returns standardized payload", async () => {
+    const res = apiError("invalid input", "BAD_REQUEST", { status: 422 });
+
+    expect(res.status).toBe(422);
+    await expect(res.json()).resolves.toEqual({
+      error: "invalid input",
+      code: "BAD_REQUEST",
+    });
+  });
+});

package/src/contract/route-helpers.ts

@@ -0,0 +1,156 @@
+import { z, type ZodTypeAny } from "zod";
+
+export type ApiErrorCode = string;
+
+export interface ApiErrorBody {
+  error: string;
+  code: ApiErrorCode;
+}
+
+export interface ApiErrorOptions {
+  status?: number;
+  details?: unknown;
+  headers?: HeadersInit;
+}
+
+export type QuerySource =
+  | Request
+  | URL
+  | URLSearchParams
+  | string
+  | Record<string, string | number | boolean | null | undefined>;
+
+function toSearchParams(source: QuerySource): URLSearchParams {
+  if (source instanceof Request) {
+    return new URL(source.url).searchParams;
+  }
+
+  if (source instanceof URL) {
+    return source.searchParams;
+  }
+
+  if (source instanceof URLSearchParams) {
+    return source;
+  }
+
+  if (typeof source === "string") {
+    const raw = source.startsWith("?") ? source.slice(1) : source;
+    return new URLSearchParams(raw);
+  }
+
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(source)) {
+    if (value === undefined || value === null) continue;
+    params.set(key, String(value));
+  }
+  return params;
+}
+
+function paramsToObject(params: URLSearchParams): Record<string, string | string[]> {
+  const out: Record<string, string | string[]> = {};
+  for (const [key, value] of params.entries()) {
+    const prev = out[key];
+    if (prev === undefined) {
+      out[key] = value;
+      continue;
+    }
+    if (Array.isArray(prev)) {
+      prev.push(value);
+      continue;
+    }
+    out[key] = [prev, value];
+  }
+  return out;
+}
+
+/**
+ * Creates a parser for URL query parameters with Zod schema validation
+ *
+ * @param schema - Zod schema for validation
+ * @returns Parser function that accepts various query sources
+ *
+ * @example
+ * ```ts
+ * const parseQuery = querySchema(z.object({
+ *   page: z.coerce.number().default(1),
+ *   limit: z.coerce.number().max(100).default(20)
+ * }));
+ *
+ * const query = parseQuery(request);
+ * ```
+ */
+export function querySchema<TSchema extends ZodTypeAny>(schema: TSchema) {
+  return (source: QuerySource): z.infer<TSchema> => {
+    const params = toSearchParams(source);
+    return schema.parse(paramsToObject(params));
+  };
+}
+
+/**
+ * Creates a parser for JSON request body with Zod schema validation
+ *
+ * Validates Content-Type (application/json or application/*+json) and parses JSON.
+ * Throws TypeError for invalid content-type or malformed JSON.
+ *
+ * @param schema - Zod schema for validation
+ * @returns Async parser function that accepts Request
+ *
+ * @example
+ * ```ts
+ * const parseBody = bodySchema(z.object({
+ *   text: z.string().min(1).max(500)
+ * }));
+ *
+ * const body = await parseBody(request);
+ * ```
+ */
+export function bodySchema<TSchema extends ZodTypeAny>(schema: TSchema) {
+  return async (request: Request): Promise<z.infer<TSchema>> => {
+    const contentType = request.headers.get("content-type") ?? "";
+
+    if (!/^application\/(.+\+json|json)$/i.test(contentType.split(";")[0]?.trim() ?? "")) {
+      throw new TypeError("Body must be application/json");
+    }
+
+    let payload: unknown;
+    try {
+      payload = await request.clone().json();
+    } catch {
+      throw new TypeError("Request body contains invalid JSON");
+    }
+
+    return schema.parse(payload);
+  };
+}
+
+/**
+ * Creates a standardized API error response
+ *
+ * Returns Response with JSON payload: { error, code, details? }
+ *
+ * @param error - Human-readable error message
+ * @param code - Machine-readable error code
+ * @param options - Optional status (default 400), details, and headers
+ * @returns Response with error payload
+ *
+ * @example
+ * ```ts
+ * return apiError("Invalid input", "VALIDATION_ERROR", {
+ *   status: 422,
+ *   details: { field: "email", issue: "Invalid format" }
+ * });
+ * ```
+ */
+export function apiError(error: string, code: ApiErrorCode, options: ApiErrorOptions = {}): Response {
+  const { status = 400, details, headers } = options;
+  const payload: ApiErrorBody & { details?: unknown } = { error, code };
+
+  if (details !== undefined) {
+    payload.details = details;
+  }
+
+  return Response.json(payload, {
+    status,
+    headers,
+  });
+}

package/src/index.ts

@@ -25,7 +25,7 @@ export * from "./paths";
 
 // Consolidated Mandu namespace
 import { ManduFilling, ManduContext, ManduFillingFactory, createSSEConnection } from "./filling";
-import { createContract, defineHandler, defineRoute, createClient, contractFetch, createClientContract } from "./contract";
+import { createContract, defineHandler, defineRoute, createClient, contractFetch, createClientContract, querySchema, bodySchema, apiError } from "./contract";
 import { defineContract, generateAllFromContract, generateOpenAPISpec } from "./contract/define";
 import { island, isIsland, type IslandComponent, type HydrationStrategy } from "./island";
 import { intent, isIntent, getIntentDocs, generateOpenAPIFromIntent } from "./intent";
@@ -111,6 +111,21 @@ export const Mandu = {
    */
   fetch: contractFetch,
 
+  /**
+   * Build a typed query parser from zod schema
+   */
+  querySchema,
+
+  /**
+   * Build a typed JSON body parser from zod schema
+   */
+  bodySchema,
+
+  /**
+   * Build standard API error response ({ error, code })
+   */
+  apiError,
+
   // === AI-Native APIs ===
   /**
    * Define a Contract for code generation

package/src/runtime/index.ts

@@ -9,3 +9,4 @@ export * from "./lifecycle";
 export * from "./trace";
 export * from "./logger";
 export * from "./boundary";
+export * from "./stable-selector";

package/src/runtime/react-renderer.ts

@@ -0,0 +1,67 @@
+import { createRequire } from "node:module";
+
+/**
+ * React renderer integrity layer
+ *
+ * Goal: SSR renderer must use the same React graph as the app route modules.
+ * If @mandujs/core resolves react-dom from CLI's transient bunx cache,
+ * hooks can break with `resolveDispatcher() === null`.
+ */
+
+type ReactDomServer = {
+  renderToString?: (element: unknown) => string;
+  renderToReadableStream?: (
+    element: unknown,
+    options?: Record<string, unknown>
+  ) => Promise<ReadableStream & { allReady: Promise<void> }>;
+};
+
+const requireFromCore = createRequire(import.meta.url);
+
+let cachedServer: ReactDomServer | null = null;
+let cachedServerBrowser: ReactDomServer | null = null;
+
+function loadFromProjectOrCore(specifier: "react-dom/server" | "react-dom/server.browser"): ReactDomServer {
+  // 1) Prefer app-level dependency graph (process.cwd)
+  const projectRequire = createRequire(`${process.cwd()}/`);
+
+  try {
+    return projectRequire(specifier) as ReactDomServer;
+  } catch (error) {
+    // 2) Fallback to framework-local resolution (tests/isolated runtime)
+    if (process.env.NODE_ENV === "development") {
+      console.debug(`[Mandu] Note: "${specifier}"를 프로젝트에서 로드하지 못했습니다. 프레임워크 의존성으로 대체합니다.`, error);
+    }
+    return requireFromCore(specifier) as ReactDomServer;
+  }
+}
+
+export function getRenderToString(): (element: unknown) => string {
+  if (!cachedServer) {
+    cachedServer = loadFromProjectOrCore("react-dom/server");
+  }
+
+  if (typeof cachedServer.renderToString !== "function") {
+    throw new Error("renderToString not found in react-dom/server");
+  }
+
+  return cachedServer.renderToString;
+}
+
+export function getRenderToReadableStream(): (
+  element: unknown,
+  options?: Record<string, unknown>
+) => Promise<ReadableStream & { allReady: Promise<void> }> {
+  if (!cachedServerBrowser) {
+    cachedServerBrowser = loadFromProjectOrCore("react-dom/server.browser");
+  }
+
+  if (typeof cachedServerBrowser.renderToReadableStream !== "function") {
+    throw new Error("renderToReadableStream not found in react-dom/server.browser");
+  }
+
+  return cachedServerBrowser.renderToReadableStream as (
+    element: unknown,
+    options?: Record<string, unknown>
+  ) => Promise<ReadableStream & { allReady: Promise<void> }>;
+}

package/src/runtime/ssr.ts

@@ -1,5 +1,6 @@
-import { renderToString } from "react-dom/server";
+import { getRenderToString } from "./react-renderer";
 import { serializeProps } from "../client/serialize";
+import { createRequire } from "module";
 import type { ReactElement } from "react";
 import type { BundleManifest } from "../bundler/types";
 import type { HydrationConfig, HydrationPriority } from "../spec/schema";
@@ -48,6 +49,32 @@ export interface SSROptions {
   cssPath?: string | false;
 }
 
+let projectRenderToString: ((element: ReactElement) => string) | null | undefined;
+
+function loadProjectRenderToString(): ((element: ReactElement) => string) | null {
+  if (projectRenderToString !== undefined) {
+    return projectRenderToString;
+  }
+
+  try {
+    const projectRequire = createRequire(`${process.cwd()}/package.json`);
+    const module = projectRequire("react-dom/server") as {
+      renderToString?: (element: ReactElement) => string;
+      default?: { renderToString?: (element: ReactElement) => string };
+    };
+    const renderToString = module.renderToString ?? module.default?.renderToString;
+    if (typeof renderToString === "function") {
+      projectRenderToString = renderToString;
+      return projectRenderToString;
+    }
+  } catch {
+    // fallback below
+  }
+
+  projectRenderToString = null;
+  return null;
+}
+
 /**
  * SSR 데이터를 안전하게 직렬화 (Fresh 스타일 고급 직렬화)
  * Date, Map, Set, URL, RegExp, BigInt, 순환참조 지원
@@ -160,6 +187,7 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
     ? `<link rel="stylesheet" href="${escapeHtmlAttr(`${cssPath}${isDev ? `?t=${Date.now()}` : ""}`)}">`
     : "";
 
+  const renderToString = getRenderToString();
   let content = renderToString(element);
 
   // Island 래퍼 적용 (hydration 필요 시)

package/src/runtime/stable-selector.ts

@@ -0,0 +1,70 @@
+function fnv1a64Hex(input: string): string {
+  // Browser-safe deterministic hash (FNV-1a 64-bit)
+  let hash = 0xcbf29ce484222325n;
+  const prime = 0x100000001b3n;
+  for (let i = 0; i < input.length; i++) {
+    hash ^= BigInt(input.charCodeAt(i));
+    hash = (hash * prime) & 0xffffffffffffffffn;
+  }
+  return hash.toString(16).padStart(16, "0");
+}
+
+function getBuildSaltFallback(): string {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    const salt = (typeof process !== "undefined" && (process as any)?.env?.MANDU_BUILD_SALT) as string | undefined;
+    return salt ?? "dev";
+  } catch {
+    return "dev";
+  }
+}
+
+export interface StableManduIdInput {
+  filePath: string;
+  line: number;
+  column: number;
+  symbolName: string;
+  buildSalt: string;
+}
+
+/**
+ * Stable selector id generator
+ * rule: hash(filePath + line + column + symbolName + buildSalt)
+ */
+export function createStableManduId(input: StableManduIdInput): string {
+  const payload = `${input.filePath}:${input.line}:${input.column}:${input.symbolName}:${input.buildSalt}`;
+  const hex = fnv1a64Hex(payload);
+  return `mnd_${hex}`;
+}
+
+export function inferSourceLocationFromStack(stack: string | undefined): { filePath: string; line: number; column: number } | null {
+  if (!stack) return null;
+  // naive parser: find first "(file:line:col)" or "at file:line:col" or "fn@file:line:col" frame
+  const lines = stack.split("\n").map((l) => l.trim());
+  for (const l of lines) {
+    const m =
+      l.match(/\((.*?):(\d+):(\d+)\)/) ??
+      l.match(/\bat\s+(.*?):(\d+):(\d+)\b/) ??
+      l.match(/@(.*?):(\d+):(\d+)/);
+    if (!m) continue;
+    const filePath = m[1];
+    // skip internal/node/bun frames
+    if (filePath.includes("node:") || filePath.includes("bun:") || filePath.includes("internal")) continue;
+    return { filePath, line: Number(m[2]), column: Number(m[3]) };
+  }
+  return null;
+}
+
+/**
+ * Best-effort auto injection for Mandu standard interaction components.
+ * - NOTE: In the browser, stack traces may point to bundled files.
+ * - This is a minimum skeleton; ATE can build selector-map and improve fallbacks.
+ */
+export function autoStableManduId(symbolName: string, buildSalt?: string): string {
+  const salt = buildSalt ?? getBuildSaltFallback();
+  const loc = inferSourceLocationFromStack(new Error().stack);
+  if (!loc) {
+    return createStableManduId({ filePath: "unknown", line: 0, column: 0, symbolName, buildSalt: salt });
+  }
+  return createStableManduId({ ...loc, symbolName, buildSalt: salt });
+}

package/src/runtime/streaming-ssr.ts

@@ -9,9 +9,7 @@
  * - Island Architecture와 완벽 통합
  */
 
-// Bun에서는 react-dom/server.browser에서 renderToReadableStream을 가져옴
-// Node.js 환경에서는 renderToPipeableStream 사용 필요
-import { renderToReadableStream } from "react-dom/server.browser";
+import { getRenderToReadableStream } from "./react-renderer";
 import type { ReactElement, ReactNode } from "react";
 import React, { Suspense } from "react";
 import type { BundleManifest } from "../bundler/types";
@@ -665,6 +663,7 @@ export async function renderToStream(
 
   // React renderToReadableStream 호출
   // 실패 시 throw → renderStreamingResponse에서 500 처리
+  const renderToReadableStream = getRenderToReadableStream();
   const reactStream = await renderToReadableStream(element, {
     onError: (error: Error) => {
       if (timedOut) return;