@mandujs/core 0.18.20 → 0.18.22

package/src/runtime/boundary.tsx

@@ -57,7 +57,7 @@ interface ErrorBoundaryState {
  * </LoadingBoundary>
  * ```
  */
-export function LoadingBoundary({ fallback, children }: LoadingBoundaryProps): JSX.Element {
+export function LoadingBoundary({ fallback, children }: LoadingBoundaryProps): React.ReactElement {
   return <Suspense fallback={fallback}>{children}</Suspense>;
 }
 
@@ -127,7 +127,7 @@ export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundarySt
 /**
  * 기본 로딩 컴포넌트
  */
-export function DefaultLoading(): JSX.Element {
+export function DefaultLoading(): React.ReactElement {
   return (
     <div
       style={{
@@ -146,7 +146,7 @@ export function DefaultLoading(): JSX.Element {
 /**
  * 기본 에러 컴포넌트
  */
-export function DefaultError({ error, resetError }: ErrorFallbackProps): JSX.Element {
+export function DefaultError({ error, resetError }: ErrorFallbackProps): React.ReactElement {
   return (
     <div
       style={{
@@ -220,7 +220,7 @@ export function PageBoundary({
   errorComponent,
   children,
   onError,
-}: PageBoundaryProps): JSX.Element {
+}: PageBoundaryProps): React.ReactElement {
   const LoadingFallback = loadingComponent ?? <DefaultLoading />;
   const ErrorFallback = errorComponent ?? DefaultError;
 

package/src/runtime/logger.test.ts

@@ -62,7 +62,7 @@ describe("logger", () => {
 
       log.onError(ctx, error);
 
-      expect(ctx.get("__mandu_logger_error")).toBe(error);
+      expect(ctx.get<Error>("__mandu_logger_error")).toBe(error);
     });
 
     test("afterHandle은 응답을 저장하고 반환", () => {
@@ -72,7 +72,7 @@ describe("logger", () => {
 
       const result = log.afterHandle(ctx, response);
 
-      expect(ctx.get("__mandu_logger_response")).toBe(response);
+      expect(ctx.get<Response>("__mandu_logger_response")).toBe(response);
       expect(result).toBe(response);
     });
   });
@@ -147,7 +147,7 @@ describe("logger", () => {
 
       log.onRequest(ctx);
 
-      expect(ctx.get("__mandu_logger_request_id")).toBe("custom-POST-123");
+      expect(ctx.get<string>("__mandu_logger_request_id")).toBe("custom-POST-123");
     });
   });
 

package/src/runtime/logger.ts

@@ -639,7 +639,7 @@ export function applyLogger(
   loggerInstance: ReturnType<typeof logger>
 ): void {
   lifecycle.onRequest.push({ fn: loggerInstance.onRequest, scope: "global" });
-  lifecycle.onError.push({ fn: loggerInstance.onError as any, scope: "global" });
+  lifecycle.onError.push({ fn: loggerInstance.onError as (ctx: ManduContext, error: Error) => void, scope: "global" });
   lifecycle.afterHandle.push({ fn: loggerInstance.afterHandle, scope: "global" });
   lifecycle.afterResponse.push({ fn: loggerInstance.afterResponse, scope: "global" });
 }

package/src/runtime/server.ts

@@ -1,5 +1,5 @@
 import type { Server } from "bun";
-import type { RoutesManifest } from "../spec/schema";
+import type { RoutesManifest, RouteSpec, HydrationConfig } from "../spec/schema";
 import type { BundleManifest } from "../bundler/types";
 import type { ManduFilling } from "../filling/filling";
 import { ManduContext } from "../filling/context";
@@ -304,7 +304,7 @@ export interface ServerOptions {
 }
 
 export interface ManduServer {
-  server: Server;
+  server: Server<undefined>;
   router: Router;
   /** 이 서버 인스턴스의 레지스트리 */
   registry: ServerRegistry;
@@ -659,7 +659,7 @@ async function wrapWithLayouts(
   for (let i = layouts.length - 1; i >= 0; i--) {
     const Layout = layouts[i];
     if (Layout) {
-      wrapped = React.createElement(Layout, { params }, wrapped);
+      wrapped = React.createElement(Layout, { params, children: wrapped });
     }
   }
 
@@ -916,14 +916,15 @@ async function loadPageData(
   if (loader) {
     try {
       const module = await loader();
-      const exported = module.default;
+      const exported: unknown = module.default;
+      const exportedObj = exported as Record<string, unknown> | null;
       const component = typeof exported === "function"
-        ? exported
-        : exported?.component ?? exported;
-      registry.registerRouteComponent(route.id, component);
+        ? (exported as RouteComponent)
+        : (exportedObj?.component ?? exported);
+      registry.registerRouteComponent(route.id, component as RouteComponent);
 
       // filling이 있으면 loader 실행
-      const filling = typeof exported === "object" ? exported?.filling : null;
+      const filling = typeof exported === "object" && exported !== null ? (exportedObj as Record<string, unknown>)?.filling as ManduFilling | null : null;
       if (filling?.hasLoader?.()) {
         const ctx = new ManduContext(req, params);
         loaderData = await filling.executeLoader(ctx);
@@ -948,7 +949,7 @@ async function loadPageData(
  * SSR 렌더링 (Streaming/Non-streaming)
  */
 async function renderPageSSR(
-  route: { id: string; pattern: string; layoutChain?: string[]; streaming?: boolean; hydration?: unknown },
+  route: { id: string; pattern: string; layoutChain?: string[]; streaming?: boolean; hydration?: HydrationConfig },
   params: Record<string, string>,
   loaderData: unknown,
   url: string,
@@ -1041,7 +1042,7 @@ async function renderPageSSR(
 async function handlePageRoute(
   req: Request,
   url: URL,
-  route: { id: string; pattern: string; layoutChain?: string[]; streaming?: boolean; hydration?: unknown },
+  route: { id: string; pattern: string; layoutChain?: string[]; streaming?: boolean; hydration?: HydrationConfig },
   params: Record<string, string>,
   registry: ServerRegistry
 ): Promise<Result<Response>> {
@@ -1084,7 +1085,7 @@ async function handleRequestInternal(
 
   // 0. CORS Preflight 요청 처리
   if (settings.cors && isPreflightRequest(req)) {
-    const corsOptions = settings.cors === true ? {} : settings.cors;
+    const corsOptions: CorsOptions = typeof settings.cors === 'object' ? settings.cors : {};
     return ok(handlePreflightRequest(req, corsOptions));
   }
 
@@ -1092,7 +1093,7 @@ async function handleRequestInternal(
   const staticResponse = await serveStaticFile(pathname, settings);
   if (staticResponse) {
     if (settings.cors && isCorsRequest(req)) {
-      const corsOptions = settings.cors === true ? {} : settings.cors;
+      const corsOptions: CorsOptions = typeof settings.cors === 'object' ? settings.cors : {};
       return ok(applyCorsToResponse(staticResponse, req, corsOptions));
     }
     return ok(staticResponse);
@@ -1127,18 +1128,19 @@ async function handleRequestInternal(
     return handlePageRoute(req, url, route, params, registry);
   }
 
-  // 4. 알 수 없는 라우트 종류
+  // 4. 알 수 없는 라우트 종류 — exhaustiveness check
+  const _exhaustive: never = route;
   return err({
     errorType: "FRAMEWORK_BUG",
     code: "MANDU_F003",
     httpStatus: 500,
-    message: `Unknown route kind: ${route.kind}`,
+    message: `Unknown route kind: ${(_exhaustive as RouteSpec).kind}`,
     summary: "알 수 없는 라우트 종류 - 프레임워크 버그",
     fix: {
       file: ".mandu/routes.manifest.json",
       suggestion: "라우트의 kind는 'api' 또는 'page'여야 합니다",
     },
-    route: { id: route.id, pattern: route.pattern },
+    route: { id: (_exhaustive as RouteSpec).id, pattern: (_exhaustive as RouteSpec).pattern },
     timestamp: new Date().toISOString(),
   });
 }
@@ -1158,7 +1160,7 @@ function startBunServerWithFallback(options: {
   port: number;
   hostname?: string;
   fetch: (req: Request) => Promise<Response>;
-}): { server: Server; port: number; attempts: number } {
+}): { server: Server<undefined>; port: number; attempts: number } {
   const { port: startPort, hostname, fetch } = options;
   let lastError: unknown = null;
 

package/src/runtime/ssr.ts

@@ -184,7 +184,7 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
   // CSS 링크 태그 생성
   // - cssPath가 string이면 해당 경로 사용
   // - cssPath가 false 또는 undefined이면 링크 미삽입 (404 방지)
-  const cssLinkTag = cssPath && cssPath !== false
+  const cssLinkTag = cssPath
     ? `<link rel="stylesheet" href="${escapeHtmlAttr(`${cssPath}${isDev ? `?t=${Date.now()}` : ""}`)}">`
     : "";
 

package/src/runtime/stable-selector.ts

@@ -11,8 +11,7 @@ function fnv1a64Hex(input: string): string {
 
 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;
+    const salt = (typeof process !== "undefined" && process.env?.MANDU_BUILD_SALT) as string | undefined;
     return salt ?? "dev";
   } catch {
     return "dev";

package/src/runtime/streaming-ssr.ts

@@ -244,6 +244,15 @@ function validateCriticalData(data: Record<string, unknown> | undefined, isDev:
 
 // ========== Streaming Warnings ==========
 
+/**
+ * Streaming 경고 상태 (module-level, globalThis as any 제거)
+ */
+const streamingWarnings = {
+  _warned: false,
+  markWarned() { this._warned = true; },
+  hasWarned() { return this._warned; },
+};
+
 /**
  * 프록시/버퍼링 관련 경고 (개발 모드)
  */
@@ -378,7 +387,7 @@ function generateHTMLShell(options: StreamingSSROptions): string {
   // CSS 링크 태그 생성
   // - cssPath가 string이면 해당 경로 사용
   // - cssPath가 false 또는 undefined이면 링크 미삽입 (404 방지)
-  const cssLinkTag = cssPath && cssPath !== false
+  const cssLinkTag = cssPath
     ? `<link rel="stylesheet" href="${escapeHtmlAttr(`${cssPath}${isDev ? `?t=${Date.now()}` : ""}`)}">`
     : "";
 
@@ -685,9 +694,9 @@ export async function renderToStream(
   validateCriticalData(criticalData, isDev);
 
   // 스트리밍 주의사항 경고 (첫 요청 시 1회만)
-  if (isDev && !(globalThis as any).__MANDU_STREAMING_WARNED__) {
+  if (isDev && !streamingWarnings.hasWarned()) {
     warnStreamingCaveats(isDev);
-    (globalThis as any).__MANDU_STREAMING_WARNED__ = true;
+    streamingWarnings.markWarned();
   }
 
   const encoder = new TextEncoder();
@@ -748,7 +757,7 @@ export async function renderToStream(
 
   async function readWithTimeout(): Promise<ReadableStreamReadResult<Uint8Array> | null> {
     if (!deadline) {
-      return reader.read();
+      return reader.read() as Promise<ReadableStreamReadResult<Uint8Array>>;
     }
 
     const remaining = deadline - Date.now();
@@ -763,8 +772,8 @@ export async function renderToStream(
 
     const readPromise = reader
       .read()
-      .then((result) => ({ kind: "read" as const, result }))
-      .catch((error) => ({ kind: "error" as const, error }));
+      .then((result) => ({ kind: "read" as const, result: result as ReadableStreamReadResult<Uint8Array> }))
+      .catch((error: unknown) => ({ kind: "error" as const, error }));
 
     const result = await Promise.race([readPromise, timeoutPromise]);
 

package/src/seo/index.ts

@@ -102,6 +102,11 @@ export type {
   JsonLd,
   JsonLdType,
 
+  // Template Literal Types
+  OGProperty,
+  TwitterProperty,
+  MetaProperty,
+
   // Google SEO 최적화
   GoogleMeta,
   FormatDetection,

package/src/seo/integration/ssr.ts

@@ -118,13 +118,13 @@ export function resolveSEOSync(staticMetadata: Metadata): SEOResult {
       resolvedTitle = { absolute: staticMetadata.title, template: null }
     } else if ('absolute' in staticMetadata.title) {
       resolvedTitle = {
-        absolute: staticMetadata.title.absolute,
-        template: staticMetadata.title.template || null,
+        absolute: staticMetadata.title.absolute ?? '',
+        template: staticMetadata.title.template ?? null,
       }
     } else if ('default' in staticMetadata.title) {
       resolvedTitle = {
-        absolute: staticMetadata.title.default,
-        template: staticMetadata.title.template || null,
+        absolute: staticMetadata.title.default ?? '',
+        template: staticMetadata.title.template ?? null,
       }
     }
   }

package/src/seo/render/basic.ts

@@ -212,7 +212,9 @@ export function renderIcons(metadata: ResolvedMetadata): string {
 
   // icon
   for (const icon of icons.icon) {
-    const attrs = [`rel="icon"`, `href="${escapeHtml(urlToString(icon.url))}"`]
+    const iconUrl = urlToString(icon.url)
+    if (!iconUrl) continue
+    const attrs = [`rel="icon"`, `href="${escapeHtml(iconUrl)}"`]
     if (icon.type) attrs.push(`type="${escapeHtml(icon.type)}"`)
     if (icon.sizes) attrs.push(`sizes="${escapeHtml(icon.sizes)}"`)
     tags.push(`<link ${attrs.join(' ')} />`)
@@ -220,19 +222,25 @@ export function renderIcons(metadata: ResolvedMetadata): string {
 
   // apple-touch-icon
   for (const icon of icons.apple) {
-    const attrs = [`rel="apple-touch-icon"`, `href="${escapeHtml(urlToString(icon.url))}"`]
+    const iconUrl = urlToString(icon.url)
+    if (!iconUrl) continue
+    const attrs = [`rel="apple-touch-icon"`, `href="${escapeHtml(iconUrl)}"`]
     if (icon.sizes) attrs.push(`sizes="${escapeHtml(icon.sizes)}"`)
     tags.push(`<link ${attrs.join(' ')} />`)
   }
 
   // shortcut icon
   for (const icon of icons.shortcut) {
-    tags.push(`<link rel="shortcut icon" href="${escapeHtml(urlToString(icon.url))}" />`)
+    const iconUrl = urlToString(icon.url)
+    if (!iconUrl) continue
+    tags.push(`<link rel="shortcut icon" href="${escapeHtml(iconUrl)}" />`)
   }
 
   // other icons
   for (const icon of icons.other) {
-    const attrs = [`href="${escapeHtml(urlToString(icon.url))}"`]
+    const iconUrl = urlToString(icon.url)
+    if (!iconUrl) continue
+    const attrs = [`href="${escapeHtml(iconUrl)}"`]
     if (icon.rel) attrs.push(`rel="${escapeHtml(icon.rel)}"`)
     if (icon.type) attrs.push(`type="${escapeHtml(icon.type)}"`)
     if (icon.sizes) attrs.push(`sizes="${escapeHtml(icon.sizes)}"`)

package/src/seo/render/opengraph.ts

@@ -69,9 +69,11 @@ export function renderOpenGraph(metadata: ResolvedMetadata): string {
   // Images
   if (openGraph.images) {
     for (const image of openGraph.images) {
-      tags.push(og('image', urlToString(image.url)))
+      const imageUrl = urlToString(image.url)
+      if (imageUrl) tags.push(og('image', imageUrl))
       if (image.secureUrl) {
-        tags.push(og('image:secure_url', urlToString(image.secureUrl)))
+        const secureUrl = urlToString(image.secureUrl)
+        if (secureUrl) tags.push(og('image:secure_url', secureUrl))
       }
       if (image.type) {
         tags.push(og('image:type', image.type))
@@ -91,9 +93,11 @@ export function renderOpenGraph(metadata: ResolvedMetadata): string {
   // Videos
   if (openGraph.videos) {
     for (const video of openGraph.videos) {
-      tags.push(og('video', urlToString(video.url)))
+      const videoUrl = urlToString(video.url)
+      if (videoUrl) tags.push(og('video', videoUrl))
       if (video.secureUrl) {
-        tags.push(og('video:secure_url', urlToString(video.secureUrl)))
+        const secureUrl = urlToString(video.secureUrl)
+        if (secureUrl) tags.push(og('video:secure_url', secureUrl))
       }
       if (video.type) {
         tags.push(og('video:type', video.type))
@@ -110,9 +114,11 @@ export function renderOpenGraph(metadata: ResolvedMetadata): string {
   // Audio
   if (openGraph.audio) {
     for (const audio of openGraph.audio) {
-      tags.push(og('audio', urlToString(audio.url)))
+      const audioUrl = urlToString(audio.url)
+      if (audioUrl) tags.push(og('audio', audioUrl))
       if (audio.secureUrl) {
-        tags.push(og('audio:secure_url', urlToString(audio.secureUrl)))
+        const secureUrl = urlToString(audio.secureUrl)
+        if (secureUrl) tags.push(og('audio:secure_url', secureUrl))
       }
       if (audio.type) {
         tags.push(og('audio:type', audio.type))

package/src/seo/render/twitter.ts

@@ -68,14 +68,15 @@ export function renderTwitter(metadata: ResolvedMetadata): string {
   if (tw.images) {
     for (let i = 0; i < tw.images.length; i++) {
       const image = tw.images[i]
+      const imageUrl = urlToString(image.url)
       if (i === 0) {
-        tags.push(twitter('image', urlToString(image.url)))
+        if (imageUrl) tags.push(twitter('image', imageUrl))
         if (image.alt) {
           tags.push(twitter('image:alt', image.alt))
         }
       } else {
         // Multiple images (for galleries)
-        tags.push(twitter(`image${i}`, urlToString(image.url)))
+        if (imageUrl) tags.push(twitter(`image${i}`, imageUrl))
         if (image.alt) {
           tags.push(twitter(`image${i}:alt`, image.alt))
         }

package/src/seo/resolve/url.ts

@@ -27,6 +27,9 @@ export function normalizeMetadataBase(
 /**
  * 상대 URL을 절대 URL로 변환
  */
+export function resolveUrl(url: URL, metadataBase: URL | null): URL;
+export function resolveUrl(url: string | null | undefined, metadataBase: URL | null): URL | null;
+export function resolveUrl(url: string | URL | null | undefined, metadataBase: URL | null): URL | null;
 export function resolveUrl(
   url: string | URL | null | undefined,
   metadataBase: URL | null
@@ -69,6 +72,10 @@ export function resolveUrl(
 /**
  * URL을 문자열로 변환 (렌더링용)
  */
+export function urlToString(url: URL): string;
+export function urlToString(url: string): string;
+export function urlToString(url: null | undefined): null;
+export function urlToString(url: URL | string | null | undefined): string | null;
 export function urlToString(url: URL | string | null | undefined): string | null {
   if (!url) return null
   if (url instanceof URL) return url.href

package/src/seo/types.ts

@@ -223,6 +223,19 @@ export interface ResolvedVerification {
   other: Record<string, string[]> | null
 }
 
+// ============================================================================
+// Template Literal Types for Meta Properties
+// ============================================================================
+
+/** OpenGraph meta property name (og:title, og:description, etc.) */
+export type OGProperty = `og:${string}`;
+
+/** Twitter meta property name (twitter:card, twitter:site, etc.) */
+export type TwitterProperty = `twitter:${string}`;
+
+/** Union of well-known meta property prefixes plus arbitrary strings */
+export type MetaProperty = OGProperty | TwitterProperty | string;
+
 // ============================================================================
 // Open Graph Types
 // ============================================================================

package/src/spec/schema.ts

@@ -2,8 +2,8 @@ import { z } from "zod";
 
 // ========== Hydration 설정 ==========
 
-export const HydrationStrategy = z.enum(["none", "island", "full", "progressive"]);
-export type HydrationStrategy = z.infer<typeof HydrationStrategy>;
+export const SpecHydrationStrategy = z.enum(["none", "island", "full", "progressive"]);
+export type SpecHydrationStrategy = z.infer<typeof SpecHydrationStrategy>;
 
 export const HydrationPriority = z.enum(["immediate", "visible", "idle", "interaction"]);
 export type HydrationPriority = z.infer<typeof HydrationPriority>;
@@ -16,7 +16,7 @@ export const HydrationConfig = z.object({
    * - full: 전체 페이지 hydrate
    * - progressive: 점진적 hydrate
    */
-  strategy: HydrationStrategy,
+  strategy: SpecHydrationStrategy,
 
   /**
    * Hydration 우선순위
@@ -56,71 +56,37 @@ export type LoaderConfig = z.infer<typeof LoaderConfig>;
 export const RouteKind = z.enum(["page", "api"]);
 export type RouteKind = z.infer<typeof RouteKind>;
 
-export const HttpMethod = z.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"]);
-export type HttpMethod = z.infer<typeof HttpMethod>;
-
-export const RouteSpec = z
+export const SpecHttpMethod = z.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"]);
+export type SpecHttpMethod = z.infer<typeof SpecHttpMethod>;
+
+// ---- 공통 필드 ----
+const RouteSpecBase = {
+  id: z.string().min(1, "id는 필수입니다"),
+  pattern: z.string().startsWith("/", "pattern은 /로 시작해야 합니다"),
+  module: z.string().min(1, "module 경로는 필수입니다"),
+  slotModule: z.string().optional(),
+  clientModule: z.string().optional(),
+  contractModule: z.string().optional(),
+  hydration: HydrationConfig.optional(),
+  loader: LoaderConfig.optional(),
+  streaming: z.boolean().optional(),
+};
+
+// ---- Page 라우트 ----
+export const PageRouteSpec = z
   .object({
-    id: z.string().min(1, "id는 필수입니다"),
-    pattern: z.string().startsWith("/", "pattern은 /로 시작해야 합니다"),
-    kind: RouteKind,
-
-    // HTTP 메서드 (API용)
-    methods: z.array(HttpMethod).optional(),
-
-    // 서버 모듈 (generated route handler)
-    module: z.string().min(1, "module 경로는 필수입니다"),
-
-    // 페이지 컴포넌트 모듈 (generated)
-    componentModule: z.string().optional(),
-
-    // 서버 슬롯 (비즈니스 로직)
-    slotModule: z.string().optional(),
-
-    // 클라이언트 슬롯 (interactive 로직) [NEW]
-    clientModule: z.string().optional(),
-
-    // Contract 모듈 (API 스키마 정의) [NEW]
-    contractModule: z.string().optional(),
-
-    // Hydration 설정 [NEW]
-    hydration: HydrationConfig.optional(),
-
-    // Loader 설정 [NEW]
-    loader: LoaderConfig.optional(),
-
-    // Streaming SSR 설정 [NEW v0.9.18]
-    // - true: 이 라우트에 Streaming SSR 적용
-    // - false: 이 라우트에 전통적 SSR 적용
-    // - undefined: 서버 설정 따름
-    streaming: z.boolean().optional(),
-
-    // Layout 체인 [NEW v0.9.33]
-    // - 페이지에 적용할 레이아웃 모듈 경로 배열
-    // - 배열 순서: 외부 → 내부 (Root → Parent → Child)
+    ...RouteSpecBase,
+    kind: z.literal("page"),
+    // page 필수
+    componentModule: z.string().min(1, "kind가 'page'인 경우 componentModule은 필수입니다"),
+    // page 전용 optional
+    methods: z.array(SpecHttpMethod).optional(),
     layoutChain: z.array(z.string()).optional(),
-
-    // Loading UI 모듈 경로 [NEW v0.9.33]
     loadingModule: z.string().optional(),
-
-    // Error UI 모듈 경로 [NEW v0.9.33]
     errorModule: z.string().optional(),
   })
   .refine(
     (route) => {
-      if (route.kind === "page" && !route.componentModule) {
-        return false;
-      }
-      return true;
-    },
-    {
-      message: "kind가 'page'인 경우 componentModule은 필수입니다",
-      path: ["componentModule"],
-    }
-  )
-  .refine(
-    (route) => {
-      // clientModule이 있으면 hydration.strategy가 none이 아니어야 함
       if (route.clientModule && route.hydration?.strategy === "none") {
         return false;
       }
@@ -132,6 +98,46 @@ export const RouteSpec = z
     }
   );
 
+export type PageRouteSpec = z.infer<typeof PageRouteSpec>;
+
+// ---- API 라우트 ----
+export const ApiRouteSpec = z.object({
+  ...RouteSpecBase,
+  kind: z.literal("api"),
+  // api 전용
+  methods: z.array(SpecHttpMethod).optional(),
+  // page 전용 필드도 optional로 허용 (호환성)
+  componentModule: z.string().optional(),
+  layoutChain: z.array(z.string()).optional(),
+  loadingModule: z.string().optional(),
+  errorModule: z.string().optional(),
+});
+
+export type ApiRouteSpec = z.infer<typeof ApiRouteSpec>;
+
+// ---- discriminatedUnion ----
+export const RouteSpec = z.discriminatedUnion("kind", [
+  // PageRouteSpec에 .refine()이 적용되어 있으므로 내부 shape를 직접 사용
+  z.object({
+    ...RouteSpecBase,
+    kind: z.literal("page"),
+    componentModule: z.string().min(1, "kind가 'page'인 경우 componentModule은 필수입니다"),
+    methods: z.array(SpecHttpMethod).optional(),
+    layoutChain: z.array(z.string()).optional(),
+    loadingModule: z.string().optional(),
+    errorModule: z.string().optional(),
+  }),
+  z.object({
+    ...RouteSpecBase,
+    kind: z.literal("api"),
+    methods: z.array(SpecHttpMethod).optional(),
+    componentModule: z.string().optional(),
+    layoutChain: z.array(z.string()).optional(),
+    loadingModule: z.string().optional(),
+    errorModule: z.string().optional(),
+  }),
+]);
+
 export type RouteSpec = z.infer<typeof RouteSpec>;
 
 // ========== Manifest ==========
@@ -166,6 +172,28 @@ export const RoutesManifest = z
 
 export type RoutesManifest = z.infer<typeof RoutesManifest>;
 
+// ========== Assertion Functions ==========
+
+/**
+ * Asserts that the given route is a page route.
+ * After this call, TypeScript narrows the type to PageRouteSpec.
+ */
+export function assertPageRoute(route: RouteSpec): asserts route is PageRouteSpec {
+  if (route.kind !== "page") {
+    throw new Error(`Expected page route, got "${route.kind}" (id: ${route.id})`);
+  }
+}
+
+/**
+ * Asserts that the given route is an API route.
+ * After this call, TypeScript narrows the type to ApiRouteSpec.
+ */
+export function assertApiRoute(route: RouteSpec): asserts route is ApiRouteSpec {
+  if (route.kind !== "api") {
+    throw new Error(`Expected API route, got "${route.kind}" (id: ${route.id})`);
+  }
+}
+
 // ========== 유틸리티 함수 ==========
 
 /**