@zntc/react-native 0.1.2 → 0.1.4

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 동시 요청 시