@mandujs/core 0.53.0 → 0.53.2

package/src/bundler/dev.ts

@@ -1,9 +1,10 @@
+import type * as __ManduContentCollectionTypes0 from "../content/collection";
 /**
  * Mandu Dev Bundler 🔥
  * 개발 모드 번들링 + HMR (Hot Module Replacement)
  */
 
-import type { RoutesManifest, RouteSpec } from "../spec/schema";
+import type { RoutesManifest } from "../spec/schema";
 import { buildClientBundles } from "./build";
 import type { BundleResult } from "./types";
 import { PORTS, TIMEOUTS } from "../constants";
@@ -408,11 +409,12 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
   } = options;
 
   // 초기 빌드
-  console.log("🔨 Initial client bundle build...");
-  const initialBuild = await buildClientBundles(manifest, rootDir, {
-    minify: false,
-    sourcemap: true,
-    reactCompiler,
+  console.log("🔨 Initial client bundle build...");
+  const initialBuild = await buildClientBundles(manifest, rootDir, {
+    mode: "development",
+    minify: false,
+    sourcemap: true,
+    reactCompiler,
   });
 
   if (initialBuild.success) {
@@ -1086,7 +1088,7 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
   const handleContentChange = async (files: readonly string[]): Promise<void> => {
     if (files.length === 0) return;
     try {
-      const mod: typeof import("../content/collection") = await import("../content/collection");
+      const mod: typeof __ManduContentCollectionTypes0 = await import("../content/collection");
       if (typeof mod.invalidateAllCollections === "function") {
         mod.invalidateAllCollections();
       }
@@ -1320,10 +1322,11 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
       const targetIds = Array.from(new Set(islandRoots.map((r) => r.routeId)));
       const startTime = performance.now();
       try {
-        const result = await buildClientBundles(manifest, rootDir, {
-          minify: false,
-          sourcemap: true,
-          targetRouteIds: targetIds,
+        const result = await buildClientBundles(manifest, rootDir, {
+          mode: "development",
+          minify: false,
+          sourcemap: true,
+          targetRouteIds: targetIds,
           reactCompiler,
         });
         const buildTime = performance.now() - startTime;
@@ -1378,10 +1381,11 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
 
       try {
         // #185: framework 번들 (runtime/router/vendor/devtools) 스킵 — 사용자 코드 변경 시 불필요
-        const result = await buildClientBundles(manifest, rootDir, {
-          minify: false,
-          sourcemap: true,
-          skipFrameworkBundles: true,
+        const result = await buildClientBundles(manifest, rootDir, {
+          mode: "development",
+          minify: false,
+          sourcemap: true,
+          skipFrameworkBundles: true,
           reactCompiler,
         });
 
@@ -1447,19 +1451,19 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
       // SSR 모듈 변경 감지 (page.tsx, layout.tsx) — #151
       if (onSSRChange && serverModuleSet.has(normalizedPath)) {
         console.log(`\n🔄 SSR file changed: ${path.basename(changedFile)}`);
-        // Refresh the changed file's imports so the reverse graph
-        // tracks refactors (a new import added to an SSR module).
-        await refreshReverseGraphEdges(path.resolve(rootDir, changedFile));
-        onSSRChange(normalizedPath);
-        return;
-      }
+        // Refresh the changed file's imports so the reverse graph
+        // tracks refactors (a new import added to an SSR module).
+        await refreshReverseGraphEdges(path.resolve(rootDir, changedFile));
+        await Promise.resolve(onSSRChange(normalizedPath));
+        return;
+      }
       // API 모듈 변경 감지 (route.ts)
       if (onAPIChange && apiModuleSet.has(normalizedPath)) {
-        console.log(`\n🔄 API route changed: ${path.basename(changedFile)}`);
-        await refreshReverseGraphEdges(path.resolve(rootDir, changedFile));
-        onAPIChange(normalizedPath);
-        return;
-      }
+        console.log(`\n🔄 API route changed: ${path.basename(changedFile)}`);
+        await refreshReverseGraphEdges(path.resolve(rootDir, changedFile));
+        await Promise.resolve(onAPIChange(normalizedPath));
+        return;
+      }
       // Phase 7.0 R2 Agent D — route middleware change.
       // `app/**/middleware.ts` isn't in apiModuleSet (not registered as a
       // route handler) but reuses the API reload path: the underlying
@@ -1467,11 +1471,11 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
       // import chain. Falls through to `onAPIChange` so the CLI can
       // reuse its existing `handleAPIChange` plumbing.
       if (onAPIChange && isRouteMiddlewareFile(normalizedPath)) {
-        console.log(`\n🔄 Middleware changed: ${path.basename(changedFile)}`);
-        await refreshReverseGraphEdges(path.resolve(rootDir, changedFile));
-        onAPIChange(normalizedPath);
-        return;
-      }
+        console.log(`\n🔄 Middleware changed: ${path.basename(changedFile)}`);
+        await refreshReverseGraphEdges(path.resolve(rootDir, changedFile));
+        await Promise.resolve(onAPIChange(normalizedPath));
+        return;
+      }
       // #189 — reverse import-graph fallback.
       //
       // The changed file matched none of our direct dispatch sets.
@@ -1503,10 +1507,11 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
 
     try {
       // 단일 island만 재빌드 (Runtime/Router/Vendor 스킵, #122)
-      const result = await buildClientBundles(manifest, rootDir, {
-        minify: false,
-        sourcemap: true,
-        targetRouteIds: [routeId],
+      const result = await buildClientBundles(manifest, rootDir, {
+        mode: "development",
+        minify: false,
+        sourcemap: true,
+        targetRouteIds: [routeId],
         reactCompiler,
       });
 
@@ -2188,10 +2193,10 @@ export function createHMRServer(
         } catch {
           // 무시
         }
-      }
-      clients.clear();
-      server.stop();
-    },
+      }
+      clients.clear();
+      void server.stop();
+    },
     setRestartHandler: (handler: () => Promise<void>) => {
       restartHandler = handler;
     },

package/src/bundler/prerender.ts

@@ -555,6 +555,46 @@ export async function prerenderRoutes(
     }
   }
 
+  // 5.5. Issue #254 — emit `404.html` at the dist root when the project
+  // declares an `app/not-found.tsx`. Static hosts (Vercel, Netlify,
+  // Cloudflare Pages, Firebase Hosting) auto-serve `dist/404.html` for
+  // unmatched URLs; without this, visitors hit the platform's plain-
+  // text default.
+  //
+  // The probe path is multi-segment + sentinel-prefixed so it doesn't
+  // collide with single-segment dynamic routes (e.g. `[lang]`). Catch-
+  // all routes at the root (`[...slug]`) WILL still catch this — those
+  // projects own their own 404 surface anyway, so the probe falls
+  // through and we surface a clear warning instead of writing a wrong
+  // 404.html.
+  if (await hasAppNotFound(rootDir)) {
+    const probePath =
+      "/__mandu_not_found_probe_38f17a2c__/__inner_38f17a2c__";
+    try {
+      const request = new Request(`http://localhost${probePath}`);
+      const response = await fetchHandler(request);
+      if (response.status === 404) {
+        const html = await response.text();
+        const filePath = path.join(outputDir, "404.html");
+        await fs.writeFile(filePath, html, "utf-8");
+        pages.push({ path: "/404", size: html.length, duration: 0 });
+        // Not added to pageIndex — `/404` is a host-level fallback,
+        // not a routable page. The runtime keeps using its registered
+        // handler for live SSR.
+      } else {
+        // A catch-all route matched the probe. Skip the 404 emit and
+        // tell the user how to handle it themselves — emitting the
+        // catch-all body as 404.html would be wrong.
+        errors.push(
+          `[404.html] not emitted: probe path matched a catch-all route (HTTP ${response.status}). ` +
+            `Add an explicit 404 page or a sentinel route, or write \`dist/404.html\` from a postbuild script.`,
+        );
+      }
+    } catch (err) {
+      errors.push(`[404.html] ${describeError(err)}`);
+    }
+  }
+
   // 6. Emit runtime index.
   if (writeIndex) {
     const indexContents: PrerenderIndex = {
@@ -874,3 +914,26 @@ function describeError(error: unknown): string {
   if (error instanceof Error) return error.message;
   return String(error);
 }
+
+/**
+ * Issue #254 — true when the project ships an `app/not-found.tsx`
+ * (or one of its non-TSX variants). Used by the prerender step to
+ * decide whether to emit a `404.html` fallback at the dist root.
+ */
+async function hasAppNotFound(rootDir: string): Promise<boolean> {
+  const candidates = [
+    "app/not-found.tsx",
+    "app/not-found.ts",
+    "app/not-found.jsx",
+    "app/not-found.js",
+  ];
+  for (const rel of candidates) {
+    try {
+      await fs.access(path.join(rootDir, rel));
+      return true;
+    } catch {
+      // try next
+    }
+  }
+  return false;
+}

package/src/bundler/safe-build.test.ts

@@ -163,7 +163,8 @@ describe("safeBuild", () => {
     // of landing inside it). The strict assertion is still `peak <= max`.
     let stop = false;
     const sample = async () => {
-      while (!stop) {
+      for (;;) {
+        if (stop) break;
         const { active } = _getConcurrencyState();
         if (active > peak) peak = active;
         samples++;

package/src/bundler/types.ts

@@ -1,3 +1,5 @@
+import type * as __ManduBunTypes0 from "bun";
+import type * as __ManduPluginsHooksTypes1 from "../plugins/hooks";
 /**
  * Mandu Bundler Types
  */
@@ -121,9 +123,14 @@ export interface IslandFileEntry {
 /**
  * 번들러 옵션
  */
-export interface BundlerOptions {
-  /** 코드 압축 여부 (기본: production에서 true) */
-  minify?: boolean;
+export interface BundlerOptions {
+  /**
+   * Build mode. This controls development-only transforms such as React
+   * Fast Refresh independently from minification.
+   */
+  mode?: "development" | "production";
+  /** 코드 압축 여부 (기본: production에서 true) */
+  minify?: boolean;
   /** 소스맵 생성 여부 */
   sourcemap?: boolean;
   /** 파일 감시 모드 */
@@ -187,13 +194,13 @@ export interface BundlerOptions {
    * via `runDefineBundlerPlugin()` and fed into every `safeBuild(...)`
    * call-site; library users may populate it directly.
    */
-  pluginBundlerPlugins?: readonly import("bun").BunPlugin[];
+  pluginBundlerPlugins?: readonly __ManduBunTypes0.BunPlugin[];
 
   /**
    * Phase 18.τ — fire per-build `onBundleComplete(stats)` hook after
    * `buildClientBundles()` finishes. Paired with `configHooks` for
    * config-level hooks. Zero-overhead when both are omitted.
    */
-  plugins?: readonly import("../plugins/hooks").ManduPlugin[];
-  configHooks?: Partial<import("../plugins/hooks").ManduHooks>;
+  plugins?: readonly __ManduPluginsHooksTypes1.ManduPlugin[];
+  configHooks?: Partial<__ManduPluginsHooksTypes1.ManduHooks>;
 }

package/src/change/history.ts

@@ -114,7 +114,7 @@ export async function pruneHistory(
 /**
  * History 설정 로드 (향후 mandu.config.json에서 로드)
  */
-export async function loadHistoryConfig(rootDir: string): Promise<HistoryConfig> {
+export async function loadHistoryConfig(_rootDir: string): Promise<HistoryConfig> {
   // 향후 mandu.config.json에서 로드하도록 확장
   // 현재는 기본값 반환
   return DEFAULT_HISTORY_CONFIG;

package/src/change/snapshot.ts

@@ -13,11 +13,19 @@ import { validateAndReport } from "../config";
 const MANDU_DIR = ".mandu";
 const SPEC_DIR = "spec";
 const MANIFEST_FILE = "routes.manifest.json";
-const SLOTS_DIR = "slots";
-const HISTORY_DIR = "history";
-const SNAPSHOTS_DIR = "snapshots";
-
-/**
+const SLOTS_DIR = "slots";
+const HISTORY_DIR = "history";
+const SNAPSHOTS_DIR = "snapshots";
+
+function reverseCopy<T>(items: readonly T[]): T[] {
+  const reversed: T[] = [];
+  for (let index = items.length - 1; index >= 0; index -= 1) {
+    reversed.push(items[index] as T);
+  }
+  return reversed;
+}
+
+/**
  * 스냅샷 ID 생성 (YYYYMMDD-HHmmss-xxx)
  */
 function generateSnapshotId(): string {
@@ -250,10 +258,11 @@ export async function listSnapshotIds(rootDir: string): Promise<string[]> {
       })
     );
 
-    return entries
-      .map((entry) => entry.replace(".snapshot.json", ""))
-      .sort()
-      .reverse(); // 최신 순
+    return reverseCopy(
+      entries
+        .map((entry) => entry.replace(".snapshot.json", ""))
+        .sort()
+    ); // 최신 순
   } catch {
     return [];
   }

package/src/client/Link.tsx

@@ -88,10 +88,10 @@ export function Link({
       } catch {
         return;
       }
-
-      // Client-side 네비게이션
-      event.preventDefault();
-      navigate(href, { replace, scroll });
+
+      // Client-side 네비게이션
+      event.preventDefault();
+      void navigate(href, { replace, scroll });
     },
     [href, replace, scroll, onClick]
   );
@@ -101,11 +101,11 @@ export function Link({
     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;
-      }
+      const url = new URL(href, window.location.origin);
+      if (url.origin === window.location.origin) {
+        void prefetch(href);
+        prefetchedRef.current = true;
+      }
     } catch {
       // 무시
     }

package/src/client/globals.ts

@@ -1,3 +1,4 @@
+import type * as __ManduReactTypes0 from "react";
 /**
  * Mandu 전역 타입 선언
  * 클라이언트 측 전역 상태의 타입 정의
@@ -37,7 +38,7 @@ declare global {
     __MANDU_ROOTS__?: Map<string, Root>;
 
     /** React 인스턴스 공유 */
-    __MANDU_REACT__?: typeof import("react");
+    __MANDU_REACT__?: typeof __ManduReactTypes0;
 
     /**
      * Issue #193 — global SPA navigation toggle.
@@ -58,4 +59,4 @@ declare global {
   }
 }
 
-export {};
+

package/src/client/hooks.ts

@@ -7,10 +7,6 @@ import { useState, useEffect, useCallback, useMemo, useSyncExternalStore } from
 import {
   subscribe,
   getRouterState,
-  getCurrentRoute,
-  getLoaderData,
-  getActionData,
-  getNavigationState,
   navigate,
   submitAction,
   type RouteInfo,

package/src/client/hydrate.ts

@@ -110,7 +110,7 @@ function noopDispose(): Disposer {
  */
 function scheduleLoad(hydrate: () => void): Disposer {
   let cancelled = false;
-  Promise.resolve().then(() => {
+  void Promise.resolve().then(() => {
     if (!cancelled) hydrate();
   });
   return () => {

package/src/client/router.ts

@@ -3,7 +3,7 @@
  * SPA 스타일 네비게이션을 위한 클라이언트 라우터
  */
 
-import type { ReactNode } from "react";
+
 import { startTransition } from "react";
 import {
   getManduData,
@@ -404,12 +404,12 @@ export async function navigate(
 function handlePopState(event: PopStateEvent): void {
   const state = event.state;
 
-  if (state?.routeId) {
-    // Mandu로 방문한 페이지 - 데이터 다시 fetch
-    navigate(window.location.pathname + window.location.search, {
-      replace: true,
-      scroll: false,
-    });
+  if (state?.routeId) {
+    // Mandu로 방문한 페이지 - 데이터 다시 fetch
+    void navigate(window.location.pathname + window.location.search, {
+      replace: true,
+      scroll: false,
+    });
   } else {
     // SPA 네비게이션 이력이 아닌 페이지 — 현재 라우터 상태 유지
     // (getManduRoute()는 SSR 초기값이라 SPA 네비게이션 후에는 stale)
@@ -576,10 +576,10 @@ function handleLinkClick(event: MouseEvent): void {
   // All clear — prevent the default full-page navigation and hand off
   // to the client-side router. `href` preserves the user's original
   // string (relative paths, fragments, query strings) so the router
-  // can normalize as needed.
-  event.preventDefault();
-  navigate(href);
-}
+  // can normalize as needed.
+  event.preventDefault();
+  void navigate(href);
+}
 
 // ========== Prefetch ==========
 
@@ -702,7 +702,7 @@ export async function submitAction(
         actionData: nextActionData,
         loaderData: result._revalidated ? result.loaderData as unknown : undefined,
       };
-  } catch (error) {
+  } catch  {
     if (controller.signal.aborted) return { ok: false };
 
     setRouterStateInternal({

package/src/client/rpc.ts

@@ -50,7 +50,7 @@ export interface RpcClientOptions {
  * const { id } = await api.post({ body: { title: "New" } });
  * ```
  */
-export function createClient<TContract = unknown>(
+export function createClient<_TContract = unknown>(
   path: string,
   options?: RpcClientOptions
 ): RpcMethods {

package/src/client/use-fetch.ts

@@ -228,12 +228,12 @@ export function useFetch<T = unknown>(
     }
   }, [url, method, stableQuery, stableHeaders, stableBody, cacheTime, cacheKey, transform]);
 
-  useEffect(() => {
-    if (!immediate) return;
-    if (data && dedupe) return;
-    fetchData();
-    return () => { abortRef.current?.abort(); };
-  }, [fetchData, immediate, dedupe]);
+  useEffect(() => {
+    if (!immediate) return;
+    if (data && dedupe) return;
+    void fetchData();
+    return () => { abortRef.current?.abort(); };
+  }, [fetchData, immediate, dedupe]);
 
   const mutate = useCallback((updater: T | ((prev: T | null) => T)) => {
     setData(prev => typeof updater === "function" ? (updater as (prev: T | null) => T)(prev) : updater);

package/src/client/use-sse.ts

@@ -210,7 +210,7 @@ export function useSSE(options: UseSSEOptions = {}): UseSSEReturn {
       }
 
       // Start reading in a properly-yielding async loop
-      (async () => {
+      void (async () => {
         const reader = body.getReader();
         const decoder = new TextDecoder();
 
@@ -218,7 +218,7 @@ export function useSSE(options: UseSSEOptions = {}): UseSSEReturn {
           while (true) {
             // Check for abort
             if (controller.signal.aborted) {
-              reader.cancel();
+              await reader.cancel();
               break;
             }
 
@@ -227,7 +227,7 @@ export function useSSE(options: UseSSEOptions = {}): UseSSEReturn {
 
             // Check for abort again (may have been aborted during read)
             if (controller.signal.aborted) {
-              reader.cancel();
+              await reader.cancel();
               break;
             }
 
@@ -342,7 +342,7 @@ export async function readStreamWithYield(
   try {
     while (true) {
       if (signal?.aborted) {
-        reader.cancel();
+        await reader.cancel();
         break;
       }
 
@@ -350,7 +350,7 @@ export async function readStreamWithYield(
       if (done) break;
 
       if (signal?.aborted) {
-        reader.cancel();
+        await reader.cancel();
         break;
       }
 

package/src/config/mcp-status.ts

@@ -7,7 +7,6 @@
  */
 
 import {
-  MCP_SERVER_STATUS,
   type McpServerStatusMetadata,
 } from "./symbols.js";
 

package/src/config/validate.ts

@@ -15,7 +15,7 @@ import { isGuardRuleLike, type GuardRule as CustomGuardRule } from "../guard/def
  * Creates a schema that warns about unknown keys instead of failing
  * This provides the benefits of .strict() while maintaining compatibility
  */
-function strictWithWarnings<T extends z.ZodRawShape>(
+function _strictWithWarnings<T extends z.ZodRawShape>(
   schema: z.ZodObject<T>,
   schemaName: string
 ): z.ZodEffects<z.ZodObject<T>> {
@@ -237,9 +237,9 @@ const BuildBudgetConfigSchema = z
 /**
  * Build 설정 스키마 (strict)
  */
-const BuildConfigSchema = z
-  .object({
-    outDir: z.string().default(".mandu"),
+const BuildConfigSchema = z
+  .object({
+    outDir: z.string().default(".mandu/client"),
     minify: z.boolean().default(true),
     sourcemap: z.boolean().default(false),
     splitting: z.boolean().default(false),

package/src/config/watcher.ts

@@ -150,7 +150,7 @@ export async function watchConfig(
 
     debounceTimer = setTimeout(() => {
       debounceTimer = null;
-      doReload(changedPath);
+      void doReload(changedPath);
     }, debounceMs);
   };
 

package/src/content/collection.ts

@@ -607,9 +607,8 @@ interface RenderedMarkdown {
  * remark/rehype plugin chain; when any piece is missing, falls back
  * to returning a `<pre>` shell so the caller gets a stable API.
  *
- * We go through `Function("return import(...)")` instead of a direct
- * dynamic `import()` so TS doesn't resolve the optional modules
- * during typecheck — they are NOT in `@mandujs/core` deps by design.
+ * We use a variable dynamic import so TS doesn't resolve the optional
+ * modules during typecheck — they are NOT in `@mandujs/core` deps by design.
  *
  * The `options.remarkPlugins` / `options.rehypePlugins` arrays let
  * docs sites add `rehype-slug`, `rehype-autolink-headings`, `shiki`,
@@ -621,15 +620,12 @@ async function renderMarkdownSafe(
 ): Promise<RenderedMarkdown> {
   const { remarkPlugins = [], rehypePlugins = [], silent = false } = options;
 
-  // Passing the module specifier through a Function-wrapped dynamic
-  // import keeps TypeScript from erroring on optional peer deps; if
-  // any module is missing we fall through to the raw-markdown path.
-  const tryImport = async (id: string): Promise<unknown> => {
-    try {
-      return await (Function("x", "return import(x)") as (x: string) => Promise<unknown>)(id);
-    } catch {
-      return null;
-    }
+  const tryImport = async (id: string): Promise<unknown> => {
+    try {
+      return await import(id);
+    } catch {
+      return null;
+    }
   };
 
   const unified = (await tryImport("unified")) as

package/src/content/content-layer.ts

@@ -253,11 +253,11 @@ export class ContentLayer {
   /**
    * 리소스 정리
    */
-  dispose(): void {
-    this.dataStore.dispose();
-    this.watcher?.close();
-  }
-}
+  dispose(): void {
+    this.dataStore.dispose();
+    void this.watcher?.close();
+  }
+}
 
 /**
  * ContentLayer 팩토리

package/src/content/data-store.ts

@@ -131,7 +131,7 @@ export class ContentDataStore {
       }
 
       this.saveTimer = setTimeout(() => {
-        this.save();
+        void this.save();
       }, this.options.saveDebounce);
     }
   }
@@ -217,7 +217,7 @@ export class ContentDataStore {
 
     // 남은 변경사항 저장
     if (this.dirty && this.options.filePath) {
-      this.save();
+      void this.save();
     }
   }
 

package/src/content/loader-context.ts

@@ -13,7 +13,6 @@ import type {
   ContentWatcher,
   ParseDataOptions,
   RenderedContent,
-  ValidationError as ContentValidationError,
 } from "./types";
 import { ValidationError } from "./types";
 import { generateDigest } from "./digest";

package/src/content/loaders/file.ts

@@ -98,7 +98,7 @@ export function file(options: FileLoaderOptions): Loader {
     name: "file",
 
     async load(context: LoaderContext): Promise<void> {
-      const { store, config, logger, parseData, generateDigest } = context;
+      const { store, config, logger, parseData, generateDigest: _generateDigest } = context;
 
       // 절대 경로 계산
       const absolutePath = path.isAbsolute(filePath)