@zntc/react-native 0.1.2 → 0.1.3

package/README.md

@@ -1,48 +1,108 @@
 # @zntc/react-native
 
-ZNTC 의 React Native platform layer (#2540).
+English · **[한국어](./README_KO.md)**
 
-## 역할
+> ZNTC React Native platform layer — RN preset + Metro-compatible dev server + Reanimated worklets / Flow / Hermes.
 
-- **RN preset** — `buildRnBundleOptions(input)` / `bundleRn(input)` / `watchRn(input)`. RN-specific NAPI build 옵션 (target=es5, flow, jsx=automatic-dev, devMode, reactRefresh, polyfills, runBeforeMain, banner) 자동 적용.
-- **Metro HMR adapter** — `createMetroHmrAdapter()` (`@zntc/server.HmrChannel` 위 thin wrapper). RN runtime 의 HMRClient interface 호환 메시지 (`hmr:update-start` / `hmr:update` / `hmr:update-done` / `hmr:reload` / `hmr:error` / `log`) 송출.
-- **RN runtime** — `runtime/zntc-hmr-client.cjs` (Metro HMRClient 인터페이스 호환 RN runtime).
-- **Plugin factories** — `createAssetPlugin` / `createBabelPlugin` / `createCodegenPlugin` / `createRequireContextPlugin` / `createMetroResolveRequestPlugin`.
-- **RN 상수 / helpers** — `RN_GLOBAL_IDENTIFIERS` / `tryResolve` / `resolveRnPolyfills`.
+[![npm](https://img.shields.io/npm/v/@zntc/react-native.svg)](https://www.npmjs.com/package/@zntc/react-native)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/ohah/zntc/blob/main/LICENSE)
+
+`@zntc/react-native` adapts the [ZNTC](https://github.com/ohah/zntc) toolchain to React Native. It turns a small user input into Metro-compatible NAPI build options, ships a Metro-compatible HMR dev server, and wires in the RN-specific transforms (Flow, Reanimated worklets, Hermes target) — all built into the ZNTC core, **without Babel**.
 
-## 비범위 (이 패키지가 안 함)
+What it provides:
+
+- **RN preset** — `buildRnBundleOptions(input)` / `bundleRn(input)` / `watchRn(input)`. RN-specific build options (Hermes/ES5 target, Flow, automatic-dev JSX, worklets, dev mode, Fast Refresh, polyfills, RN prelude banner) are applied automatically.
+- **Metro-compatible dev server** — `serveRn(options)` / `buildRnDevServerOptions(input)`. Per-platform watch, HMR bridge over the `/hot` endpoint, and terminal actions, wired together for you.
+- **Metro HMR adapter** — `createMetroHmrAdapter()` emits messages compatible with the RN runtime's HMRClient interface (`hmr:update-start` / `hmr:update` / `hmr:update-done` / `hmr:reload` / `hmr:error` / `log`).
+- **RN runtime** — `runtime/zntc-hmr-client.cjs`, an HMRClient-compatible client for the RN runtime.
+- **Plugin factories** — `createAssetPlugin` / `createBabelPlugin` / `createCodegenPlugin` / `createRequireContextPlugin` / `createMetroResolveRequestPlugin`.
+- **RN constants / helpers** — `RN_GLOBAL_IDENTIFIERS` / `tryResolve` / `resolveRnPolyfills`.
 
-- HTTP server / dev-middleware / asset registry / Rozenite DevTools / open-stack-frame / symbolicate — RN-specific runtime 영역, 사용자 측 (예: bungae) 가 운영
-- iOS / Android native build orchestration (run-android / run-ios / autolinking) — `@react-native-community/cli` 영역
+Out of scope (handled elsewhere): iOS / Android native build orchestration (`run-android` / `run-ios` / autolinking) belongs to `@react-native-community/cli`.
 
-## 설치
+## Installation
 
 ```bash
 bun add -D @zntc/react-native @zntc/core
-# 사용 환경에 따라 optional:
-# bun add -D @babel/core @react-native/babel-preset metro-resolver react-native
+# npm i -D @zntc/react-native @zntc/core
+# pnpm add -D @zntc/react-native @zntc/core
+```
+
+Some features rely on optional peer packages — install the ones your setup needs:
+
+```bash
+bun add -D @babel/core @react-native/babel-preset metro-resolver react-native
 ```
 
-## 사용 예
+`@react-native-community/cli-server-api` is required for the dev server's reload / dev-menu broadcasts.
+
+## Usage
+
+### Attaching to an existing React Native CLI project
+
+The simplest path is the scaffolder, which rewrites the `start` / `bundle:*` scripts of an existing RN CLI app to use ZNTC (Metro fallback is preserved):
+
+```bash
+npx @zntc/init
+```
+
+See the [React Native guide](https://ohah.github.io/zntc/guides/react-native/) for details.
+
+### RN preset — `buildRnBundleOptions`
+
+Convert a small RN input into ZNTC NAPI build options, then run a build:
 
 ```ts
 import { init, build } from '@zntc/core';
 import { buildRnBundleOptions } from '@zntc/react-native';
 
 await init();
+
 const result = await build(
   buildRnBundleOptions({
     entry: '/abs/path/index.ts',
     projectRoot: '/abs/path',
-    rnPlatform: 'ios',
+    rnPlatform: 'ios', // 'ios' | 'android'
     dev: false,
     sourcemap: true,
   }),
 );
 ```
 
-## 관련 epic
+`bundleRn(input)` is a one-call shorthand for `build(buildRnBundleOptions(input))`, and `watchRn(input)` starts a watching build.
+
+The preset auto-enables the RN-compatible defaults (Hermes/ES5 target, Flow, worklets, polyfills, RN prelude banner, asset loaders, and so on). In dev mode it additionally enables automatic-dev JSX, Fast Refresh, and the dev-mode runtime. You can layer user overrides on top via `input.override` (dictionaries deep-merge, arrays/primitives replace).
+
+### Metro-compatible dev server — `serveRn`
+
+```ts
+import { buildRnDevServerOptions, serveRn } from '@zntc/react-native';
+
+const handle = await serveRn(
+  buildRnDevServerOptions({
+    bundle: {
+      entry: '/abs/path/index.ts',
+      projectRoot: '/abs/path',
+      rnPlatform: 'ios',
+      dev: true,
+    },
+    port: 8081,
+    host: 'localhost',
+  }),
+);
+
+// handle.url / handle.port — connect the RN app to this server
+// await handle.stop(); — graceful shutdown
+```
+
+`serveRn` lazily loads `@react-native-community/cli-server-api` and the RN dev middleware, runs a per-platform watching build, serves HMR over `/hot`, and sets up terminal actions (reload / dev menu). The HMR messages are Metro HMRClient-compatible, so the standard RN runtime connects without changes.
+
+## Documentation
+
+- Monorepo: <https://github.com/ohah/zntc>
+- Docs: <https://ohah.github.io/zntc>
+- React Native guide: <https://ohah.github.io/zntc/guides/react-native/>
+
+## License
 
-- #2539 — `@zntc/web` + `@zntc/server` 분리 (선행, 완료)
-- #2540 — 본 패키지 신설
-- #2538 — Zig 단일 dev server (후속)
+MIT

package/dist/dev-server/platform-state.d.ts

@@ -20,6 +20,30 @@ export interface PlatformStateCallbacks {
     onReady?: (state: PlatformState, event: WatchReadyEvent) => void;
     onRebuild?: (state: PlatformState, event: WatchRebuildEvent) => void;
 }
+export interface BundleRefresher {
+    /** stale 신호 — generation 을 bump 해 in-flight build 가 이 변경을 마스킹하지 못하게 한다. */
+    markStale(): void;
+    /** stale 이면 build, in-flight 면 coalesce. */
+    refresh(): Promise<void>;
+}
+/**
+ * in-flight build coalescing + generation guard. `build` 는 시작 시점 소스를 빌드하므로,
+ * 진행 중 `markStale()` 이 또 불리면(파일 재변경) 그 build 완료가 stale 을 clear 하면 안 된다
+ * (더 새로운 변경을 마스킹 → stale bundle 제공). generation 으로 가드: build 시작 시 generation
+ * 을 캡처, 완료 시 generation 이 그대로일 때만 `clearStale`. 새 staleness 가 들어왔으면 stale 을
+ * 유지해 다음 `refresh()` 가 최신 소스로 rebuild 한다. `bundleRn`/state 의존을 콜백으로 주입해
+ * race-safety 로직만 결정적으로 유닛 테스트할 수 있게 분리.
+ */
+export declare function createBundleRefresher(deps: {
+    /** 이미 신선(!bundleStale && bundle≠null)하면 build 스킵. */
+    isFresh: () => boolean;
+    /** bundleRn + state.bundle/buildError 갱신. 내부 try/catch 라 reject 하지 않음. */
+    build: () => Promise<void>;
+    /** stale=true. */
+    setStale: () => void;
+    /** stale=false. */
+    clearStale: () => void;
+}): BundleRefresher;
 /**
  * platform 별 watch + state 생성. 첫 build 는 비동기 — caller 가
  * `waitForBuild(state)` 로 대기. RN runtime 이 ios+android 동시 요청 시

package/dist/index.js

@@ -2226,7 +2226,10 @@ function createMetroResolveRequestPlugin(opts) {
 			try {
 				const result = resolveRequest({ originModulePath: args.importer ?? "", platform: metroPlatform, resolveRequest: fallbackResolver }, args.path, metroPlatform);
 				if (result.type === "sourceFile")return { path: result.filePath };
-				if (result.type === "assetFiles")return { path: result.filePaths[0] ?? args.path };
+				if (result.type === "assetFiles") {
+					const assetPath = result.filePaths[0];
+					return assetPath ? { path: assetPath } : null;
+				}
 				if (result.type === "empty")return { disabled: true };
 			} catch (err) {
 				if (err.message === DELEGATE_TO_DEFAULT_SENTINEL)return null;
@@ -2531,28 +2534,42 @@ function getBundleText(result) {
 function getBundleSourceMapText(result) {
 	return result.outputFiles.find((file) => file.path.endsWith(".map"))?.text ?? null;
 }
-function createPlatformState(options,platform,callbacks) {
-	const outputDir = mkdtempSync(join$2(tmpdir(), `zntc-rn-${platform}-`)),outputPath = join$2(outputDir, "bundle.js"),platformBundle = { ...options.bundle, rnPlatform: platform };
-	let refreshPromise = null;
-	const state = { platform, outputDir, outputPath, handle: undefined, bundle: null, bundleStale: false, refreshBundle: () => refreshPlatformBundle(), sourceMapCache: null, buildError: null, fileCount: 1, lastRebuildTime: Date.now() };
-	function refreshPlatformBundle() {
-		if (!state.bundleStale && state.bundle !== null)return Promise.resolve();
-		if (refreshPromise)return refreshPromise;
-		refreshPromise = bundleRn(platformBundle).then((result) => {
-			state.bundle = getBundleText(result);
-			const sourceMap = getBundleSourceMapText(result);
-			state.sourceMapCache = sourceMap ? postProcessSourceMap(sourceMap) : null;
-			state.buildError = null;
-			state.bundleStale = false;
-		}).catch((err) => {
-			state.bundle = null;
-			state.buildError = err instanceof Error ? err.message : String(err);
-			state.bundleStale = false;
+function createBundleRefresher(deps) {
+	let inFlight = null,generation = 0;
+	function markStale() {
+		deps.setStale();
+		generation += 1;
+	}
+	function refresh() {
+		if (deps.isFresh())return Promise.resolve();
+		if (inFlight)return inFlight;
+		const startGen = generation;
+		inFlight = deps.build().then(() => {
+			if (generation === startGen)deps.clearStale();
 		}).finally(() => {
-			refreshPromise = null;
+			inFlight = null;
 		});
-		return refreshPromise;
+		return inFlight;
 	}
+	return { markStale, refresh };
+}
+function createPlatformState(options,platform,callbacks) {
+	const outputDir = mkdtempSync(join$2(tmpdir(), `zntc-rn-${platform}-`)),outputPath = join$2(outputDir, "bundle.js"),platformBundle = { ...options.bundle, rnPlatform: platform };
+	let refresher;
+	const state = { platform, outputDir, outputPath, handle: undefined, bundle: null, bundleStale: false, refreshBundle: () => refresher.refresh(), sourceMapCache: null, buildError: null, fileCount: 1, lastRebuildTime: Date.now() };
+	refresher = createBundleRefresher({ isFresh: () => !state.bundleStale && state.bundle !== null, build: () => bundleRn(platformBundle).then((result) => {
+		state.bundle = getBundleText(result);
+		const sourceMap = getBundleSourceMapText(result);
+		state.sourceMapCache = sourceMap ? postProcessSourceMap(sourceMap) : null;
+		state.buildError = null;
+	}).catch((err) => {
+		state.bundle = null;
+		state.buildError = err instanceof Error ? err.message : String(err);
+	}), setStale: () => {
+		state.bundleStale = true;
+	}, clearStale: () => {
+		state.bundleStale = false;
+	} });
 	if (process.env.ZNTC_DEBUG_TERMINAL === "1") {
 		process.stderr.write(`[zntc:rn-dev:debug] watchRn[${platform}] sourcemap=${platformBundle.sourcemap} dev=${platformBundle.dev} outfile=${outputPath}\n`);
 	}
@@ -2576,7 +2593,7 @@ function createPlatformState(options,platform,callbacks) {
 		state.sourceMapCache = null;
 		if (platformBundle.dev) {
 			if (event.graphChanged) {
-				state.bundleStale = true;
+				refresher.markStale();
 				return state.refreshBundle().then(() => {
 					if (state.buildError) {
 						callbacks?.onRebuild?.(state, { ...event, success: false, error: state.buildError });
@@ -2586,7 +2603,7 @@ function createPlatformState(options,platform,callbacks) {
 				});
 			}
 			if (event.updates && event.updates.length > 0) {
-				state.bundleStale = true;
+				refresher.markStale();
 			}
 			callbacks?.onRebuild?.(state, event);
 			return;
@@ -2757,9 +2774,23 @@ function isOpenUrlRoute(pathname,method) {
 }
 function resolveOpener(platform=process.platform) {
 	if (platform === "darwin")return { command: "open", args: (t) => [t] };
-	if (platform === "win32")return { command: "cmd", args: (t) => ["/c", "start", "", t] };
+	if (platform === "win32")return { command: "rundll32", args: (t) => ["url.dll,FileProtocolHandler", t] };
 	return { command: "xdg-open", args: (t) => [t] };
 }
+const ALLOWED_PROTOCOLS = new Set(["http:", "https:"]);
+function isSafeBrowserUrl(target) {
+	for (let i = 0; i < target.length; i += 1) {
+		const c = target.charCodeAt(i);
+		if (c <= 0x20 || c === 0x22 || c === 0x27 || c === 0x5c)return false;
+	}
+	let parsed;
+	try {
+		parsed = new URL(target);
+	} catch {
+		return false;
+	}
+	return ALLOWED_PROTOCOLS.has(parsed.protocol);
+}
 async function handleOpenUrl(req,res,spawner=spawn,platform=process.platform) {
 	let body = {};
 	try {
@@ -2773,6 +2804,10 @@ async function handleOpenUrl(req,res,spawner=spawn,platform=process.platform) {
 		sendJson(res, 400, { error: "Invalid URL" });
 		return;
 	}
+	if (!isSafeBrowserUrl(target)) {
+		sendJson(res, 400, { error: "URL must be an http(s) URL without control characters" });
+		return;
+	}
 	try {
 		const { command:command, args:args } = resolveOpener(platform),child = spawner(command, args(target), { detached: true, stdio: "ignore" });
 		child.unref();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zntc/react-native",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "ZNTC React Native platform — Metro HMR adapter + RN preset (buildRnBundleOptions) + plugin factories + RN runtime",
   "keywords": [
     "bundler",
@@ -48,13 +48,13 @@
   },
   "dependencies": {
     "@react-native-community/cli-server-api": "^15.0.0",
-    "@zntc/core": "0.1.2",
+    "@zntc/core": "0.1.3",
     "jsc-safe-url": "^0.2.4",
     "source-map": "^0.7.4"
   },
   "devDependencies": {
     "@types/node": "^25.5.2",
-    "@zntc/server": "0.1.2"
+    "@zntc/server": "0.1.3"
   },
   "optionalDependencies": {
     "@babel/core": "^7.26.0",