@zntc/web 0.1.1 → 0.1.3

package/README.md

@@ -1,29 +1,40 @@
 # @zntc/web
 
-ZNTC 의 web platform layer — dev server (HTTP/HTTPS + WebSocket HMR), HMR overlay, postcss/sass/lightningcss CSS pipeline, dev controller (file watcher + module graph).
+English · **[한국어](./README_KO.md)**
 
-## 설치
+> ZNTC web platform layer — dev server (HTTP/HTTPS + WebSocket HMR), HMR overlay, postcss / sass / lightningcss CSS pipeline, and dev controller (file watcher + module graph).
+
+[![npm](https://img.shields.io/npm/v/@zntc/web.svg)](https://www.npmjs.com/package/@zntc/web)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/ohah/zntc/blob/main/LICENSE)
+
+`@zntc/web` powers the app-mode side of [ZNTC](https://github.com/ohah/zntc): the `zntc dev` / `zntc preview` / `zntc build` commands. It adds a dev server with WebSocket-based HMR, an error overlay, a CSS pipeline (postcss / sass / lightningcss), and a dev controller that wires a file watcher to the module graph. The `zntc` CLI loads this package automatically, so you rarely import it yourself.
+
+## Installation
 
 ```bash
 bun add -D @zntc/web
-# 또는
+# or
 npm i -D @zntc/web
 ```
 
-`@zntc/core` 가 dependency 로 자동 install 됨 (NAPI binary 포함).
+`@zntc/core` (which ships the native NAPI binary and the `zntc` CLI) is installed automatically as a dependency.
 
-### Optional (CSS pipeline)
+### Optional — CSS pipeline
 
 ```bash
 bun add -D postcss postcss-load-config sass
 ```
 
-- `postcss` / `postcss-load-config` — `postcss.config.{js,ts}` 자동 탐색 / Tailwind / PostCSS plugins
-- `sass` — `.scss` / `.sass` 파일 처리
+- `postcss` / `postcss-load-config` — auto-discovers `postcss.config.{js,ts}` for Tailwind and other PostCSS plugins
+- `sass` — handles `.scss` / `.sass` files
 
-## 사용
+These are optional dependencies; install only what your project needs.
 
-`zntc dev`, `zntc preview`, `zntc build` (app mode) CLI 가 자동으로 `@zntc/web` 을 dynamic import 해서 사용. 사용자 코드에서 직접 import 할 일은 거의 없음.
+## Usage
+
+### Dev server + HMR
+
+In app mode, the `zntc` CLI dynamically imports `@zntc/web` for you — installing the package is all that's required:
 
 ```bash
 bunx zntc dev       # dev server + HMR
@@ -31,18 +42,35 @@ bunx zntc build     # production app build
 bunx zntc preview   # production preview server
 ```
 
-자세한 설정: [docs/CONFIG.md](https://github.com/ohah/zts/blob/main/docs/CONFIG.md) · [docs/HMR.md](https://github.com/ohah/zts/blob/main/docs/HMR.md)
+`zntc dev` serves your app over HTTP (or HTTPS when TLS options are set), pushes Hot Module Replacement updates over WebSocket, and surfaces build errors through the HMR overlay in the browser.
+
+### postcss / sass
+
+When the optional CSS packages are installed, the CSS pipeline activates automatically:
+
+- `postcss.config.{js,ts}` is auto-discovered (Tailwind / PostCSS plugins).
+- `.scss` / `.sass` files are compiled through `sass`.
+- lightningcss handles transforms and minification.
+
+No extra configuration is needed beyond installing the relevant packages.
+
+### Direct import (advanced)
+
+`createAppDevController` is the dev controller's main entry point. It consumes the result of `prepareAppDevSync` from `@zntc/core` and exposes a broad option surface for embedding the dev server in custom tooling. The package also exports a `@zntc/web/css` entry for the CSS pipeline. See the [HMR guide](https://ohah.github.io/zntc) for usage examples.
+
+## Documentation
 
-## 직접 import (고급)
+📚 **Official docs: <https://ohah.github.io/zntc>**
 
-`createAppDevController` 가 dev controller 의 main entry. 옵션 surface 가 넓고 `@zntc/core` 의 `prepareAppDevSync` 결과를 받음 — 사용 예는 [docs/HMR.md](https://github.com/ohah/zts/blob/main/docs/HMR.md) 참조.
+- Monorepo / source: <https://github.com/ohah/zntc>
+- Config reference and HMR details are part of the main ZNTC documentation.
 
-## 관련 패키지
+Related packages:
 
-- [@zntc/core](https://npmjs.com/package/@zntc/core) — 트랜스파일러 / 번들러 코어
-- [@zntc/react-native](https://npmjs.com/package/@zntc/react-native) — RN platform layer
-- [@zntc/vite-plugin](https://npmjs.com/package/@zntc/vite-plugin) — Vite 사용 시 ZNTC transform 적용
+- [@zntc/core](https://www.npmjs.com/package/@zntc/core) — transpiler / bundler core
+- [@zntc/react-native](https://www.npmjs.com/package/@zntc/react-native) — React Native platform layer
+- [@zntc/vite-plugin](https://www.npmjs.com/package/@zntc/vite-plugin) — apply the ZNTC transform when using Vite
 
-## 라이센스
+## License
 
-MIT.
+MIT

package/dist/css/index.d.ts

@@ -0,0 +1,64 @@
+/**
+ * `@zntc/web/css` — ZTS dev/build 의 CSS pipeline plugin (#2538 4-4 PR-2).
+ *
+ * 사용자가 명시 안 해도 controller 가 default 로 등록 (#2538 4-4 PR-3 에서 wiring).
+ * 명시적으로 끄거나 옵션 override 하려면 zntc.config 에 `plugins: [css(...)]` 추가.
+ *
+ * Vite 의 `vite:css` plugin 과 같은 역할 — postcss.config.js 자동 발견 (Vite 정확
+ * 패턴) + `css({ postcss: { plugins } })` 명시 override. 둘 다 지원.
+ *
+ * 현 PR-2 의 scope = factory + ZntcPlugin shape + .css 파일 onLoad PostCSS 통과
+ * (minimal). Sass / CSS Modules 는 follow-up commit.
+ */
+import type { ZntcPlugin } from '@zntc/core';
+export interface CssPluginOptions {
+    /** plugin 전체 비활성. 사용자가 `plugins:[css()]` 명시했지만 특정 빌드에서 끄고 싶을 때. */
+    disabled?: boolean;
+    /**
+     * PostCSS override. 미지정 시 ZTS 가 postcss.config.js 자동 발견 (Vite 패턴).
+     * 명시 시 자동 발견 무시하고 해당 plugins 사용.
+     */
+    postcss?: {
+        plugins?: unknown[];
+        options?: Record<string, unknown>;
+    };
+    /**
+     * postcss.config 검색의 root. 미지정 시 process.cwd().
+     * Vite 의 `css.postcss` 또는 `process.cwd()` 와 동일 의미.
+     */
+    root?: string;
+    /**
+     * postcss-load-config 의 `env` 로 전달 — postcss.config.js 가 factory 형식
+     * `({ mode }) => ({...})` 일 때 사용. 미지정 시 `process.env.NODE_ENV` 또는
+     * `'development'` (dev safer). Vite 의 `css.postcss` env parity.
+     */
+    mode?: 'development' | 'production';
+}
+/**
+ * CSS pipeline plugin factory. ZTS dev / build pipeline 의 `.css` 파일 onLoad 시
+ * PostCSS pass 적용 (autoprefixer / preset-env 등 postcss.config 의 plugin들).
+ *
+ * @example
+ * ```ts
+ * // zero-config — postcss.config.js 자동 발견
+ * export default defineConfig({ plugins: [css()] });
+ *
+ * // override
+ * export default defineConfig({
+ *   plugins: [css({ postcss: { plugins: [autoprefixer()] } })],
+ * });
+ *
+ * // disable
+ * export default defineConfig({ plugins: [css({ disabled: true })] });
+ * ```
+ */
+/**
+ * ZntcPlugin + caller-side pre-warm sentinel (RFC #3833 v3 D1a'').
+ * @internal — caller (runAppBuild) 만 사용. 사용자 type-import 차단 위해 unexported.
+ * sentinel 은 string property 라 runtime 위장 방어 0 — 의도 매치용.
+ */
+type CssZntcPlugin = ZntcPlugin & {
+    readonly __cssOptions: CssPluginOptions;
+};
+export declare function css(options?: CssPluginOptions): CssZntcPlugin;
+export {};

package/dist/css/index.js

@@ -0,0 +1,69 @@
+import { readdirSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+var readFileSync$1 = readFileSync;
+import { createRequire } from "node:module";
+var createRequire$1 = createRequire;
+import { join, resolve, basename, dirname, relative } from "node:path";
+var join$1 = join;
+var resolve$1 = resolve;
+//#region loader.ts
+function requireFromAppRoot(root,fallbackRequire,specifier) {
+	const requireFromRoot = createRequire(join(root, "package.json"));
+	return requireFromAppOrFallback(requireFromRoot, fallbackRequire, specifier);
+}
+function requireFromAppOrFallback(requireFromApp,fallbackRequire,specifier) {
+	try {
+		return requireFromApp(specifier);
+	} catch (err) {
+		const code = err?.code;
+		if (code !== "MODULE_NOT_FOUND" && code !== "ERR_MODULE_NOT_FOUND")throw err;
+		return fallbackRequire(specifier);
+	}
+}
+//#endregion
+//#region postcss.ts
+async function loadPostcssConfig(root,configEnv,fallbackRequire,requireBase) {
+	const reqBase = requireBase ?? root,postcssrc = requireFromAppRoot(reqBase, fallbackRequire, "postcss-load-config"),postcssModule = requireFromAppRoot(reqBase, fallbackRequire, "postcss"),postcss = postcssModule.default ?? postcssModule,config = await postcssrc({ cwd: root, env: configEnv.mode }, root).catch((err) => {
+		if (err?.message?.includes("No PostCSS Config found"))return null;
+		throw err;
+	});
+	if (!config)return null;
+	const plugins = config.plugins ?? [];
+	if (plugins.length === 0)return null;
+	return { postcss, plugins, options: config.options ?? {}, configFile: config.file ?? null };
+}
+//#endregion
+//#region index.ts
+function css(options={}) {
+	return { name: "@zntc/web/css", __cssOptions: options, setup(build) {
+		if (options.disabled)return;
+		build.onLoad({ filter: /(?<!\.module)\.css$/ }, async (args) => {
+			const input = readFileSync$1(args.path, "utf8"),root = options.root ?? process.cwd(),fallbackRequire = createRequire$1(import.meta.url),mode = options.mode ?? "production";
+			let plugins,postcssOptions,postcssModule;
+			const overridePlugins = options.postcss?.plugins;
+			if (overridePlugins && overridePlugins.length > 0) {
+				try {
+					postcssModule = (await import("postcss")).default;
+				} catch {
+					return { contents: input };
+				}
+				plugins = overridePlugins;
+				postcssOptions = options.postcss?.options ?? {};
+			} else {
+				let loaded;
+				try {
+					loaded = await loadPostcssConfig(root, { mode }, fallbackRequire);
+				} catch {
+					return { contents: input };
+				}
+				if (!loaded)return { contents: input };
+				plugins = loaded.plugins;
+				postcssOptions = loaded.options ?? {};
+				postcssModule = loaded.postcss;
+			}
+			const result = await postcssModule(plugins).process(input, { ...postcssOptions, from: args.path, to: args.path });
+			return { contents: result.css, map: result.map?.toString(), loader: "css" };
+		});
+	} };
+}
+export { css };
+//#endregion

package/dist/dev-controller.d.ts

@@ -9,11 +9,31 @@ export interface AppDevControllerOptions {
     base?: string | undefined;
     publicPath?: string | undefined;
     appRoot?: string | undefined;
+    /** React Fast Refresh preamble(`/__zntc_react_refresh__`) 을 HTML 에 주입할지.
+     *  react 미설치(=비-React 앱)면 주입 자체를 스킵(404 노이즈 방지). */
+    reactRefresh?: boolean | undefined;
     entryHtml?: string | undefined;
     publicDir?: string | false | undefined;
     envDir?: string | undefined;
     envPrefixes?: readonly string[] | undefined;
     logLevel?: string | undefined;
+    /** caller-side pre-warm PostCSS override (RFC #3833 v3 D1a'' Phase 2). 사용자
+     *  explicit `plugins: [css({postcss:{...override}})]` 의 옵션을 runAppDev 가
+     *  추출해 controller 에 전달. prepare 의 `postcssOverride` + afterBundle 의
+     *  `runPostcssForAppDev` override 둘 다에 동일 값. build path 와 dev path 의
+     *  PostCSS plugin set 일치 (dev/build divergence 해소). */
+    postcssOverride?: {
+        plugins: unknown[];
+        options?: Record<string, unknown>;
+        /** issue #3851 — css({root}) override 가 controller path 로 전달될 때 type
+         *  보존 (TS 사용자가 명시적으로 root 줄 수 있도록). runtime 은 prepare →
+         *  runPostcssIfConfigured 가 동일 field name 으로 read. */
+        root?: string;
+    } | null;
+    /** issue #3857 — css({root}) 단독 명시 시 findPostcssConfig search base.
+     *  controller 가 prepareAppCssPipelineRoot 의 cssAutoDiscoverRoot 옵션으로
+     *  forward. monorepo edge (app 이 sub-package, postcss.config 가 monorepo root). */
+    cssAutoDiscoverRoot?: string | null;
 }
 export interface AppDevControllerDeps {
     /** dev/build 의 NAPI sync wrapper — core 가 이미 세션에서 init 됐다고 가정. */
@@ -32,11 +52,36 @@ export interface PrepareAppCssPipelineRootOptions {
     dirtyPaths?: readonly string[] | null;
     /** 이전 prep 의 stylePipelineFiles + styleSourceFiles — 구조 변화 없으면 재사용. */
     cache?: PipelineCache | null;
+    /** sass @import reverse-dep 맵(tempRoot 기준 path): dep → 그 dep 을 import 한 파일들. dev 세션이
+     *  소유하고 prep 마다 갱신/조회한다. dirty 한 sass 가 다른 root scss 의 dep 이면 그 root 도 재컴파일
+     *  대상에 transitive 추가 — partial(`_x.scss`) 변경 시 stale CSS 방지 (#71). */
+    sassReverseDep?: Map<string, Set<string>> | null;
+    /** caller-side pre-warm 으로 전달되는 PostCSS override (RFC #3833 v3 D1a''). 사용자
+     *  explicit `plugins: [css({ postcss: {...override} })]` 의 옵션을 runAppBuild 가
+     *  추출해 prepareAppCssPipelineRoot 로 전달. truthy + plugins.length>0 면 자동 발견
+     *  skip 후 override 직접 사용. sync dispatcher × async onLoad 충돌 회피용 path. */
+    postcssOverride?: {
+        plugins: unknown[];
+        options?: Record<string, unknown>;
+        /** issue #3851 — css({root}) override 의 postcss require base. 미지정 시
+         *  root 인자 fallback. AppDevControllerOptions.postcssOverride.root 와 동일
+         *  field — controller 가 forward. */
+        root?: string;
+    } | null;
+    /** issue #3857 — css({root}) 단독 명시 (postcss override 없이) 시 root 가
+     *  auto-discover path 의 findPostcssConfig 시작 base 로 사용되게 caller 가
+     *  전달. monorepo edge: app 이 sub-package, postcss.config 가 monorepo root.
+     *  미지정 시 root 인자 사용 — 기존 동작 유지. */
+    cssAutoDiscoverRoot?: string | null;
 }
 export interface AppCssPipelineResult {
     tempRoot: string;
     generatedCssAbsPaths: string[];
     cache: PipelineCache;
+    /** issue #3850 — PostCSS message 의 deps/dirDeps 보존. afterBundle skipPostcssRun
+     *  path 가 watch trigger 정합 위해 사용 (tailwind `@source` 같은 dir-dep). */
+    postcssDeps?: Set<string>;
+    postcssDirDeps?: Set<string>;
 }
 export declare function cleanupPostcssTempRoot(tempRoot: string): void;
 /**
@@ -47,6 +92,10 @@ export declare function cleanupPostcssTempRoot(tempRoot: string): void;
  * Incremental — existingTempRoot + dirtyPaths 가 있으면 그 파일만 cp / 삭제 처리,
  * cache 가 있으면 stylePipelineFiles / styleSourceFiles tree walk 도 skip.
  */
+/** #71: sass `loadedUrls`(전이 @import, 자기 자신 포함)로 reverse-dep 맵(dep → 그것을 import 한
+ *  파일들)을 갱신. self/비-file URL 제외. dep 맵은 누적 — 삭제된 import 의 stale entry 는 과잉
+ *  재컴파일(느릴 뿐 correctness 안전)이라 정리하지 않는다. */
+export declare function recordSassReverseDep(reverseDep: Map<string, Set<string>>, file: string, loadedUrls: readonly URL[]): void;
 export declare function prepareAppCssPipelineRoot(root: string, outdir: string, configEnv: ConfigEnv, logLevel: string | undefined, phase: string, deps: AppDevControllerDeps, options?: PrepareAppCssPipelineRootOptions): Promise<AppCssPipelineResult | null>;
 export interface AppDevPrepareResult {
     entryPath: string;
@@ -56,6 +105,15 @@ export interface AppDevController {
     readonly outdir: string;
     readonly base: string;
     prepare(dirtyPaths?: readonly string[] | null): Promise<AppDevPrepareResult>;
+    /**
+     * issue #3861 follow-up — drain (fs.watch) 의 CSS incremental path 가 PostCSS
+     * 재실행 없이 tempRoot 만 raw root 와 동기시키기 위한 minimal sync. prepare 가
+     * full pipeline (sync + PostCSS reprocess) 라 단일 CSS modify 시 전체 .css
+     * reprocess 회귀. PostCSS 는 afterBundle 의 changedPath 분기가 incremental
+     * 처리 — sync 만 충분. dirtyPaths 가 modify 면 cpSync, delete 면 rmSync
+     * (sync flow 는 prepare 와 동일 invariant).
+     */
+    syncDirty(dirtyPaths: readonly string[]): void;
     afterBundle(options?: {
         changedPath?: string | null;
     }): Promise<{
@@ -65,9 +123,23 @@ export interface AppDevController {
         processed: number;
     }>;
     injectBundleCssLinks(bundleResult: BundleResult): void;
+    /**
+     * #3813 — outdir 의 `.css` 파일을 file system 스캔해 HTML `<link>` 주입.
+     * `injectBundleCssLinks` 가 bundleResult 를 받는 것과 달리 native watch onRebuild 의
+     * graphChanged 분기처럼 bundleResult 가 없는 경로용. JS 변경이 새 CSS import 추가했을 때
+     * stale `<link>` 회귀 가드.
+     */
+    injectBundleCssLinksFromOutdir(): void;
     isPostcssConfig(absPath: string): boolean;
     isCssOnlyChange(absPath: string): boolean;
     isSassOnlyChange(absPath: string): boolean;
+    /**
+     * #3801 — drain else 분기의 CSS-derived 판정 단일 소스. inline literal endsWith 가
+     * `.less` 같은 미지원 확장자나 `.styl/.pcss` 누락으로 drift 하던 회귀 방지. CSS / Sass /
+     * postcss config / CSS Module / Sass Module 등 native watch graph 밖이라 incremental
+     * update 가 트리거되지 않는 변경을 cover.
+     */
+    isCssLikeChange(absPath: string): boolean;
     rebuildScssIncremental(absPath: string): Promise<string | null>;
     hrefFor(absPath: string): string;
 }

package/dist/dev-overlay-client.raw.js

@@ -0,0 +1,311 @@
+// zntc dev overlay client — single source of truth (src/server/dev_overlay_client.js).
+// Zig dev server (src/server/dev_server.zig) 는 @embedFile 로, @zntc/web 의 JS
+// dev server 는 readFileSync 로 raw mirror (packages/web/runtime/dev-overlay-client.raw.js)
+// 를 읽어 아래 sentinel 들을 @zntc/server/protocol 의 실제 값으로 replaceAll 한 뒤
+// 브라우저로 보낸다. raw 그대로는 동작하지 않음 — 반드시 치환 후 송신.
+//
+// Sentinel 들은 모두 `__ZNTC_HMR_*__` 패턴. 신규 추가 시 dev_server.zig 의
+// substituteOverlayPlaceholders 와 packages/web/runtime/dev-overlay-client.mjs
+// 양쪽 치환 표를 같이 갱신해야 한다.
+
+const ZNTC_HMR_WS_PATH = "__ZNTC_HMR_WS_PATH__";
+const ZNTC_HMR_MSG_ERROR = "__ZNTC_HMR_MSG_ERROR__";
+const ZNTC_HMR_MSG_CLEAR_ERROR = "__ZNTC_HMR_MSG_CLEAR_ERROR__";
+const ZNTC_HMR_MSG_UPDATE_START = "__ZNTC_HMR_MSG_UPDATE_START__";
+const ZNTC_HMR_MSG_UPDATE = "__ZNTC_HMR_MSG_UPDATE__";
+const ZNTC_HMR_MSG_UPDATE_DONE = "__ZNTC_HMR_MSG_UPDATE_DONE__";
+const ZNTC_HMR_MSG_FULL_RELOAD = "__ZNTC_HMR_MSG_FULL_RELOAD__";
+const ZNTC_HMR_MSG_CSS_UPDATE = "__ZNTC_HMR_MSG_CSS_UPDATE__";
+
+const socketProtocol = location.protocol === "https:" ? "wss:" : "ws:";
+let overlay = null;
+let closeOverlayOnEsc = null;
+function hideOverlay() {
+  if (closeOverlayOnEsc) document.removeEventListener("keydown", closeOverlayOnEsc);
+  closeOverlayOnEsc = null;
+  if (overlay && overlay.parentNode) overlay.parentNode.removeChild(overlay);
+  overlay = null;
+}
+function normalizeErrors(errors) {
+  if (!Array.isArray(errors) || errors.length === 0) {
+    return [{ file: "", message: "Unknown build error" }];
+  }
+  return errors.map(function(error) {
+    if (typeof error === "string") return { file: "", message: error };
+    return {
+      file: error && typeof error.file === "string" ? error.file : "",
+      message: error && typeof error.message === "string" ? error.message : String(error)
+    };
+  });
+}
+function normalizeRuntimeError(error, file) {
+  if (error && typeof error.stack === "string" && error.stack) {
+    return { file: file || "", message: error.stack };
+  }
+  if (error && typeof error.message === "string" && error.message) {
+    const name = typeof error.name === "string" && error.name ? error.name : "Error";
+    return { file: file || "", message: name + ": " + error.message };
+  }
+  return { file: file || "", message: String(error || "Unknown runtime error") };
+}
+const sourceMapCache = new Map();
+const sourceMapVlqChars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+function displaySourceName(source) {
+  if (!source) return "";
+  const clean = String(source).split("?")[0].split("#")[0];
+  const slash = Math.max(clean.lastIndexOf("/"), clean.lastIndexOf("\\"));
+  return slash >= 0 ? clean.slice(slash + 1) : clean;
+}
+function decodeSourceMapVlq(segment) {
+  const values = [];
+  let result = 0;
+  let shift = 0;
+  for (const ch of segment) {
+    let digit = sourceMapVlqChars.indexOf(ch);
+    if (digit < 0) return values;
+    const continuation = digit & 32;
+    digit &= 31;
+    result += digit << shift;
+    if (continuation) {
+      shift += 5;
+      continue;
+    }
+    const negative = result & 1;
+    const value = result >> 1;
+    values.push(negative ? -value : value);
+    result = 0;
+    shift = 0;
+  }
+  return values;
+}
+function parseSourceMapMappings(map) {
+  if (map.__zntcParsedMappings) return map.__zntcParsedMappings;
+  let source = 0;
+  let originalLine = 0;
+  let originalColumn = 0;
+  let name = 0;
+  const parsed = [];
+  for (const line of String(map.mappings || "").split(";")) {
+    let generatedColumn = 0;
+    const segments = [];
+    for (const segment of line.split(",")) {
+      if (!segment) continue;
+      const values = decodeSourceMapVlq(segment);
+      if (values.length === 0) continue;
+      generatedColumn += values[0];
+      if (values.length >= 4) {
+        source += values[1];
+        originalLine += values[2];
+        originalColumn += values[3];
+        if (values.length >= 5) name += values[4];
+        segments.push({ generatedColumn, source, originalLine, originalColumn });
+      }
+    }
+    parsed.push(segments);
+  }
+  Object.defineProperty(map, "__zntcParsedMappings", { value: parsed });
+  return parsed;
+}
+function findOriginalPosition(map, line, column) {
+  const segments = parseSourceMapMappings(map)[line - 1];
+  if (!segments || segments.length === 0) return null;
+  let lo = 0;
+  let hi = segments.length - 1;
+  let best = null;
+  while (lo <= hi) {
+    const mid = (lo + hi) >> 1;
+    const segment = segments[mid];
+    if (segment.generatedColumn <= column) {
+      best = segment;
+      lo = mid + 1;
+    } else {
+      hi = mid - 1;
+    }
+  }
+  best = best || segments[0];
+  const source = map.sources && map.sources[best.source];
+  if (!source) return null;
+  const columnOffset = Math.max(0, column - best.generatedColumn);
+  return {
+    source: displaySourceName(source),
+    line: best.originalLine + 1,
+    column: best.originalColumn + columnOffset,
+  };
+}
+async function loadSourceMapForGeneratedUrl(url) {
+  const generatedUrl = new URL(url, location.href).href;
+  if (sourceMapCache.has(generatedUrl)) return sourceMapCache.get(generatedUrl);
+  async function safeJson(response) {
+    try { return await response.json(); } catch (_) { return null; }
+  }
+  const promise = (async function() {
+    const direct = await fetch(generatedUrl + ".map", { cache: "no-store" }).catch(function() { return null; });
+    if (direct && direct.ok) return safeJson(direct);
+    const jsResponse = await fetch(generatedUrl, { cache: "no-store" }).catch(function() { return null; });
+    if (!jsResponse || !jsResponse.ok) return null;
+    const code = await jsResponse.text();
+    const match =
+      code.match(/\/\/[#@]\s*sourceMappingURL=([^\n\r]+)/) ||
+      code.match(/\/\*[#@]\s*sourceMappingURL=([^*]+)\*\//);
+    if (!match) return null;
+    const ref = match[1].trim();
+    if (ref.startsWith("data:")) {
+      const comma = ref.indexOf(",");
+      if (comma < 0) return null;
+      const meta = ref.slice(0, comma);
+      const data = ref.slice(comma + 1);
+      try {
+        const json = meta.includes(";base64") ? atob(data) : decodeURIComponent(data);
+        return JSON.parse(json);
+      } catch (_) {
+        return null;
+      }
+    }
+    const mapResponse = await fetch(new URL(ref, generatedUrl).href, { cache: "no-store" }).catch(function() { return null; });
+    return mapResponse && mapResponse.ok ? safeJson(mapResponse) : null;
+  })();
+  sourceMapCache.set(generatedUrl, promise);
+  return promise;
+}
+async function mapGeneratedLocation(url, line, column) {
+  const map = await loadSourceMapForGeneratedUrl(url);
+  return map ? findOriginalPosition(map, line, column) : null;
+}
+async function mapLocationText(text) {
+  if (!text) return text;
+  const match = String(text).match(/(https?:\/\/[^\s)]+):(\d+):(\d+)/);
+  if (!match) return text;
+  const mapped = await mapGeneratedLocation(match[1], Number(match[2]), Number(match[3]));
+  if (!mapped) return text;
+  return String(text).replace(match[0], mapped.source + ":" + mapped.line + ":" + mapped.column);
+}
+async function mapStackTrace(stack) {
+  if (typeof stack !== "string") return stack;
+  const lines = await Promise.all(stack.split("\n").map(mapLocationText));
+  return lines.join("\n");
+}
+async function normalizeRuntimeErrorWithSourceMap(error, file) {
+  const item = normalizeRuntimeError(error, file);
+  item.file = await mapLocationText(item.file);
+  item.message = await mapStackTrace(item.message);
+  return item;
+}
+async function showRuntimeOverlay(error, file) {
+  let item;
+  try {
+    item = await normalizeRuntimeErrorWithSourceMap(error, file);
+  } catch (_) {
+    item = normalizeRuntimeError(error, file);
+  }
+  showOverlay([item], "Runtime Error");
+}
+function showOverlay(errors, titleText = "Build Error") {
+  hideOverlay();
+  const items = normalizeErrors(errors);
+  overlay = document.createElement("div");
+  overlay.id = "zntc-error-overlay";
+  const root = overlay.attachShadow({ mode: "open" });
+  const style = document.createElement("style");
+  style.textContent = ":host{position:fixed;inset:0;z-index:2147483647;display:block;--font:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;--red:#fb7185;--text:#f8fafc;--blue:#93c5fd;--window:#181818;}" +
+    ".backdrop{position:fixed;inset:0;overflow:auto;padding:32px;box-sizing:border-box;background:rgba(0,0,0,.66);font:14px/1.5 var(--font);color:var(--text);}" +
+    ".window{max-width:980px;margin:0 auto;background:var(--window);border-top:8px solid var(--red);border-radius:6px 6px 8px 8px;box-shadow:0 19px 38px rgba(0,0,0,.30),0 15px 12px rgba(0,0,0,.22);overflow:hidden;}" +
+    ".header{display:flex;align-items:center;justify-content:space-between;gap:16px;padding:18px 20px;border-bottom:1px solid rgba(255,255,255,.12);}" +
+    ".title{font-size:18px;font-weight:700;color:#fecdd3;}" +
+    ".close{width:30px;height:30px;border:1px solid rgba(255,255,255,.25);border-radius:4px;background:#111827;color:var(--text);cursor:pointer;font:18px/1 var(--font);}" +
+    ".card{padding:18px 20px;border-top:1px solid rgba(255,255,255,.08);}" +
+    ".file{margin-bottom:10px;color:var(--blue);word-break:break-all;}" +
+    ".message{margin:0;white-space:pre-wrap;color:#fff;word-break:break-word;font:14px/1.5 var(--font);}";
+  const backdrop = document.createElement("div");
+  backdrop.className = "backdrop";
+  const panel = document.createElement("div");
+  panel.className = "window";
+  panel.onclick = function(event) { event.stopPropagation(); };
+  const header = document.createElement("div");
+  header.className = "header";
+  const title = document.createElement("div");
+  title.className = "title";
+  title.textContent = titleText;
+  const close = document.createElement("button");
+  close.type = "button";
+  close.textContent = "x";
+  close.className = "close";
+  close.setAttribute("aria-label", "Close error overlay");
+  close.onclick = hideOverlay;
+  header.appendChild(title);
+  header.appendChild(close);
+  panel.appendChild(header);
+  for (const item of items) {
+    const card = document.createElement("div");
+    card.className = "card";
+    if (item.file) {
+      const file = document.createElement("div");
+      file.className = "file";
+      file.textContent = item.file;
+      card.appendChild(file);
+    }
+    const message = document.createElement("pre");
+    message.className = "message";
+    message.textContent = item.message;
+    card.appendChild(message);
+    panel.appendChild(card);
+  }
+  backdrop.appendChild(panel);
+  root.appendChild(style);
+  root.appendChild(backdrop);
+  closeOverlayOnEsc = function(event) {
+    if (event.key === "Escape" || event.code === "Escape") hideOverlay();
+  };
+  document.addEventListener("keydown", closeOverlayOnEsc);
+  (document.body || document.documentElement).appendChild(overlay);
+}
+globalThis.__zntc_show_error_overlay = showOverlay;
+globalThis.__zntc_clear_error_overlay = hideOverlay;
+if (!globalThis.__zntc_runtime_listeners_attached) {
+  globalThis.__zntc_runtime_listeners_attached = true;
+  window.addEventListener("error", function(event) {
+    const file = event.filename ? event.filename + ":" + event.lineno + ":" + event.colno : "";
+    showRuntimeOverlay(event.error || event.message, file);
+  });
+  window.addEventListener("unhandledrejection", function(event) {
+    showRuntimeOverlay(event.reason, "");
+  });
+}
+const socket = new WebSocket(socketProtocol + "//" + location.host + ZNTC_HMR_WS_PATH);
+socket.addEventListener("message", function(event) {
+  const msg = JSON.parse(event.data);
+  if (msg.type === ZNTC_HMR_MSG_ERROR) { showOverlay(msg.errors); return; }
+  if (msg.type === ZNTC_HMR_MSG_CLEAR_ERROR) { hideOverlay(); return; }
+  if (msg.type === ZNTC_HMR_MSG_UPDATE_START) return;
+  if (msg.type === ZNTC_HMR_MSG_UPDATE_DONE) { hideOverlay(); return; }
+  if (msg.type === ZNTC_HMR_MSG_FULL_RELOAD) { hideOverlay(); location.reload(); return; }
+  if (msg.type === ZNTC_HMR_MSG_UPDATE) {
+    hideOverlay();
+    if (typeof __zntc_apply_update === "function") __zntc_apply_update(msg.modules);
+    else location.reload();
+    return;
+  }
+  if (msg.type === ZNTC_HMR_MSG_CSS_UPDATE) {
+    hideOverlay();
+    const targetPath = msg.href || msg.file;
+    const stamp = msg.timestamp || Date.now();
+    const links = Array.from(document.querySelectorAll('link[rel="stylesheet"]'));
+    let updated = false;
+    for (const link of links) {
+      const href = link.getAttribute("href");
+      if (!href) continue;
+      const current = new URL(href, location.href);
+      const target = new URL(targetPath || current.pathname, location.href);
+      if (targetPath && current.pathname !== target.pathname) continue;
+      const next = new URL(current.href);
+      next.searchParams.set("t", String(stamp));
+      const replacement = link.cloneNode();
+      replacement.href = next.href;
+      replacement.onload = function() { link.remove(); };
+      replacement.onerror = function() { location.reload(); };
+      link.after(replacement);
+      updated = true;
+    }
+    if (!updated) location.reload();
+  }
+});
+

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-export { APP_DEV_HMR_CLIENT_PATH, APP_DEV_HMR_WS_PATH, type BunHmrClient, createHmrChannel, createWatcher, type CreateWatcherOptions, HMR_MSG, type HmrChannel, type HmrConnectedMessage, type HmrCssUpdateMessage, type HmrError, type HmrErrorMessage, type HmrFullReloadMessage, type HmrMessage, type HmrMessageType, type WatchEventType, type WatchFn, type WatchListener, type WatcherHandle, type WatcherInstance, } from '@zntc/server';
-export { type BundleResult, injectAppDevBundleCssLinks, injectAppDevHmrClient, injectAppDevPipelineCssLinks, injectIntoDevHtml, } from './inject.ts';
+export { APP_DEV_HMR_CLIENT_PATH, APP_DEV_HMR_WS_PATH, APP_DEV_REACT_REFRESH_PATH, broadcastRebuildEvent, type BunHmrClient, createHmrChannel, createWatcher, type CreateWatcherOptions, HMR_MSG, type HmrChannel, type HmrConnectedMessage, type HmrCssUpdateMessage, type HmrError, type HmrErrorMessage, type HmrFullReloadMessage, type HmrMessage, type HmrMessageType, type HmrUpdateDoneMessage, type HmrUpdateMessage, type HmrUpdateModule, type HmrUpdateStartMessage, type RebuildBroadcastOutcome, type RebuildEventLike, type WatchEventType, type WatchFn, type WatchListener, type WatcherHandle, type WatcherInstance, } from '@zntc/server';
+export { type BundleResult, injectAppDevBundleCssLinks, injectAppDevBundleCssLinksFromOutdir, injectAppDevHmrClient, injectAppDevPipelineCssLinks, injectAppDevReactRefreshPreamble, injectIntoDevHtml, } from './inject.ts';
+export { buildReactRefreshPreamble } from './react-refresh-preamble.ts';
 export { DEFAULT_HTML_ENV_PREFIX, type TransformHtmlEnvResult, applyHtmlEnvTokens, transformHtmlEnvTokens, } from './html-env.ts';
 export { joinUrl } from './url.ts';
 export { isCssIdent, isCssIdentStart, skipCssString, skipCssUrl, startsWithCssIdent, } from './style/css-parser.ts';