@zntc/core 0.1.1 → 0.1.3

package/bin/zntc.mjs

@@ -7,7 +7,16 @@
  * Watch/Serve는 JS 레이어에서 구현.
  */
 
-import { mkdirSync, existsSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import {
+  mkdirSync,
+  existsSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
 import { resolve, dirname, basename, extname, join, sep } from 'node:path';
 import { createServer } from 'node:http';
 import { createServer as createHttpsServer } from 'node:https';
@@ -59,6 +68,7 @@ const {
   build,
   buildAppSync,
   buildSync,
+  watch,
   envToDefine,
   filterWorkspaces,
   findConfigPath,
@@ -109,6 +119,7 @@ function usageLines(command) {
       '  --host [host]              Host to listen on (default: localhost)',
       '  --port <port>              Port to listen on (default: 12300)',
       '  --open                     Open the app URL in the browser',
+      '  --lazy                     Compile dynamic import() chunks on demand',
       '  --mode <mode>              Load mode-specific config and .env files',
       '  --base <path>              Base public path',
       '  --entry-html <path>        HTML entry file',
@@ -247,7 +258,11 @@ function parseArgs(argv) {
     bundle: false,
     watch: false,
     watchJson: false,
-    watchDelay: 100,
+    // SCALAR_KEYS 머지 키 — config.watchDelay 가 적용되려면 default 가 `undefined`
+    // 여야 한다(머지 조건 `opts[key] === undefined`). 16ms 디바운스 default 는
+    // 소비처(setTimeout)에서 `?? 16` 으로 보정(#4223 — 이전 `16` default 라 config
+    // watchDelay 가 silent 무시되던 schema-drift 가드 발동).
+    watchDelay: undefined,
     serve: false,
     serveDir: '.',
     port: undefined,
@@ -288,6 +303,9 @@ function parseArgs(argv) {
     entryNames: undefined,
     chunkNames: undefined,
     assetNames: undefined,
+    // #4466 — undefined 여야 native default(4096)를 덮지 않는다. 명시 0 = 인라인 끔.
+    assetInlineLimit: undefined,
+    cssNames: undefined,
     jsx: undefined,
     jsxDev: false,
     jsxFactory: undefined,
@@ -332,6 +350,9 @@ function parseArgs(argv) {
     resolveExtensions: [],
     mainFields: [],
     rnPlatform: undefined,
+    rnVersion: undefined,
+    diskCache: false, // #4438 디스크 캐시 활성 (--disk-cache)
+    cacheDir: undefined, // #4438 디스크 캐시 경로 (--cache-dir)
     jsxInJs: false,
     outExtensionJs: undefined,
     sourceRoot: undefined,
@@ -393,6 +414,16 @@ function parseArgs(argv) {
     opts.serve = true;
     opts.bundle = true;
     opts.watch = true;
+    // #3793 — `zntc dev` 는 incremental HMR 활성 (__zntc_apply_update / __esm register
+    // 주입) 이 필수. 명시 안 set 시 initial bundle 이 production 모드로 빌드돼 HMR
+    // 런타임 누락 → broadcast 된 Update 가 client 에서 fallback reload. user 가
+    // 명시적으로 `--dev=false` 줘서 override 하기 전엔 dev 모드 default 보장.
+    opts.devMode = true;
+    // RFC_LAZY_DEV_MODULE_HMR PR-5 / web React Fast Refresh: dev 는 reactRefresh 기본 on.
+    // 번들러는 React 컴포넌트가 있는 모듈에만 $RefreshReg$/accept 를 emit(비-React 무해).
+    // 브라우저 런타임 preamble 주입은 runServe 가 react 존재 시에만 한다(비-React 노이즈 0).
+    // 명시 flag(`--react-refresh=false`)는 아래 flag 파싱이 덮어쓴다.
+    if (opts.reactRefresh === undefined) opts.reactRefresh = true;
   } else if (appCommand === 'build') {
     opts.bundle = true;
   } else if (appCommand === 'preview') {
@@ -662,16 +693,137 @@ function getAutoConfigSearchDir(opts) {
   return process.cwd();
 }
 
+/**
+ * RFC #3833 v3 D1a'' (caller-side pre-warm) helper — runAppBuild/runAppDev 가
+ * 공유. 사용자 explicit `plugins: [css({postcss:{...}})]` 의 옵션을 추출해
+ * prepare 단계의 `postcssOverride` 로 전달. buildAppSync 의 sync dispatcher ×
+ * async cssOnLoad 충돌 회피 — Vite/esbuild 의 main thread pre-process → sync
+ * bundle 패턴.
+ *
+ * 분기:
+ *   1. disabled:true     → explicit PostCSS 끄기 (override={plugins:[]} 로
+ *                          auto-discover 도 차단, prepare 가 length 0 skip)
+ *   2. postcss 명시       → presence check, plugins ?? [] 정규화. options-only
+ *                          override 도 explicit no-op (Vite inline override
+ *                          시맨틱)
+ *   3. 둘 다 없으면       → override=null → prepare 가 auto-discover path
+ *
+ * **findLast**: 미래 default `css()` prepend 와 user override 가 동시 존재 시
+ * 마지막 등록이 winner (Vite plugins 순서 의미). sentinel `__cssOptions` 는
+ * runtime 위장 방어 0 — 의도 매치용.
+ *
+ * @param {Array<{name?:string,__cssOptions?:object}>} plugins
+ * @returns {{plugins: unknown[], options: Record<string,unknown> | undefined} | null}
+ */
+/**
+ * sentinel `__cssOptions` 보유 css plugin 의 raw options 추출. 매치 안 되면 null.
+ * extractCssPostcssOverride / extractCssAutoDiscoverRoot 의 공통 helper.
+ */
+function extractCssOptions(plugins) {
+  const cssPlugin = plugins.findLast(
+    // 두 항 모두 optional chain — predicate 순서 변경 시 null/undefined deref 회귀
+    // 차단 (/code-review max #1 latent finding).
+    (p) => p?.name === '@zntc/web/css' && p?.__cssOptions !== undefined,
+  );
+  return cssPlugin?.__cssOptions ?? null;
+}
+
+function extractCssPostcssOverride(plugins) {
+  const opts = extractCssOptions(plugins);
+  if (!opts) return null;
+  if (opts.disabled === true) return { plugins: [], options: undefined };
+  if (opts.postcss) {
+    return {
+      plugins: opts.postcss.plugins ?? [],
+      options: opts.postcss.options,
+      // issue #3851 — css({root}) 의 root 가 caller-pre-warm path 에서 silent
+      // ignore 였던 회귀 fix. override path 의 postcss require base 로 routing.
+      // mode 는 override.plugins 명시 시 loadPostcssConfig 미호출이라 무의미 —
+      // routing 안 함 (사용자가 root 와 mode 둘 다 명시한 경우 mode 는 onLoad
+      // 의 dispatcher path 에서만 의미 있었음, caller-pre-warm 에선 dead).
+      root: opts.root,
+    };
+  }
+  return null;
+}
+
+/**
+ * issue #3857 — `css({root})` 단독 명시 (postcss override 없이) 시 root 가
+ * auto-discover path 의 findPostcssConfig 시작 base 로 사용되게 caller 가 전달.
+ * monorepo edge: postcss.config 가 monorepo root 에 있고 app 이 sub-package
+ * 인 경우 사용자가 root='/monorepo-root' 명시.
+ *
+ * - opts.disabled 면 null (자동발견 차단은 disabled true 의 책임)
+ * - opts.postcss truthy 면 null (override path 가 root 직접 routing)
+ * - opts.root 만 있으면 그것 반환
+ */
+function extractCssAutoDiscoverRoot(plugins) {
+  const opts = extractCssOptions(plugins);
+  if (!opts || opts.disabled === true) return null;
+  if (opts.postcss) return null;
+  // /code-review max #3/#4: type/empty guard — non-string 또는 빈 string 거부.
+  // findPostcssConfig(non-string) → TypeError, findPostcssConfig('') → cwd 기준
+  // wrong-base search. 사용자 invalid 입력은 silent null (auto-discover skip).
+  if (typeof opts.root !== 'string' || opts.root.length === 0) return null;
+  return opts.root;
+}
+
+/**
+ * RFC #3833 v3 D1a'' — caller-pre-warm sentinel (`__cssOptions !== undefined`)
+ * 가진 css plugin 을 native dispatcher plugin chain 에서 제거.
+ *
+ * Caller paths:
+ *   - **runAppBuild**: buildAppSync 의 sync dispatcher 가 async onLoad 받으면
+ *     syncPluginPromiseFailure → BundleFailed. 본 helper 로 dispatch 차단.
+ *   - **buildBundleOptions** (runBundle/watch/runServe): native async dispatcher
+ *     가 onLoad 호출 → prepare 와 같은 PostCSS 두 번 실행 (double-pass). 본
+ *     helper 로 dispatch 차단.
+ *
+ * **runAppDev 는 본 helper 미경유** — controller (createAppDevController) 에
+ * postcssOverride 만 전달, plugin chain 자체는 runServe → buildBundleOptions
+ * 경로에서 처리. 따라서 dev path 의 filter 는 buildBundleOptions 가 cover.
+ *
+ * extractCssPostcssOverride 와 동일 sentinel match 조건 (predicate 일관) —
+ * drift 위험 차단.
+ *
+ * @param {Array<{name?:string,__cssOptions?:object}>} plugins
+ * @returns {Array<unknown>} caller-pre-warm 활성 css plugin 제거된 새 array
+ */
+function dropCallerPreWarmedCssPlugin(plugins) {
+  return plugins.filter((p) => !(p?.name === '@zntc/web/css' && p?.__cssOptions !== undefined));
+}
+
 async function runAppBuild(opts, config, configEnv, _dotenvVars) {
-  if (config?.plugins?.length || opts.pluginPaths.length > 0) {
-    throw new Error(
-      'zntc build app mode does not support JS plugins yet; use --bundle for plugin builds',
-    );
+  // JS plugin 로드 — bundle pipeline 의 buildBundleOptions 와 동일 패턴. app
+  // pipeline 도 plugin dispatcher 통과 (#2538 4-4 PR-1).
+  const appPlugins = [];
+  if (config && Array.isArray(config.plugins)) {
+    appPlugins.push(...config.plugins);
+  }
+  for (const pluginPath of opts.pluginPaths) {
+    const absPath = resolve(pluginPath);
+    const cfg = await importAndResolveDefault(absPath);
+    if (Array.isArray(cfg.plugins)) {
+      appPlugins.push(...cfg.plugins);
+    } else if (typeof cfg.setup === 'function') {
+      appPlugins.push(cfg);
+    }
   }
   const web = await loadWebModule();
   const root = resolve(opts.appRoot ?? '.');
   const outdir = resolve(opts.outdir ?? join(root, 'dist'));
   if (opts.clean) rmSync(outdir, { recursive: true, force: true });
+  // RFC #3833 v3 D1a'' caller-side pre-warm — extractCssPostcssOverride helper 참조.
+  const postcssOverride = extractCssPostcssOverride(appPlugins);
+  // issue #3857 — css({root}) 단독 명시 시 findPostcssConfig search base
+  // (monorepo edge: app 이 sub-package, postcss.config 가 monorepo root).
+  const cssAutoDiscoverRoot = extractCssAutoDiscoverRoot(appPlugins);
+  // dropCallerPreWarmedCssPlugin: sentinel 가진 css plugin 을 항상 dispatcher 에서
+  // 제거 (buildBundleOptions 와 동일 무조건 적용). /code-review max #5: 조건부
+  // (postcssOverride truthy 시만) 분기는 비대칭 — 사용자가 sentinel 만 가진
+  // plugin (예: `__cssOptions:{someFutureKey}` — extract null) 등록 시
+  // BundleFailed 회귀 가능. 무조건 drop 으로 future-key 안전 + 양쪽 path 일관.
+  const dispatchPlugins = dropCallerPreWarmedCssPlugin(appPlugins);
   let pipelineRoot = null;
   try {
     const pipeline = await web.prepareAppCssPipelineRoot(
@@ -681,6 +833,7 @@ async function runAppBuild(opts, config, configEnv, _dotenvVars) {
       opts.logLevel,
       'build',
       { fallbackRequire: requireFromCli, cliNodeModules },
+      { postcssOverride, cssAutoDiscoverRoot },
     );
     pipelineRoot = pipeline?.tempRoot ?? null;
     const result = buildAppSync({
@@ -701,6 +854,7 @@ async function runAppBuild(opts, config, configEnv, _dotenvVars) {
       jsxFactory: opts.jsxFactory,
       jsxFragment: opts.jsxFragment,
       compiler: config?.compiler,
+      plugins: dispatchPlugins.length > 0 ? dispatchPlugins : undefined,
     });
     const htmlEnv = loadEnv(
       configEnv.mode,
@@ -731,14 +885,40 @@ async function runAppDev(opts, config, configEnv, _dotenvVars) {
   const web = await loadWebModule();
   const root = resolve(opts.appRoot ?? '.');
   opts.outdir = opts.outdir || join(root, '.zntc-dev');
-  const appDev = web.createAppDevController(opts, root, configEnv, {
-    fallbackRequire: requireFromCli,
-    cliNodeModules,
-  });
+  // RFC #3833 v3 D1a'' Phase 2: build path 와 동일 plugin walk + helper 추출.
+  const devUserPlugins = [];
+  if (config && Array.isArray(config.plugins)) devUserPlugins.push(...config.plugins);
+  for (const pluginPath of opts.pluginPaths) {
+    const absPath = resolve(pluginPath);
+    const cfg = await importAndResolveDefault(absPath);
+    if (Array.isArray(cfg.plugins)) devUserPlugins.push(...cfg.plugins);
+    else if (typeof cfg.setup === 'function') devUserPlugins.push(cfg);
+  }
+  const appDev = web.createAppDevController(
+    {
+      ...opts,
+      postcssOverride: extractCssPostcssOverride(devUserPlugins),
+      // issue #3857 — css({root}) 단독 명시 (postcss override 없이) 시 root 를
+      // findPostcssConfig 의 search base 로 전달. monorepo 의 sub-package app
+      // 이 monorepo root 의 postcss.config 참조하는 시나리오.
+      cssAutoDiscoverRoot: extractCssAutoDiscoverRoot(devUserPlugins),
+    },
+    root,
+    configEnv,
+    { fallbackRequire: requireFromCli, cliNodeModules },
+  );
   const prepared = await appDev.prepare();
 
   opts.entryPoints = [prepared.entryPath];
   opts.serveDir = opts.outdir;
+  // issue #3858 — runServe 의 watchFolders 자동 set 위해 app root 를 stash.
+  // opts.serveDir 은 outdir(`.zntc-dev`) 이라 사용자 source code root 가 아님 —
+  // 별도 channel 필요.
+  opts._appWatchRoot = root;
+  // issue #3852 — runAppDev 가 collect 한 plugin 을 stash → runServe 의
+  // buildBundleOptions 가 재import 안 함. ESM cache hit 라 시맨틱 회귀는 0 였지만
+  // perf + cache invalidate edge 안전.
+  opts._resolvedPlugins = devUserPlugins;
 
   return runServe(opts, config, { appDev });
 }
@@ -762,6 +942,17 @@ async function loadWebModule() {
         console.error('help: install with `bun add -D @zntc/web` 또는 `npm i -D @zntc/web`.');
         process.exit(1);
       }
+      // @zntc/web 의 module 평가가 dev-overlay-client.raw.js 를 readFileSync 한다
+      // (#2538 4-3). dist 가 incomplete 한 경우 (build:bundle 의 copy 누락 / 일부만
+      // 추출된 tarball) 가 ENOENT 로 throw — 친절 핸들 분기.
+      if (code === 'ENOENT' && /dev-overlay-client\.raw\.js/.test(message)) {
+        console.error('error: @zntc/web 의 dist/dev-overlay-client.raw.js 가 누락됐습니다.');
+        console.error('');
+        console.error(
+          'help: `bun --cwd <repo>/packages/web run build` 로 재빌드하거나 @zntc/web 을 재설치하세요.',
+        );
+        process.exit(1);
+      }
       throw err;
     }
   })();
@@ -1138,6 +1329,8 @@ function mergeConfigIntoOpts(opts, config) {
     'format',
     'platform',
     'target',
+    'rnVersion',
+    'cacheDir', // #4438 디스크 캐시 경로 (NAPI 가 disk_cache_dir 로 해석)
     'banner',
     'footer',
     'globalName',
@@ -1145,6 +1338,8 @@ function mergeConfigIntoOpts(opts, config) {
     'entryNames',
     'chunkNames',
     'assetNames',
+    'assetInlineLimit', // #4466 asset data URL 인라인 임계값 (숫자 scalar)
+    'cssNames',
     'jsx',
     'jsxFactory',
     'jsxFragment',
@@ -1176,6 +1371,8 @@ function mergeConfigIntoOpts(opts, config) {
     'runtimePolyfills',
     'coreJs',
     'tokenizeFormat',
+    // #4223 — config.watchDelay 가 머지되도록(opts default=undefined, 소비처 `?? 16`).
+    'watchDelay',
   ];
   for (const key of SCALAR_KEYS) {
     if (opts[key] === undefined && config[key] !== undefined) {
@@ -1215,6 +1412,7 @@ function mergeConfigIntoOpts(opts, config) {
     // 머지 안 되던 실 BuildOption bool.
     'analyze',
     'devMode',
+    'diskCache', // #4438 디스크 캐시 활성 (NAPI 가 disk_cache_dir 로 해석)
   ];
   for (const key of BOOL_KEYS) {
     if ((opts[key] === false || opts[key] === undefined) && config[key] === true) {
@@ -1238,7 +1436,10 @@ function mergeConfigIntoOpts(opts, config) {
   // tristate bool: false 가 명시적 의미를 가져서 default 를 undefined 로 두는 키.
   // CLI 가 미지정(undefined)일 때만 config 값(true/false)을 채택한다 (CLI flag 우선).
   // inlineDynamicImports=false 의 single-file 보정은 applySingleFileDynamicImportDefault.
-  for (const key of ['inlineDynamicImports']) {
+  // reactRefresh(#4223): `zntc dev` 는 default on(parseArgs 가 opts.reactRefresh=true) →
+  //   그 경우 머지 skip(opts defined). build/transpile 은 opts undefined 라 config(true/
+  //   false) 채택 — 이전 머지 리스트 누락으로 silent 무시되던 schema-drift 해소.
+  for (const key of ['inlineDynamicImports', 'reactRefresh']) {
     if (opts[key] === undefined && config[key] !== undefined) {
       opts[key] = config[key];
     }
@@ -1299,32 +1500,62 @@ function mergeCliRuntimeTargets(runtimePolyfills, runtimeTargetQueries) {
   return runtimePolyfills;
 }
 
-async function runBundle(opts, config) {
-  // config 자동 탐색 + 머지는 main() 에서 모든 모드에 대해 사전 적용된다.
-  // 여기서는 plugins 만 추가로 합친다 (config 의 plugins → --plugin <path> 의 plugins).
-  const plugins = [];
-  if (config && Array.isArray(config.plugins)) {
-    plugins.push(...config.plugins);
-  }
-  for (const pluginPath of opts.pluginPaths) {
-    const absPath = resolve(pluginPath);
-    // importAndResolveDefault 는 pathToFileURL 으로 Windows 경로를 안전하게 처리하고
-    // ENOENT/객체 검증을 통일한다 (config-loader 와 공유).
-    const cfg = await importAndResolveDefault(absPath);
-    if (Array.isArray(cfg.plugins)) {
-      plugins.push(...cfg.plugins);
-    } else if (typeof cfg.setup === 'function') {
-      plugins.push(cfg);
+/**
+ * `runBundle` / `startBundleWatch` 가 공유하는 NAPI BuildOptions 생성 helper.
+ * plugins 머지 + applySingleFileDynamicImportDefault + 옵션 매핑을 한 곳에 모아
+ * runBundle (single-shot) 와 watch (incremental HMR, #3779) 의 옵션 drift 차단.
+ */
+async function buildBundleOptions(opts, config, { filterCallerPreWarmCss = false } = {}) {
+  // issue #3852 — caller (runAppDev) 가 이미 plugin walk 했으면 `_resolvedPlugins`
+  // 로 stash → 재import skip. ESM cache hit 이라 시맨틱 회귀 없지만 perf +
+  // cache invalidate edge 안전.
+  let plugins;
+  if (Array.isArray(opts._resolvedPlugins)) {
+    plugins = [...opts._resolvedPlugins];
+  } else {
+    plugins = [];
+    if (config && Array.isArray(config.plugins)) {
+      plugins.push(...config.plugins);
+    }
+    for (const pluginPath of opts.pluginPaths) {
+      const absPath = resolve(pluginPath);
+      // importAndResolveDefault 는 pathToFileURL 으로 Windows 경로를 안전하게 처리하고
+      // ENOENT/객체 검증을 통일한다 (config-loader 와 공유).
+      const cfg = await importAndResolveDefault(absPath);
+      if (Array.isArray(cfg.plugins)) {
+        plugins.push(...cfg.plugins);
+      } else if (typeof cfg.setup === 'function') {
+        plugins.push(cfg);
+      }
     }
   }
+  // RFC #3833 v3 D1a'' caller-side pre-warm — dropCallerPreWarmedCssPlugin helper
+  // 로 sentinel 가진 css plugin 을 dispatcher chain 에서 제거. **app caller
+  // (runServe with appDev) 만 적용** — bundle/transpile 모드 사용자가 css()
+  // 명시한 경우 무조건 drop 하면 PostCSS 효과 0 silent regression (review #2).
+  // app 모드만 caller-pre-warm 로 prepare 가 처리하므로 dispatcher dispatch 차단
+  // 필요, bundle 모드는 native async dispatcher 가 onLoad 호출 (단 caller-pre-warm
+  // 없어 PostCSS 적용 안 되지만 사용자 의도 그대로 dispatcher 에 전달).
+  const dispatchPlugins = filterCallerPreWarmCss ? dropCallerPreWarmedCssPlugin(plugins) : plugins;
 
   applySingleFileDynamicImportDefault(opts);
 
-  const buildOpts = {
+  return {
     entryPoints: opts.entryPoints.map((e) => resolve(e)),
+    // #3795/#3796 — watch handle 이 outdir 알아야 worker thread 의 createFile 가 정확한 위치에
+    // 출력. `prepareNapiOptions` 가 build/buildSync 케이스에서 outdir 를 delete 하지만 watch()
+    // wrapper (index.ts:3358) 가 명시 outdir 받아 NAPI 로 restore. 그러므로 BuildOptions 의
+    // outdir/outfile 필드 자체는 enrich 해서 보내야 함.
+    outdir: opts.outdir,
+    outfile: opts.outfile,
     format: opts.format,
     platform: opts.platform,
     target: opts.target,
+    // --rn-version: platform=react-native 함의 + RN 문서 기준 버전별 다운레벨 (NAPI 가 해석).
+    rnVersion: opts.rnVersion,
+    // #4438 디스크 캐시 opt-in: --disk-cache(활성) / --cache-dir <path>. NAPI 가 disk_cache_dir 로 해석.
+    diskCache: opts.diskCache,
+    cacheDir: opts.cacheDir,
     browserslist: opts.browserslist,
     external: opts.external,
     packagesExternal: opts.packagesExternal,
@@ -1402,6 +1633,8 @@ async function runBundle(opts, config) {
     entryNames: opts.entryNames,
     chunkNames: opts.chunkNames,
     assetNames: opts.assetNames,
+    assetInlineLimit: opts.assetInlineLimit,
+    cssNames: opts.cssNames,
     jsx: opts.jsx,
     jsxDev: opts.jsxDev,
     jsxFactory: opts.jsxFactory,
@@ -1409,6 +1642,9 @@ async function runBundle(opts, config) {
     jsxImportSource: opts.jsxImportSource,
     inject: opts.inject.map((p) => resolve(p)),
     devMode: opts.devMode,
+    // web React Fast Refresh: native 빌드(options.zig:reactRefresh)에 전파 → 컴포넌트에
+    // $RefreshReg$/accept emit. dev 블록이 기본 on(비-React 무해).
+    reactRefresh: opts.reactRefresh,
     globalIdentifiers: opts.globalIdentifiers,
     // --polyfill / --run-before-main / --watch-folder 는 경로 → abs 변환 (--inject 와 동일).
     // --watch-include / --watch-exclude 는 루트 기준 glob 이므로 변환 안 함.
@@ -1421,7 +1657,7 @@ async function runBundle(opts, config) {
     watchExclude: opts.watchExclude?.length ? opts.watchExclude : undefined,
     jobs: opts.jobs,
     outbase: opts.outbase,
-    plugins: plugins.length > 0 ? plugins : undefined,
+    plugins: dispatchPlugins.length > 0 ? dispatchPlugins : undefined,
     // compiler.styledComponents / compiler.emotion 도 bundle 모드에서 forward.
     // 누락 시 `zntc.config.json` 의 `compiler` 설정이 silently drop 돼 1st-party transform
     // (autoLabel 등) 이 활성화 안 됨.
@@ -1431,8 +1667,12 @@ async function runBundle(opts, config) {
     // (native CLI 만 zntc.config.json mf 를 직접 읽어 동작했던 갭).
     mf: config?.mf,
   };
+}
 
-  const result = plugins.length > 0 ? await build(buildOpts) : buildSync(buildOpts);
+async function runBundle(opts, config) {
+  const buildOpts = await buildBundleOptions(opts, config);
+  const hasPlugins = Array.isArray(buildOpts.plugins) && buildOpts.plugins.length > 0;
+  const result = hasPlugins ? await build(buildOpts) : buildSync(buildOpts);
 
   printResultDiagnostics(result, opts.logLevel);
 
@@ -1556,7 +1796,7 @@ async function runWatch(opts, config) {
       }
 
       clearTimeout(debounceTimer);
-      debounceTimer = setTimeout(rebuild, opts.watchDelay);
+      debounceTimer = setTimeout(rebuild, opts.watchDelay ?? 16);
     });
     attachWatcherErrorHandler(watcher, dir, opts.logLevel);
   }
@@ -1657,6 +1897,65 @@ async function emitRestartAfter(opts, reason, beforeSpawn) {
 
 // ─── Serve 모드 ───
 
+/**
+ * #3858 — raw root .css 의 diff 기반 reconcile. 이전 scan 결과와 비교해
+ * **사라진 path** 만 outdir 에서 unlink. 이전 design (raw vs outdir set diff)
+ * 은 outdir 의 bundler/sass/css-modules 가 emit 한 transient file (chunk.css,
+ * Button.module.zntc.css 등) 을 stale 오판 → unlink 회귀 (/code-review max #4/#5).
+ *
+ * caller 가 closure 로 prevRawSet 보관 — 매 cycle current scan + diff:
+ *   - removed = prev ∖ current → outdir 의 동일 rel path unlink
+ *   - prev := current
+ *
+ * .scss/.sass 는 sass pipeline 이 별도 outdir 에 emit, raw root 의 .scss 자체
+ * 삭제 시 sass 산출물도 dev_controller 가 cleanup. reconcile 은 plain raw .css
+ * 만 cover (사용자가 직접 만든 .css 파일).
+ *
+ * cost: O(raw .css count) walk per rebuild — 일반적 small (dozens).
+ */
+function createReconcileOutdirCss(rawRoot, outdir) {
+  let prevRawSet = new Set();
+
+  function scanRawCss() {
+    const set = new Set();
+    function walk(dir, relBase) {
+      let entries;
+      try {
+        entries = readdirSync(dir, { withFileTypes: true });
+      } catch {
+        return;
+      }
+      for (const e of entries) {
+        if (e.name === 'node_modules' || e.name === '.git') continue;
+        if (e.name.startsWith('.zntc-')) continue;
+        const rel = relBase ? `${relBase}/${e.name}` : e.name;
+        if (e.isDirectory()) walk(join(dir, e.name), rel);
+        else if (e.isFile() && e.name.endsWith('.css')) set.add(rel);
+      }
+    }
+    walk(rawRoot, '');
+    return set;
+  }
+
+  // 첫 호출 시 prev 를 현재 raw scan 으로 초기화 — 첫 reconcile cycle 에서
+  // 모든 outdir .css 가 stale 로 오판되는 것 회피.
+  prevRawSet = scanRawCss();
+
+  return function reconcile() {
+    const current = scanRawCss();
+    for (const rel of prevRawSet) {
+      if (current.has(rel)) continue;
+      const target = join(outdir, rel);
+      try {
+        unlinkSync(target);
+      } catch {
+        // best-effort — file 이 없거나 race
+      }
+    }
+    prevRawSet = current;
+  };
+}
+
 async function runServe(opts, config, { appDev = null } = {}) {
   const isBun = typeof globalThis.Bun !== 'undefined';
   // appDev 모드에서만 web 모듈 (HMR_MSG / APP_DEV_HMR_*_PATH / createHmrChannel /
@@ -1669,7 +1968,47 @@ async function runServe(opts, config, { appDev = null } = {}) {
   const APP_DEV_HMR_CLIENT = web?.APP_DEV_HMR_CLIENT;
   const APP_DEV_HMR_CLIENT_PATH = web?.APP_DEV_HMR_CLIENT_PATH;
   const APP_DEV_HMR_WS_PATH = web?.APP_DEV_HMR_WS_PATH;
+  const APP_DEV_REACT_REFRESH_PATH = web?.APP_DEV_REACT_REFRESH_PATH;
+  // React Fast Refresh preamble (react-refresh 런타임 글로벌 노출 + injectIntoGlobalHook).
+  // reactRefresh on + react 설치 시에만 non-null(=비-React 앱은 주입/서빙/경고 0). lazy 1회 캐시.
+  const reactRefreshAppRoot = opts.appRoot ? resolve(opts.appRoot) : process.cwd();
+  let reactRefreshPreamble; // undefined=미계산, null=스킵, string=서빙
+  const getReactRefreshPreamble = () => {
+    if (reactRefreshPreamble === undefined) {
+      reactRefreshPreamble =
+        web && opts.reactRefresh ? web.buildReactRefreshPreamble(reactRefreshAppRoot) : null;
+    }
+    return reactRefreshPreamble;
+  };
   let serverHandle = null;
+  // #3779 follow-up — restart 시 stop 호출용. opts.bundle+watch+appDev+hmr 분기 안에서만 할당.
+  let nativeWatchHandle = null;
+  // #4062 — JS dev 서버 lazy on-demand 라우트. 게이트 = `--lazy` CLI 플래그(PR-C-3) 또는
+  // env `ZNTC_LAZY=1`(동치 fallback). D105 접근1: native lazy 프리미티브(#4069/#4070, watch
+  // lazySeeds + build lazyForceParse) 위에 JS 서버가 얇게 on-demand 라우팅을 얹는다. lazy 동적
+  // 청크는 emit-skip 되므로(디스크에 없음) 브라우저가 `/<stem>-<8hex>.js` 를 요청하면 그 seed 만
+  // force-parse 한 단발 build() 로 즉석 생성·캐시해서 서빙한다. 게이트 OFF 면 아래 전부 무시 → 0 영향.
+  const lazyMode = opts.lazy === true || process.env.ZNTC_LAZY === '1';
+  // pathHash(8 hex) → seed 절대경로. watch onReady/onRebuild 의 event.lazySeeds 로 갱신.
+  const lazySeedMap = new Map();
+  // pathHash → { body, type }. on-demand 빌드 결과 캐시. rebuild 마다 무효화(seed 본문 변경 가능).
+  const lazyChunkCache = new Map();
+  // pathHash → in-flight build Promise. 같은 청크 동시 요청을 coalesce(중복 build 회피).
+  const lazyInflight = new Map();
+  // on-demand build() 직렬화 tail. 페이지 로드 시 여러 lazy 청크가 동시 요청돼도 native build()
+  // 를 한 번에 하나씩만 돌려 watch worker 와의 동시 재진입 위험을 없앤다(/code-review Q2).
+  let lazyBuildTail = Promise.resolve();
+  // #4062 PR-C-2 — 캐시 세대(epoch). rebuild(captureLazyState)가 캐시를 무효화할 때마다 +1.
+  // on-demand build 가 시작 시 epoch 를 캡처하고 완료 후 비교해, 빌드 도중 rebuild 가 끼면
+  // (epoch 변동) 그 결과를 캐시에 넣지 않는다(옛 소스로 만든 stale 바이트가 비워진 캐시를
+  // 재오염하는 것을 막음 — native LazyState.epoch PR-4-iii 패턴 이식).
+  let lazyEpoch = 0;
+  // lazy entry 청크의 디스크 경로(`<entrystem>.js`). served index.html 은 prepareDev 가 non-split
+  // 으로 `/bundle.js` 를 참조하게 rewrite 했지만, watch lazy 빌드의 entry 청크는 stem 이름이라
+  // mismatch → `/bundle.js` 를 이 파일로 alias.
+  let lazyEntryFile = null;
+  // on-demand 단발 build() 옵션 템플릿(watchBuildOpts 와 동일 lazy 설정, callback/outdir 제거).
+  let lazyOnDemandOpts = null;
   const mimeTypes = {
     '.html': 'text/html',
     '.js': 'application/javascript',
@@ -1686,29 +2025,40 @@ async function runServe(opts, config, { appDev = null } = {}) {
     '.map': 'application/json',
   };
 
-  // 번들 모드면 먼저 빌드
+  // #3796/#3798 root-cause — cold-start 시 runBundle 호출 제거. native watch 가 initial
+  // 빌드 + outdir 출력 + appDev hooks 전부 담당. plugin.setup() 1회만 invoke (cold-start
+  // 시점). race 회피는 HTTP server listen 을 watch.onReady 까지 wait — `napi_tsfn_blocking`
+  // 모드라 worker 가 outdir 출력 완료 후 ready_event firing, JS callback 안에서 markWatchReady.
   if (opts.bundle && opts.entryPoints.length > 0) {
     opts.outdir = opts.outdir || join(opts.serveDir, '.zntc-serve');
-    const bundleResult = await runBundle(opts, config);
-    if (appDev) {
-      if (bundleResult.errors.length > 0) {
-        hmr?.reportError(bundleResult.errors);
-      } else {
-        hmr?.clearError();
-        appDev.injectBundleCssLinks(bundleResult);
-        await appDev.afterBundle();
-      }
-    }
-
-    // watch도 같이
     if (!opts.watch) {
       opts.watch = true;
     }
   }
 
+  // #3796 — watch.onReady 까지 HTTP listen 이 wait 할 수 있게 promise. appDev + hmr 모드만
+  // 의미 — 그 외 모드는 markWatchReady 즉시 호출 → promise 가 처음부터 resolved.
+  let watchReadyResolve;
+  const watchReadyPromise = new Promise((r) => {
+    watchReadyResolve = r;
+  });
+  let watchReadyResolved = false;
+  const markWatchReady = () => {
+    if (!watchReadyResolved) {
+      watchReadyResolved = true;
+      watchReadyResolve();
+    }
+  };
+  if (!(opts.bundle && opts.watch && appDev && hmr)) markWatchReady();
+
   const serveDir = resolve(opts.outdir || opts.serveDir);
   const base = normalizeBase(opts.base ?? '/');
 
+  // #3799 — HMR Update modules 의 sourceMappingURL 이 가리키는 lazy sourcemap endpoint.
+  // dev_overlay_client.js 의 __zntc_apply_update 가 eval 한 module code 끝의 주석을 DevTools
+  // 가 fetch 함. RN bridge 의 `/__zntc_hmr_map/<id>` 와 동일 path.
+  const HMR_MAP_PATH = '/__zntc_hmr_map/';
+
   function handleRequest(reqUrl, accept = '') {
     let pathname = new URL(reqUrl, 'http://localhost').pathname;
     if (appDev && pathname === APP_DEV_HMR_CLIENT_PATH) {
@@ -1718,6 +2068,27 @@ async function runServe(opts, config, { appDev = null } = {}) {
         type: 'application/javascript',
       };
     }
+    // React Fast Refresh preamble — 앱 번들보다 먼저 실행되는 classic <script> 본문.
+    if (appDev && opts.reactRefresh && pathname === APP_DEV_REACT_REFRESH_PATH) {
+      const body = getReactRefreshPreamble();
+      if (body != null) return { status: 200, body, type: 'application/javascript' };
+    }
+    // #3799 — HMR module 별 sourcemap. nativeWatchHandle 이 lazy cache 한 V3 JSON 을
+    // moduleId 로 조회. handle 가 stop 됐거나 module 미수집 시 null → 404. 사용자
+    // app 의 routing 우선순위 (base prefix 처리) 보다 앞에 위치 — `__zntc_hmr_map/`
+    // 는 internal prefix 라 base 영향 무관.
+    if (appDev && pathname.startsWith(HMR_MAP_PATH) && nativeWatchHandle) {
+      const moduleId = decodeURIComponent(pathname.slice(HMR_MAP_PATH.length));
+      try {
+        const sm = nativeWatchHandle.getHmrSourceMap(moduleId);
+        if (sm) {
+          return { status: 200, body: sm, type: 'application/json' };
+        }
+      } catch {
+        // handle stop 또는 unwrap 실패 — 404
+      }
+      return { status: 404, body: 'Not Found', type: 'text/plain' };
+    }
     if (base && base !== '/' && pathname.startsWith(base)) {
       pathname = '/' + pathname.slice(base.length);
     }
@@ -1744,16 +2115,323 @@ async function runServe(opts, config, { appDev = null } = {}) {
     return { status: 200, body, type };
   }
 
+  // #4062 PR-B-2 — lazy 상태 갱신. watch onReady/onRebuild event 의 lazySeeds 로 pathHash→seed
+  // 맵을 다시 채우고, entry 청크 파일을 식별하고, 캐시를 무효화한다(seed 본문 변경 가능).
+  // event.outputs 는 디스크 경로 목록. entry 청크 = entry stem(`<name>.js`)과 basename 이 일치하는
+  // 출력(splitting 의 entry 청크 네이밍). dev 모드는 content-hash off 라 stem 그대로.
+  function captureLazyState(event) {
+    // 실패한 rebuild(event.success===false)는 무시 — 직전 성공 빌드의 seed/cache 를 유지한다
+    // (clear 하면 다음 요청이 또 실패할 빌드를 돌려 last-good 청크를 잃는다). onReady event 는
+    // success 필드가 없어(undefined) 통과한다.
+    if (!lazyMode || !event || event.success === false) return;
+    // 정밀 캐시 무효화(#4062 후속) — 매 rebuild 전체 clear 하면 무관한 편집에도 멀쩡한 lazy
+    // 청크가 버려져 다음 요청이 cold build()(store 없는 단발이라 ~수초)를 돈다. 대신 변경 파일
+    // (event.changed, 절대경로)이 *닿은* 청크만 버린다 — 캐시 항목의 moduleIds(청크 내 모듈
+    // 절대경로)와 교집합이 있을 때만. graph 모양이 바뀐 rebuild(graphChanged=모듈 추가/제거)는
+    // moduleIds 가 stale 일 수 있어(신규 파일이 옛 moduleIds 에 없음) 전체 clear 로 fallback.
+    // changed 가 없으면(onReady 등) 보수적으로 전체 clear.
+    const changedAbs =
+      Array.isArray(event.changed) && event.changed.length > 0
+        ? new Set(event.changed.map((p) => resolve(p)))
+        : null;
+    if (event.graphChanged || !changedAbs) {
+      lazyChunkCache.clear();
+    } else {
+      for (const [hash, entry] of lazyChunkCache) {
+        const ids = entry.moduleIds;
+        // moduleIds 미보유(방어) 또는 변경 파일과 교집합 → 버림.
+        if (!Array.isArray(ids) || ids.some((id) => changedAbs.has(resolve(id)))) {
+          lazyChunkCache.delete(hash);
+        }
+      }
+    }
+    // epoch 증가는 항상 — 진행 중 on-demand build 가 이 무효화를 넘겨 stale 바이트를 재캐시하지
+    // 못하게(in-flight race backstop). 정밀 delete 와 직교(어떤 항목을 버리든 race 가드는 유지).
+    lazyEpoch++;
+    // seed 맵은 event.lazySeeds 가 *실제로 올 때만* 교체한다. 일반 편집(동적 import 를 가진
+    // 모듈이 cache-hit)은 native 가 graph.lazy_seeds 를 다시 안 쌓아 lazySeeds 가 undefined 로
+    // 온다 — 무조건 clear 하면 직전 유효 맵을 날려(PR-B-2 보다 나쁨) on-demand 라우트가 죽는다.
+    // 새 seed 집합(동적 import 추가/제거 = importer 재파싱)일 때만 clear+repopulate.
+    // (lazyEntryFile 의 `if (entry)` 보존과 같은 원리.)
+    if (Array.isArray(event.lazySeeds)) {
+      lazySeedMap.clear();
+      for (const s of event.lazySeeds) {
+        if (s && typeof s.pathHash === 'string' && typeof s.path === 'string') {
+          lazySeedMap.set(s.pathHash, s.path);
+        }
+      }
+    }
+    const entryStem = basename(opts.entryPoints[0] ?? '', extname(opts.entryPoints[0] ?? ''));
+    // event.outputs 는 outdir 기준 bare 파일명("main.js") — serveDir 로 절대화한다(이미 절대면 그대로).
+    const outputs = (Array.isArray(event.outputs) ? event.outputs : [])
+      .filter((p) => typeof p === 'string')
+      .map((p) => resolve(serveDir, p));
+    let entry = outputs.find((p) => basename(p, '.js') === entryStem) ?? null;
+    // fallback: entry stem 매칭 실패 시 `__zntc_load_chunk` 를 포함한 .js 출력(동적 import 보유 청크).
+    if (!entry) {
+      for (const p of outputs) {
+        if (!p.endsWith('.js')) continue;
+        try {
+          if (readFileSync(p, 'utf8').includes('__zntc_load_chunk(')) {
+            entry = p;
+            break;
+          }
+        } catch {
+          // 읽기 실패 — skip
+        }
+      }
+    }
+    // dev rebuild 는 skip_bundle_output 라 event.outputs 가 비어있을 수 있다(#3796). entry 를
+    // 못 찾았으면 직전 값을 유지(entry 청크 파일명은 stem 고정이라 안정 — 매 요청 readFileSync 라
+    // 내용은 자동 fresh). 찾았을 때만 갱신.
+    if (entry) lazyEntryFile = entry;
+  }
+
+  // #4062 PR-B-2 — lazy on-demand 라우트. 반환 null = lazy 라우트가 처리 안 함(기존 handleRequest 로).
+  //   ① `/bundle.js` (served index.html 이 참조) → lazy entry 청크 alias.
+  //   ② `/<stem>-<8hex>.js` → seed 역참조 후 그 seed 만 force-parse 한 단발 build() 로 동적 청크 생성.
+  async function tryServeLazy(reqUrl) {
+    if (!lazyMode) return null;
+    let pathname = new URL(reqUrl, 'http://localhost').pathname;
+    if (base && base !== '/' && pathname.startsWith(base)) {
+      pathname = '/' + pathname.slice(base.length);
+    }
+    // ① entry alias — served index.html 의 `/bundle.js` 를 lazy entry 청크로.
+    if ((pathname === '/bundle.js' || pathname === '/index.js') && lazyEntryFile) {
+      try {
+        return {
+          status: 200,
+          body: readFileSync(lazyEntryFile),
+          type: 'application/javascript',
+        };
+      } catch {
+        return null; // 파일 사라짐 — 정적 fallback
+      }
+    }
+    // ② on-demand 동적 청크.
+    const m = pathname.match(/-([0-9a-f]{8})\.js$/);
+    if (!m) return null;
+    const pathHash = m[1];
+    const seedPath = lazySeedMap.get(pathHash);
+    if (!seedPath) return null; // 알 수 없는 hash — 정적 자산일 수 있어 fallback
+    // #4079 PR-3 (dev materialize) — 이 seed 가 방문됐으니 watch worker 가 그것을 force-parse 해
+    // 정식 청크로 emit(이후 정적 서빙) + transitive deps 를 감시(깊은 편집 HMR + warm 재빌드)하게
+    // 한다. native 가 dedup 하므로 매 요청 호출 무해. PR-1 의 path-hash 안정 이름 덕에 on-demand
+    // 청크 URL ↔ watch emit 청크 URL 이 동일해 전환이 매끄럽다. 아래 on-demand build 는 첫 요청
+    // 즉시성용(watch rebuild 는 ≤200ms 비동기). 구 native 바이너리면 메서드 부재 → 옵셔널 no-op.
+    nativeWatchHandle?.requestLazySeed?.(seedPath);
+    const cached = lazyChunkCache.get(pathHash);
+    if (cached) return cached;
+    if (!lazyOnDemandOpts) return null;
+    // 같은 청크 동시 요청은 진행 중 build 를 공유(coalesce).
+    const existing = lazyInflight.get(pathHash);
+    if (existing) return existing;
+    // tail 에 체인 → on-demand build 들을 직렬화(동시 native build()+watch worker 재진입 회피).
+    const job = lazyBuildTail.then(async () => {
+      // 큐 대기 중 cache 가 채워졌으면(다른 동일 요청이 먼저 완료) 그대로 재사용.
+      const c = lazyChunkCache.get(pathHash);
+      if (c) return c;
+      // build 시작 직전 세대 캡처 — 완료 후 변동(=빌드 도중 rebuild) 시 캐시 오염 방지.
+      const epoch = lazyEpoch;
+      try {
+        const r = await build({ ...lazyOnDemandOpts, lazyForceParse: [seedPath] });
+        if (r.errors && r.errors.length > 0) return null;
+        // seed 모듈을 포함한 청크를 moduleIds 로 찾는다(force-parse 라 그 seed 가 어느 청크에 인라인됨).
+        const chunk = (r.outputFiles ?? []).find(
+          (f) => Array.isArray(f.moduleIds) && f.moduleIds.includes(seedPath),
+        );
+        if (!chunk) return null;
+        const result = {
+          status: 200,
+          body: chunk.contents,
+          type: 'application/javascript',
+          // 정밀 무효화용 — 이 청크에 들어간 모듈 절대경로 집합. rebuild 시 event.changed 와
+          // 교집합이 있을 때만 이 항목을 버린다(무관한 편집엔 보존 → cold 재빌드 회피).
+          moduleIds: Array.isArray(chunk.moduleIds) ? chunk.moduleIds : [],
+        };
+        // 빌드 도중 rebuild 가 끼지 않았을 때만 캐시(epoch 불변). 끼었으면 이 결과는 옛 소스
+        // 기반이라 캐시하지 않고(다음 요청이 fresh 재빌드) 이번 응답으로만 반환.
+        if (lazyEpoch === epoch) lazyChunkCache.set(pathHash, result);
+        return result;
+      } catch (err) {
+        console.error('[serve] lazy chunk build failed:', err);
+        return null;
+      }
+    });
+    lazyBuildTail = job.catch(() => {}); // tail 은 reject 흡수(다음 build 가 멈추지 않게).
+    lazyInflight.set(pathHash, job);
+    try {
+      return await job;
+    } finally {
+      lazyInflight.delete(pathHash);
+    }
+  }
+
   const useTls = opts.certfile && opts.keyfile;
 
+  // #3796/#3798 root-cause — watch handle 을 HTTP listen 전에 띄움. cold-start runBundle 제거
+  // 후 watch worker 가 outdir 출력 + appDev hooks 담당. HTTP listen 은 watchReadyPromise 까지
+  // wait → server listen 시점에 outdir 채워진 상태 (race-free).
+  if (opts.bundle && opts.watch && appDev && hmr) {
+    // app dev path (appDev 활성) — caller-pre-warm 으로 prepare 가 처리한
+    // css plugin 을 dispatcher 에서 제거 필요. bundle 모드 (appDev=null) 는
+    // filter false (사용자 명시 css() 가 dispatcher 에 정상 전달).
+    const watchBuildOpts = await buildBundleOptions(opts, config, {
+      filterCallerPreWarmCss: true,
+    });
+    watchBuildOpts.devMode = true;
+    // #4062 PR-B-2 — lazy on-demand 활성화. lazy 동적 청크는 (a) code splitting 으로 분리되고
+    // (b) IIFE registry(`__zntc_require`/`__zntc_load_chunk`) 로 로드되어야 한다. dev 단일파일
+    // 기본(applySingleFileDynamicImportDefault 가 splitting 미설정 시 inlineDynamicImports=true)
+    // 을 명시적으로 끄고 splitting+iife 를 강제한다. on-demand 단발 build() 템플릿도 동일 설정으로
+    // 준비(watch callback/outdir 제거 — build() 는 outdir 없으면 in-memory outputFiles 반환).
+    if (lazyMode) {
+      watchBuildOpts.splitting = true;
+      watchBuildOpts.inlineDynamicImports = false;
+      watchBuildOpts.lazyCompilation = true;
+      watchBuildOpts.format = 'iife';
+      lazyOnDemandOpts = {
+        ...watchBuildOpts,
+        splitting: true,
+        inlineDynamicImports: false,
+        lazyCompilation: true,
+        format: 'iife',
+      };
+      delete lazyOnDemandOpts.onReady;
+      delete lazyOnDemandOpts.onRebuild;
+      // outdir/outfile 둘 다 제거 → build() 가 write skip(in-memory outputFiles)해 watch 의
+      // 디스크 출력을 매 요청마다 clobber 하지 않게 한다(/code-review: outfile 누락 footgun).
+      delete lazyOnDemandOpts.outdir;
+      delete lazyOnDemandOpts.outfile;
+      delete lazyOnDemandOpts.watch;
+    }
+    // issue #3858 — appDev path 에서 watchFolders 자동 = app root. 사용자가 직접
+    // .css 파일을 import 없이 만들었을 때 (graph 외) 신규 file 의 add 감지를
+    // native watcher (TrackedFileSet 의 dir-watch) 가 처리하도록 root_dir 등록.
+    // opts._appWatchRoot 는 runAppDev 가 stash 한 사용자 source code root (outdir
+    // 아닌 진짜 src/ 컨테이너). 사용자 명시 watchFolders 가 있으면 union — 우선순위 유지.
+    let reconcileOutdir = null;
+    if (opts._appWatchRoot) {
+      const autoWatchRoot = resolve(opts._appWatchRoot);
+      const existing = Array.isArray(watchBuildOpts.watchFolders)
+        ? watchBuildOpts.watchFolders
+        : [];
+      if (!existing.includes(autoWatchRoot)) {
+        watchBuildOpts.watchFolders = [...existing, autoWatchRoot];
+      }
+      // issue #3858 — reconcileOutdir factory 생성 (closure 가 prev/current raw
+      // .css set 추적). onRebuild 마다 호출 — sass/.module/.chunk emit 영향 0.
+      if (opts.outdir) {
+        reconcileOutdir = createReconcileOutdirCss(autoWatchRoot, resolve(opts.outdir));
+      }
+    }
+    watchBuildOpts.onReady = async (event) => {
+      try {
+        // #3799 root-cause — initial build 의 diagnostics 의 error 도 reportError.
+        if (event && event.errors && event.errors.length > 0) {
+          hmr.reportError(
+            event.errors.map((e) => ({ text: e.message, location: { file: e.file } })),
+          );
+        } else {
+          hmr.clearError();
+        }
+        captureLazyState(event); // #4062 — lazySeed 맵 + entry 청크 식별 (lazyMode 아니면 no-op)
+        // #3796 — event.outputs (path 목록) 를 BundleResult shape 으로 변환해 injectBundleCssLinks.
+        const mockResult = {
+          outputFiles: (event && event.outputs ? event.outputs : []).map((p) => ({ path: p })),
+        };
+        appDev.injectBundleCssLinks(mockResult);
+        await appDev.afterBundle();
+      } catch (err) {
+        console.error('[serve] initial appDev hooks failed:', err);
+      } finally {
+        markWatchReady();
+      }
+    };
+    watchBuildOpts.onRebuild = (event) => {
+      // dev_mode + collect_module_codes 인 incremental rebuild 는 skip_bundle_output 자동
+      // 활성이라 outdir 갱신 안 함. graphChanged 시 추가 runBundle 호출 (plugin.setup 2회
+      // 시점 — cold-start 는 watch 1회만).
+      void (async () => {
+        try {
+          // #4062 PR-C-1 — rebuild 마다 lazy 상태 갱신: seed 맵을 event.lazySeeds 로 다시 채우고
+          // (신규 동적 import 추가/제거 반영) 청크 캐시를 무효화한다. captureLazyState 가 실패한
+          // rebuild 는 skip, outputs 가 비면(skip_bundle_output) entry 는 유지한다. (PR-B-2 는
+          // onRebuild 가 lazySeeds 미노출이라 cache.clear 만 했음 — PR-C-1 에서 native 가 노출.)
+          captureLazyState(event);
+          // issue #3858 — native onRebuild 의 cssChanges 분기는 PR #3859 머지로
+          // 도입됐으나, drain (fs.watch) 가 이미 같은 fs event 받아 rebuildAppDevCss
+          // (syncDirty + afterBundle, PostCSS incremental) 로 처리. dual watch race
+          // 의 source 였음 + prepare 호출이 PostCSS 를 tempRoot 전체 reprocess →
+          // "processed N" 회귀 (dev-hmr/postcss test fail). drain 단일 처리로 통합.
+          // graph 외 .css ADD case (#3858 핵심) 는 drain 의 fs.watch (recursive)
+          // 가 신규 add event 받아 처리 — native 의 cssChanges 분기 redundant.
+          // 단 graphChanged 시 outdir 갱신은 아래 runBundle 분기가 cover.
+          // issue #3858 — 매 rebuild 마다 outdir reconcile (raw root .css diff
+          // 후 사라진 path 만 outdir unlink). closure factory 의 prev/current
+          // diff 로 outdir 의 sass/.module/.chunk emit 영향 0.
+          if (event && event.success && reconcileOutdir) {
+            reconcileOutdir();
+          }
+          if (event && event.success && event.graphChanged) {
+            try {
+              const r = await runBundle(opts, config);
+              if (r.errors.length === 0) appDev.injectBundleCssLinks(r);
+            } catch (cssErr) {
+              console.error('[serve] graph-change outdir rebuild failed:', cssErr);
+            }
+          }
+          const annotated =
+            event && event.success && event.updates && event.updates.length > 0
+              ? {
+                  ...event,
+                  updates: event.updates.map((u) => ({
+                    ...u,
+                    code: `${u.code}\n//# sourceMappingURL=${HMR_MAP_PATH}${encodeURIComponent(u.id)}\n`,
+                  })),
+                }
+              : event;
+          const outcome = web.broadcastRebuildEvent(hmr, annotated);
+          // #4079: lazy(splitting) dev 는 분할 청크가 dev HMR 모듈 레지스트리에 없어 module-level
+          // HMR 이 불가하다(dev init lowering 이 production init 로 fallback). 그래서 lazy 청크
+          // 안의 모듈을 편집하면 rebuild 는 변경을 감지(event.changed)하지만 module update 를
+          // 못 만들어 broadcastRebuildEvent 가 'noop' 으로 끝나 화면이 안 갱신된다 → full reload 로 갈음.
+          // 단 (a) 'update'(메인 번들 모듈 변경 — 진짜 HMR 적용 가능)와 'full-reload'(graphChanged)
+          //  /'error' 는 제외, (b) CSS 변경은 drain 의 CSS-only HMR(live <link> swap)이 처리하므로
+          //  *비-CSS* 변경이 하나라도 있을 때만 full reload(전부 CSS 면 CSS HMR 보존).
+          // errors 가 있으면(partial build) overlay 가 latch 된 상태 — full reload 는 overlay 를
+          // 숨기고 깨진 상태로 리로드하므로 skip(에러는 그대로 보여줌, 다음 성공 빌드가 갱신).
+          if (lazyMode && event.success && outcome === 'noop' && !event.errors?.length) {
+            const hasNonCss = (event.changed ?? []).some(
+              (p) => !/\.(css|scss|sass|less|styl|pcss|postcss)$/i.test(p),
+            );
+            if (hasNonCss) hmr.broadcast({ type: web.HMR_MSG.FullReload, timestamp: Date.now() });
+          }
+        } catch (err) {
+          console.error('[serve] hmr broadcast error:', err);
+        }
+      })();
+    };
+    try {
+      nativeWatchHandle = watch(watchBuildOpts);
+    } catch (err) {
+      console.error('[serve] native watch failed to start (incremental HMR disabled):', err);
+      markWatchReady();
+    }
+  }
+
+  // #3796 — HTTP listen 을 watch.onReady 까지 wait (5초 timeout 으로 deadlock 방어).
+  await Promise.race([watchReadyPromise, new Promise((r) => setTimeout(r, 5000))]);
+
   if (isBun) {
     // Bun.serve
     const serveOpts = {
       port: opts.port,
       hostname: opts.host,
-      fetch(req, server) {
+      async fetch(req, server) {
         const url = new URL(req.url);
         // /__hmr WebSocket upgrade — Bun-native API 사용 (Node 분기는 server.on('upgrade')).
+        // upgrade 는 첫 await 전에 동기 실행돼 async fetch 여도 안전.
         if (hmr && url.pathname === APP_DEV_HMR_WS_PATH) {
           if (server.upgrade(req)) return undefined;
           return new Response('Upgrade required', { status: 426 });
@@ -1765,6 +2443,18 @@ async function runServe(opts, config, { appDev = null } = {}) {
           }
         }
 
+        // #4062 PR-B-2 — lazy 라우트(entry alias + on-demand 동적 청크). null = 정적 처리로.
+        const lazy = await tryServeLazy(req.url);
+        if (lazy) {
+          return new Response(lazy.body, {
+            status: lazy.status,
+            headers: {
+              'Content-Type': lazy.type,
+              'Access-Control-Allow-Origin': '*',
+            },
+          });
+        }
+
         const { status, body, type } = handleRequest(req.url, req.headers.get('accept') ?? '');
         return new Response(body, {
           status,
@@ -1819,6 +2509,17 @@ async function runServe(opts, config, { appDev = null } = {}) {
         }
       }
 
+      // #4062 PR-B-2 — lazy 라우트(entry alias + on-demand 동적 청크). null = 정적 처리로.
+      const lazy = await tryServeLazy(req.url);
+      if (lazy) {
+        res.writeHead(lazy.status, {
+          'Content-Type': lazy.type,
+          'Access-Control-Allow-Origin': '*',
+        });
+        res.end(Buffer.isBuffer(lazy.body) ? lazy.body : Buffer.from(lazy.body));
+        return;
+      }
+
       const { status, body, type } = handleRequest(req.url, req.headers.accept ?? '');
       res.writeHead(status, {
         'Content-Type': type,
@@ -1863,6 +2564,20 @@ async function runServe(opts, config, { appDev = null } = {}) {
   }
 
   async function closeServerForRestart() {
+    // #3779 follow-up — native watch worker thread 가 child process spawn 후에도 살아남으면
+    // outdir 출력이 부모/자식 두 곳에서 일어나 race. emitRestartAfter 의 child spawn 전에 stop.
+    // stop 자체가 throw 해도 server.close 는 시도 (HTTP 포트 해제 우선).
+    // #3803 — stop() throw 시 nativeWatchHandle 을 null 하지 않고 유지 → 다음 호출에서 retry
+    // 가능. 정상 path 에서만 null 로 갱신. idempotent stop (#3794 의 napi_remove_wrap) 라
+    // 다음 시도도 안전.
+    if (nativeWatchHandle) {
+      try {
+        nativeWatchHandle.stop();
+        nativeWatchHandle = null;
+      } catch (err) {
+        console.error('[serve] native watch stop failed (will retry on next invocation):', err);
+      }
+    }
     if (!serverHandle) return;
     if (typeof serverHandle.stop === 'function') {
       await serverHandle.stop();
@@ -1889,8 +2604,26 @@ async function runServe(opts, config, { appDev = null } = {}) {
     let rebuilding = false;
     const dirty = new Set();
 
+    // #3796 — native watch handle 은 HTTP listen 전에 띄움 (위쪽 코드). 이 블록은
+    // fsWatch + drain (CSS / sass / postcss / restart) 만 — JS 변경은 native watch 가 단독 처리.
+
     async function rebuildAppDevCss(changedPath) {
-      await appDev.afterBundle({ changedPath });
+      // issue #3861 — drain (fs.watch) 가 prepare skip 시 tempRoot 가 raw root
+      // 와 동기 안 되어 afterBundle 의 mirror 가 stale .css 를 outdir 에 다시
+      // write → reconcileOutdirCss 의 unlink 무효화 (dual watch race).
+      // syncDirty 는 prepare 의 syncDirtyFilesIntoTempRoot 만 호출 — PostCSS
+      // 재실행 skip (prepare 가 full PostCSS reprocess 라 단일 CSS modify 시
+      // 전체 .css 처리 → "processed N" 회귀, dev-hmr/postcss test fail). PostCSS
+      // incremental 처리는 아래 afterBundle 의 changedPath 분기가 cover.
+      appDev.syncDirty([changedPath]);
+      try {
+        await appDev.afterBundle({ changedPath });
+      } catch (cssErr) {
+        if (opts.logLevel !== 'silent') {
+          console.error('[serve] css afterBundle failed:', cssErr);
+        }
+        throw cssErr; // drain outer catch (line 2460) 가 hmr.reportThrownError.
+      }
       hmr?.clearError();
       hmr?.broadcast({
         type: HMR_MSG.CssUpdate,
@@ -1900,6 +2633,9 @@ async function runServe(opts, config, { appDev = null } = {}) {
       if (opts.logLevel !== 'silent') console.error('[serve] css updated');
     }
 
+    // #3779 — sass partial / 다중 sass 변경 (drain 의 sass 분기) 전용. SCSS dependents
+    // 까지 재컴파일해야 하므로 full pipeline + FullReload. JS module 변경은 native watch
+    // handle 이 단독 처리 — 이 함수는 더 이상 JS 분기에서 호출되지 않는다.
     async function rebuildAppDevFull(dirtyPaths = null) {
       const prepared = await appDev.prepare(dirtyPaths);
       opts.entryPoints = [prepared.entryPath];
@@ -1947,6 +2683,12 @@ async function runServe(opts, config, { appDev = null } = {}) {
               } else {
                 await rebuildAppDevFull();
               }
+            } else if (paths.some((p) => p.endsWith('.scss') || p.endsWith('.sass'))) {
+              // #71: sass 변경인데 fast-path 자격 없음(다른 root scss 가 @import 하는 partial,
+              // 또는 다중 sass 변경) → full pipeline rebuild 로 dirty 의 transitive dependents 까지
+              // 재컴파일. CSS-only 분기(afterBundle = postcss only)는 sass 를 재컴파일하지 않아
+              // partial 변경 시 root scss 가 stale 로 남는다(code-review max 적발).
+              await rebuildAppDevFull(paths);
             } else if (cssChanges.length === 1 && paths.length === 1) {
               await rebuildAppDevCss(cssChanges[0]);
             } else {
@@ -1956,7 +2698,33 @@ async function runServe(opts, config, { appDev = null } = {}) {
               if (opts.logLevel !== 'silent') console.error('[serve] css updated');
             }
           } else {
-            await rebuildAppDevFull(paths);
+            // #3797 — paths 의 종류에 따라 3분기:
+            // - 전부 CSS-derived (CSS Module / Sass Module / postcss): native watch 의 module
+            //   graph 밖이라 incremental update 트리거 안 됨 → full pipeline + FullReload.
+            // - JS module (.ts/.tsx/.js 등) 섞임: native watch 가 단독 처리. drain noop
+            //   (중복 컴파일/output race 회피).
+            // - 그 외 (HTML / JSON / static asset 등 native watch graph 밖 + non-CSS): fallback
+            //   FullReload broadcast. pre-#3779 의 unconditional rebuildAppDevFull 회귀 가드.
+            // #3801 — appDev 의 isCssLikeChange 가 단일 진실 소스. inline literal endsWith
+            // 가 `.less` (미지원) 포함하거나 `.styl/.pcss` 누락하던 drift 회귀 방지.
+            const isJsModule = (p) =>
+              p.endsWith('.ts') ||
+              p.endsWith('.tsx') ||
+              p.endsWith('.js') ||
+              p.endsWith('.jsx') ||
+              p.endsWith('.mjs') ||
+              p.endsWith('.cjs');
+            const allCssDerived = paths.every((p) => appDev.isCssLikeChange(p));
+            const hasJs = paths.some(isJsModule);
+            if (allCssDerived) {
+              await rebuildAppDevFull(paths);
+            } else if (!hasJs) {
+              // HTML/JSON/asset 변경 — native watch 가 안 보는 변경에 대한 reload 신호.
+              hmr?.clearError();
+              hmr?.broadcast({ type: HMR_MSG.FullReload, timestamp: Date.now() });
+              if (opts.logLevel !== 'silent') console.error('[serve] file changed, full reload');
+            }
+            // hasJs=true: native watch handle 의 onRebuild 가 단독 broadcast. drain noop.
           }
         }
       } catch (err) {
@@ -1990,7 +2758,7 @@ async function runServe(opts, config, { appDev = null } = {}) {
         }
         dirty.add(absPath);
         clearTimeout(debounceTimer);
-        debounceTimer = setTimeout(drain, opts.watchDelay);
+        debounceTimer = setTimeout(drain, opts.watchDelay ?? 16);
       });
       attachWatcherErrorHandler(watcher, dir, opts.logLevel);
     }