@zntc/react-native 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ohah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+# @zntc/react-native
+
+ZNTC 의 React Native platform layer (#2540).
+
+## 역할
+
+- **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`.
+
+## 비범위 (이 패키지가 안 함)
+
+- 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` 영역
+
+## 설치
+
+```bash
+bun add -D @zntc/react-native @zntc/core
+# 사용 환경에 따라 optional:
+# bun add -D @babel/core @react-native/babel-preset metro-resolver react-native
+```
+
+## 사용 예
+
+```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',
+    dev: false,
+    sourcemap: true,
+  }),
+);
+```
+
+## 관련 epic
+
+- #2539 — `@zntc/web` + `@zntc/server` 분리 (선행, 완료)
+- #2540 — 본 패키지 신설
+- #2538 — Zig 단일 dev server (후속)

package/dist/dev-server/hmr-bridge.d.ts

@@ -0,0 +1,22 @@
+import type { IncomingMessage } from 'node:http';
+import type { Socket } from 'node:net';
+import { type MetroHmrAdapter } from '../metro-hmr-adapter.ts';
+import type { PlatformStateCallbacks } from './platform-state.ts';
+export interface HmrBridgeOptions {
+    /** ws path. Metro 호환 default `/hot`. */
+    readonly path: string;
+    /** rebuild log 출력 비활성 (test 환경). default false. */
+    readonly silent?: boolean;
+    /** Metro `server.forwardClientLogs` 호환. default true. */
+    readonly forwardClientLogs?: boolean;
+}
+export interface HmrBridge {
+    readonly adapter: MetroHmrAdapter;
+    readonly callbacks: PlatformStateCallbacks;
+    readonly path: string;
+    /** http upgrade chain 안에서 호출 — channel.accept + initial greeting. */
+    acceptUpgrade(req: IncomingMessage, socket: Socket): void;
+    /** RN runtime console.log forwarding 출력 표시 toggle. 새 상태 반환. */
+    toggleLogs(): boolean;
+}
+export declare function createHmrBridge(options: HmrBridgeOptions): HmrBridge;

package/dist/dev-server/http-server.d.ts

@@ -0,0 +1,32 @@
+import { type Server } from 'node:http';
+import type { HmrBridge } from './hmr-bridge.ts';
+import type { CliServerApi } from './middleware/cli-server-api.ts';
+import { type DevMiddleware } from './middleware/dev-middleware.ts';
+import type { RnDevServerOptions } from './options.ts';
+import type { PlatformStateRegistry } from './platform-state.ts';
+import type { Broadcast, Middleware } from './types.ts';
+export interface DevHttpServerDeps {
+    /** WS broadcast — caller 가 cli-server-api 의 messageSocketEndpoint.broadcast 와 wire. */
+    broadcast: Broadcast;
+    /** per-platform state — bundle/map/hmr-map 라우트가 plat 분기 시 사용. */
+    platforms: PlatformStateRegistry;
+    /** HMR bridge — `/hot` upgrade 핸들 + adapter. 미지정 시 HMR 비활성. */
+    hmrBridge?: HmrBridge;
+    /** RN DevTools dev-middleware (peer optional). 미지정 시 inspector 비활성. */
+    devMiddleware?: DevMiddleware;
+    /** cli-server-api 의 websocket endpoints (peer optional). */
+    cliServerApi?: CliServerApi;
+}
+export interface DevHttpServerHandle {
+    readonly server: Server;
+    readonly url: string;
+    readonly port: number;
+    stop(): Promise<void>;
+}
+/**
+ * Base middleware — status/reload/devmenu/open-url 4 라우트만 처리. 매칭 못
+ * 한 path 는 next() 로 위임. user enhanceMiddleware (rozenite 등) 가 chain
+ * 의 어느 layer 든 가로챌 수 있도록 connect-style next 호출.
+ */
+export declare function createBaseMiddleware(options: RnDevServerOptions, deps: DevHttpServerDeps): Middleware;
+export declare function createDevHttpServer(options: RnDevServerOptions, deps: DevHttpServerDeps): Promise<DevHttpServerHandle>;

package/dist/dev-server/http-utils.d.ts

@@ -0,0 +1,11 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export declare function sendText(res: ServerResponse, statusCode: number, text: string, contentType?: string): void;
+export declare function sendJson(res: ServerResponse, statusCode: number, data: unknown): void;
+/**
+ * POST body 를 JSON 으로 read. Connect/Express middleware (e.g. cli-server-api
+ * 의 rawBodyMiddleware, @rozenite/middleware 의 express.json()) 가 stream 을 미리
+ * drain 한 경우 augmented `req.body` / `req.rawBody` 에서 복구 — 그렇지 않으면
+ * `req.on('data')` 가 영원히 발화 안 해 hang.
+ */
+export declare function readJsonBody<T>(req: IncomingMessage): Promise<T>;
+export declare function parseRequestUrl(req: IncomingMessage, fallbackHost: string, fallbackPort: number): URL;

package/dist/dev-server/index.d.ts

@@ -0,0 +1,18 @@
+export { createHmrBridge, type HmrBridge, type HmrBridgeOptions } from './hmr-bridge.ts';
+export { type RnDevServerHandle, serveRn, type ServeRnExtras } from './serve.ts';
+export { type CliServerApi, type CliWebsocketEndpoint, loadCliServerApi, type LoadCliServerApiOptions, } from './middleware/cli-server-api.ts';
+export { type DevMiddleware, loadDevMiddleware, type LoadDevMiddlewareOptions, } from './middleware/dev-middleware.ts';
+export { createBaseMiddleware, createDevHttpServer, type DevHttpServerDeps, type DevHttpServerHandle, } from './http-server.ts';
+export { parseRequestUrl, readJsonBody, sendJson, sendText } from './http-utils.ts';
+export type { CustomizeFrame, RnDevServerOptions, RnDevServerOptionsInput } from './options.ts';
+export { buildRnDevServerOptions } from './options.ts';
+export { colors, formatLogBadge, logBundle, logError, logInfo, logWarn, printZntcRnBanner, } from './logger.ts';
+export { createPlatformState, createPlatformStateRegistry, getCachedSourceMap, type PlatformState, type PlatformStateCallbacks, type PlatformStateRegistry, waitForBuild, } from './platform-state.ts';
+export { type AssetResolverOptions, handleAssetRequest, isAssetRoute, resolveAssetPath, } from './routes/assets.ts';
+export { handleIndexPage, isIndexRoute } from './routes/index-page.ts';
+export { handleBundleRequest, handleHmrMapRequest, handleMapRequest, isBundleRoute, isHmrMapRoute, isMapRoute, } from './routes/bundle.ts';
+export { handleSymbolicateRequest, isSymbolicateRoute } from './routes/symbolicate.ts';
+export { postProcessSourceMap, type SourcemapPathOptions } from './sourcemap.ts';
+export { setupTerminalActions, type TerminalActionsCallbacks, type TerminalActionsOptions, } from './terminal-actions.ts';
+export { applyCustomizeFrame, createSourceMapConsumer, extractCodeFrame, normalizeFrame, symbolicateFrame, type SymbolicateCodeFrame, type SymbolicateRequest, type SymbolicateResponse, } from './symbolicate-source.ts';
+export type { Broadcast, FrameInfo, Middleware, MiddlewareEnhanceContext } from './types.ts';

package/dist/dev-server/logger.d.ts

@@ -0,0 +1,35 @@
+export declare const colors: {
+    readonly reset: "\u001B[0m";
+    readonly bold: "\u001B[1m";
+    readonly dim: "\u001B[2m";
+    readonly inverse: "\u001B[7m";
+    readonly white: "\u001B[37m";
+    readonly gray: "\u001B[90m";
+    readonly red: "\u001B[31m";
+    readonly green: "\u001B[32m";
+    readonly yellow: "\u001B[33m";
+    readonly blue: "\u001B[34m";
+    readonly magenta: "\u001B[35m";
+    readonly cyan: "\u001B[36m";
+    readonly brightYellow: "\u001B[93m";
+    readonly brightRed: "\u001B[91m";
+};
+/** Metro 호환 ` INFO ` cyan inverse bold badge. */
+export declare function logInfo(...args: unknown[]): void;
+export declare function logWarn(...args: unknown[]): void;
+export declare function logError(...args: unknown[]): void;
+/**
+ * RN runtime 의 console.log 를 dev server 터미널로 forward 시 사용 — Metro 호환
+ * level 별 색상 INVERSE BOLD badge. error=red / warn=yellow / debug=magenta /
+ * info=cyan / log=white. bungae graph-bundler/utils.ts 패턴 동등.
+ */
+export declare function formatLogBadge(level: string): string;
+/**
+ * Metro `TerminalReporter._getBundleStatusMessage` 호환 BUNDLE 상태 라인.
+ * `done` 녹색 / `failed` 빨강 / `request` 노랑.
+ */
+export declare function logBundle(phase: 'done' | 'failed' | 'request', platform: string, subject: string, detail?: string): void;
+export declare const ZNTC_ASCII: readonly ["▀▀▀▀▀▀▀▀", "▀▀▀▀▀▀▀▀▀▀▀▀", "▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀", "▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀", "▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀"];
+export declare const ZNTC_GRADIENT: readonly string[];
+/** ZNTC RN dev server 시작 banner — ASCII 로고 + 그라디언트 + 박스. */
+export declare function printZntcRnBanner(version?: string): void;

package/dist/dev-server/middleware/cli-server-api.d.ts

@@ -0,0 +1,25 @@
+import type { IncomingMessage } from 'node:http';
+import type { Duplex } from 'node:stream';
+import type { Broadcast } from '../types.ts';
+export interface CliWebsocketEndpoint {
+    handleUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer, callback: (ws: unknown) => void): void;
+    emit(event: string, ws: unknown, req: IncomingMessage): void;
+}
+export interface CliServerApi {
+    /** ws path → endpoint. /message, /events, /debugger-proxy 등. */
+    websocketEndpoints: Record<string, CliWebsocketEndpoint>;
+    /** 모든 ws client 에 broadcast — RN runtime 의 `/reload` / `/devmenu` 메시지. */
+    broadcast: Broadcast;
+}
+export interface LoadCliServerApiOptions {
+    port: number;
+    host: string;
+    /**
+     * peer dependency resolve base — 사용자 프로젝트 root. cli-server-api 가
+     * `@zntc/react-native/node_modules` 가 아니라 caller (예: `examples/react-native-bare`)
+     * 의 node_modules 에 설치된 경우 dynamic import 가 못 찾는 문제 회피용.
+     * 미지정 시 `process.cwd()`.
+     */
+    projectRoot?: string;
+}
+export declare function loadCliServerApi(options: LoadCliServerApiOptions): Promise<CliServerApi | null>;

package/dist/dev-server/middleware/dev-middleware.d.ts

@@ -0,0 +1,33 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Duplex } from 'node:stream';
+export interface DevMiddleware {
+    middleware: (req: IncomingMessage, res: ServerResponse, next: (err?: unknown) => void) => void;
+    websocketEndpoints: Record<string, {
+        handleUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer, callback: (ws: unknown) => void): void;
+        emit(event: string, ws: unknown, req: IncomingMessage): void;
+    }>;
+}
+/**
+ * Expo 프로젝트는 Rozenite가 @expo/cli 기준의 @react-native/dev-middleware
+ * instance를 monkey-patch한다. 같은 module instance를 로드해야 RN DevTools
+ * frontend URL 패치가 적용되므로 expo → @expo/cli → react-native CLI chain
+ * 순서로 resolve. fallback 으로 project 직접 / zntc 자기.
+ */
+export declare function resolveDevMiddlewarePath(projectRoot: string): string | null;
+export interface LoadDevMiddlewareOptions {
+    port: number;
+    projectRoot: string;
+}
+/**
+ * `@react-native/dev-middleware` 가 설치돼있으면 DevMiddleware instance,
+ * 아니면 null. errors swallow + console.warn (caller 가 dev server 띄우는 데
+ * 영향 없도록).
+ */
+export declare function loadDevMiddleware(options: LoadDevMiddlewareOptions): Promise<DevMiddleware | null>;
+export declare const DEV_MIDDLEWARE_PATH_PREFIXES: string[];
+/**
+ * dev-middleware path prefix 의 정확 경계 매칭. `/jsonbomb` 같은 우연한
+ * substring 일치를 막기 위해 정확한 path 또는 슬래시 경계 + tail 만 허용.
+ * bungae Server.js 의 prefix 매칭과 동일 패턴 (#2605 audit).
+ */
+export declare function isDevMiddlewareRoute(pathname: string): boolean;

package/dist/dev-server/options.d.ts

@@ -0,0 +1,30 @@
+import type { RnBundleInput } from '../preset.ts';
+import type { FrameInfo, Middleware, MiddlewareEnhanceContext } from './types.ts';
+/** customizeFrame `collapse:true` → DevTools 에서 frame 숨김. caller 가 try/catch 로 swallow. */
+export type CustomizeFrame = (frame: FrameInfo) => Promise<{
+    collapse?: boolean;
+} | void>;
+export interface RnDevServerOptions {
+    bundle: RnBundleInput;
+    port: number;
+    host: string;
+    /** Asset resolution 의 fallback (monorepo / pnpm / bun 의 .bun 디렉토리 등). */
+    nodeModulesPaths: readonly string[];
+    enhanceMiddleware?: (mw: Middleware, ctx: MiddlewareEnhanceContext) => Middleware;
+    /**
+     * Request URL 을 routing 전에 rewrite (Metro 호환). Argument 는 jsc-safe URL
+     * normalize 가 적용된 **full URL** (path + query). 반환값은 다시 normalize 후
+     * `req.url` 에 set. iOS/Hermes 의 jsc-safe URL 재요청을 정상 routing 하려면
+     * 미설정해도 OK — 미설정 시 normalize 만 적용.
+     */
+    rewriteRequestUrl?: (url: string) => string;
+    symbolicator?: {
+        customizeFrame?: CustomizeFrame;
+    };
+    terminalActions: boolean;
+    hmr: boolean;
+}
+export type RnDevServerOptionsInput = {
+    bundle: RnBundleInput;
+} & Partial<Omit<RnDevServerOptions, 'bundle'>>;
+export declare function buildRnDevServerOptions(input: RnDevServerOptionsInput): RnDevServerOptions;

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

@@ -0,0 +1,37 @@
+import type { WatchHandle, WatchReadyEvent, WatchRebuildEvent } from '@zntc/core';
+import type { RnDevServerOptions } from './options.ts';
+export interface PlatformState {
+    readonly platform: 'ios' | 'android';
+    readonly outputDir: string;
+    readonly outputPath: string;
+    handle: WatchHandle;
+    bundle: string | null;
+    bundleStale: boolean;
+    refreshBundle: () => Promise<void>;
+    /** rebuild 마다 invalidate. 같은 build 안에서 여러 sourcemap 요청 시 재사용. */
+    sourceMapCache: string | null;
+    buildError: string | null;
+    fileCount: number;
+    lastRebuildTime: number;
+}
+/** sourcemap lazy fetch + memoize. cache miss 시 handle 에서 build + postProcess. */
+export declare function getCachedSourceMap(state: PlatformState): string | null;
+export interface PlatformStateCallbacks {
+    onReady?: (state: PlatformState, event: WatchReadyEvent) => void;
+    onRebuild?: (state: PlatformState, event: WatchRebuildEvent) => void;
+}
+/**
+ * platform 별 watch + state 생성. 첫 build 는 비동기 — caller 가
+ * `waitForBuild(state)` 로 대기. RN runtime 이 ios+android 동시 요청 시
+ * 별도 outputDir 에 격리.
+ */
+export declare function createPlatformState(options: RnDevServerOptions, platform: 'ios' | 'android', callbacks?: PlatformStateCallbacks): PlatformState;
+/** initial build 또는 buildError 가 정해질 때까지 polling. dev server start 시점 1회. */
+export declare function waitForBuild(state: PlatformState, pollIntervalMs?: number): Promise<void>;
+/** 모든 platform 의 watch handle 종료 + outputDir cleanup (caller 책임). */
+export interface PlatformStateRegistry {
+    readonly platforms: ReadonlyMap<string, PlatformState>;
+    getOrCreate(platform: 'ios' | 'android'): PlatformState;
+    stopAll(): Promise<void>;
+}
+export declare function createPlatformStateRegistry(options: RnDevServerOptions, callbacks?: PlatformStateCallbacks): PlatformStateRegistry;

package/dist/dev-server/routes/_shared.d.ts

@@ -0,0 +1,3 @@
+import type { PlatformState, PlatformStateRegistry } from '../platform-state.ts';
+/** query param `?platform=ios|android` 검증 후 invalid 면 default. registry 에서 lazy spawn. */
+export declare function resolvePlatform(url: URL, registry: PlatformStateRegistry, defaultPlatform: 'ios' | 'android'): PlatformState;

package/dist/dev-server/routes/assets.d.ts

@@ -0,0 +1,12 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export declare function isAssetRoute(pathname: string): boolean;
+export interface AssetResolverOptions {
+    projectRoot: string;
+    nodeModulesPaths: readonly string[];
+}
+/**
+ * Metro 호환 multi-strategy resolution. node_modules 경로 안 패키지는
+ * hoisted/scoped/pnpm/bun/non-hoisted/monorepo/require.resolve 7단계로 시도.
+ */
+export declare function resolveAssetPath(urlPathname: string, opts: AssetResolverOptions): string | null;
+export declare function handleAssetRequest(_req: IncomingMessage, res: ServerResponse, url: URL, opts: AssetResolverOptions): Promise<void>;

package/dist/dev-server/routes/bundle.d.ts

@@ -0,0 +1,8 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { type PlatformStateRegistry } from '../platform-state.ts';
+export declare function isBundleRoute(pathname: string): boolean;
+export declare function isMapRoute(pathname: string): boolean;
+export declare function isHmrMapRoute(pathname: string): boolean;
+export declare function handleBundleRequest(req: IncomingMessage, res: ServerResponse, url: URL, registry: PlatformStateRegistry, defaultPlatform: 'ios' | 'android', projectRoot: string, port: number): Promise<void>;
+export declare function handleMapRequest(_req: IncomingMessage, res: ServerResponse, url: URL, registry: PlatformStateRegistry, defaultPlatform: 'ios' | 'android'): void;
+export declare function handleHmrMapRequest(_req: IncomingMessage, res: ServerResponse, url: URL, registry: PlatformStateRegistry, defaultPlatform: 'ios' | 'android'): void;

package/dist/dev-server/routes/devmenu.d.ts

@@ -0,0 +1,4 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Broadcast } from '../types.ts';
+export declare function isDevMenuRoute(pathname: string): boolean;
+export declare function handleDevMenu(_req: IncomingMessage, res: ServerResponse, broadcast: Broadcast): void;

package/dist/dev-server/routes/index-page.d.ts

@@ -0,0 +1,3 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export declare function isIndexRoute(pathname: string): boolean;
+export declare function handleIndexPage(_req: IncomingMessage, res: ServerResponse, port: number): void;

package/dist/dev-server/routes/open-url.d.ts

@@ -0,0 +1,4 @@
+import { spawn } from 'node:child_process';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export declare function isOpenUrlRoute(pathname: string, method: string | undefined): boolean;
+export declare function handleOpenUrl(req: IncomingMessage, res: ServerResponse, spawner?: typeof spawn, platform?: NodeJS.Platform): Promise<void>;

package/dist/dev-server/routes/reload.d.ts

@@ -0,0 +1,4 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Broadcast } from '../types.ts';
+export declare function isReloadRoute(pathname: string): boolean;
+export declare function handleReload(_req: IncomingMessage, res: ServerResponse, broadcast: Broadcast): void;

package/dist/dev-server/routes/status.d.ts

@@ -0,0 +1,3 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export declare function isStatusRoute(pathname: string): boolean;
+export declare function handleStatus(_req: IncomingMessage, res: ServerResponse, projectRoot: string): void;

package/dist/dev-server/routes/symbolicate.d.ts

@@ -0,0 +1,5 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { CustomizeFrame } from '../options.ts';
+import { type PlatformStateRegistry } from '../platform-state.ts';
+export declare function isSymbolicateRoute(pathname: string, method: string | undefined): boolean;
+export declare function handleSymbolicateRequest(req: IncomingMessage, res: ServerResponse, url: URL, registry: PlatformStateRegistry, defaultPlatform: 'ios' | 'android', projectRoot: string, customizeFrame: CustomizeFrame | undefined): Promise<void>;

package/dist/dev-server/serve.d.ts

@@ -0,0 +1,27 @@
+import { type HmrBridge } from './hmr-bridge.ts';
+import type { RnDevServerOptions } from './options.ts';
+import { type PlatformStateRegistry } from './platform-state.ts';
+export interface RnDevServerHandle {
+    readonly url: string;
+    readonly port: number;
+    readonly hmrBridge?: HmrBridge;
+    readonly platforms: PlatformStateRegistry;
+    stop(): Promise<void>;
+}
+/**
+ * dev server lifecycle 시작. 첫 platform 의 initial build 까지 대기 후 handle
+ * 반환. 종료는 `handle.stop()` — http server close + watch handles stop +
+ * terminal raw mode 복원 순서로 graceful.
+ */
+export interface ServeRnExtras {
+    /** package version — banner 에 표시. */
+    version?: string;
+    /** banner / startup log 출력 안 함 (test 환경 등). default false. */
+    silent?: boolean;
+    /**
+     * SIGINT/SIGTERM listener 등록 + shutdown 메시지. CLI 사용 시 default true,
+     * embed 사용 시 caller 가 직접 lifecycle 관리하면 false. default true.
+     */
+    installSignalHandlers?: boolean;
+}
+export declare function serveRn(options: RnDevServerOptions, extras?: ServeRnExtras): Promise<RnDevServerHandle>;

package/dist/dev-server/sourcemap.d.ts

@@ -0,0 +1,15 @@
+export interface SourcemapPathOptions {
+    /** Metro `sourcemapSourcesRoot` — sourcemap JSON 의 sourceRoot field. */
+    sourceRoot?: string;
+    /** Metro `sourcemapUseAbsolutePath` — sources 의 path 를 절대화. virtual module skip. */
+    useAbsolutePath?: boolean;
+    /** projectRoot — useAbsolutePath 시 base. 미설정 시 process.cwd(). */
+    projectRoot?: string;
+}
+/**
+ * sourcemap 후처리 — DevTools `x_google_ignoreList` 확장 + (옵션 시)
+ * `sourceRoot` / sources 절대화. JSON round-trip 1회로 모든 변환을 한 패스.
+ *
+ * 잘못된 JSON 또는 version != 3 이면 rawJson 반환 (caller 가 빈 응답 회피).
+ */
+export declare function postProcessSourceMap(rawJson: string, pathOpts?: SourcemapPathOptions): string;

package/dist/dev-server/symbolicate-source.d.ts

@@ -0,0 +1,54 @@
+import type { CustomizeFrame } from './options.ts';
+import type { FrameInfo } from './types.ts';
+export interface SymbolicateRequest {
+    stack: Array<Partial<FrameInfo>>;
+}
+export interface SymbolicateCodeFrame {
+    content: string;
+    location: {
+        row: number;
+        column: number;
+    };
+    fileName: string;
+}
+export interface SymbolicateResponse {
+    stack: Array<FrameInfo & {
+        collapse?: boolean;
+    }>;
+    codeFrame: SymbolicateCodeFrame | null;
+}
+interface SourceMapConsumerLike {
+    originalPositionFor(input: {
+        line: number;
+        column: number;
+    }): {
+        source: string | null;
+        line: number | null;
+        column: number | null;
+        name: string | null;
+    };
+    destroy?(): void;
+}
+/**
+ * sourceMap JSON → SourceMapConsumer. source-map@^0.7 의 SourceMapConsumer 는
+ * Promise<consumer>. 호출자가 try/finally 로 destroy 호출.
+ */
+export declare function createSourceMapConsumer(sourceMapJson: string): Promise<SourceMapConsumerLike | null>;
+/** Partial frame → 모든 필드가 채워진 FrameInfo (null fallback). */
+export declare function normalizeFrame(frame: Partial<FrameInfo>): FrameInfo;
+/** 단일 frame 역매핑. 매핑 실패 시 frame 그대로 (Metro 호환 — DevTools 가 fallback). */
+export declare function symbolicateFrame(consumer: SourceMapConsumerLike, frame: Partial<FrameInfo>, projectRoot: string): FrameInfo;
+/**
+ * frame 의 lineNumber 주변 ±2 줄 발췌 — RN runtime / DevTools 의 LogBox 가 보여줌.
+ * `.bundle` 경로는 skip — bundled module 은 readable 한 source 가 아님.
+ */
+export declare function extractCodeFrame(frames: ReadonlyArray<FrameInfo & {
+    collapse?: boolean;
+}>): Promise<SymbolicateCodeFrame | null>;
+/**
+ * customizeFrame 호출 후 collapse 적용. errors are non-fatal (Metro parity).
+ */
+export declare function applyCustomizeFrame(frame: FrameInfo, customizeFrame: CustomizeFrame | undefined): Promise<FrameInfo & {
+    collapse?: boolean;
+}>;
+export {};

package/dist/dev-server/terminal-actions.d.ts

@@ -0,0 +1,32 @@
+export interface TerminalActionsCallbacks {
+    /** `r` — RN runtime reload broadcast. */
+    onReload(): void;
+    /** `d` — Dev menu broadcast. */
+    onDevMenu(): void;
+    /** `j` — open DevTools (POST /open-debugger). */
+    onOpenDevTools(): void;
+    /** `c` — clear cache (per-platform state.bundle null 처리 등). */
+    onClearCache(): void;
+    /**
+     * `v` — RN runtime 의 console.log forwarding mute/unmute. 새 상태 반환 (true=ON,
+     * false=OFF) — INFO 피드백 메시지에 사용.
+     */
+    onToggleLogs(): boolean;
+}
+export interface TerminalActionsOptions {
+    /** false 면 listener 등록 안 하고 no-op cleanup. */
+    enabled: boolean;
+    /** TTY 가 아니면 listener 등록 skip — CI / pipe 환경 호환. */
+    stdin?: NodeJS.ReadStream;
+    /** 단축키 list 출력 callback (`?`). 미지정 시 INFO badge default. */
+    printShortcuts?(): void;
+}
+/** `?` 응답 — INFO badge + 5칸 들여쓰기 + 앞뒤 빈 줄. */
+export declare function printDefaultShortcuts(): void;
+/**
+ * 터미널 raw mode + keypress listener. 반환된 cleanup 호출 시 raw mode 해제 +
+ * listener 제거. enabled=false 또는 stdin 비-TTY 시 no-op cleanup.
+ *
+ * Ctrl+C / Ctrl+D 는 raw mode 에서 자동 SIGINT 안 가서 직접 process.kill 처리.
+ */
+export declare function setupTerminalActions(callbacks: TerminalActionsCallbacks, options?: TerminalActionsOptions): () => void;

package/dist/dev-server/types.d.ts

@@ -0,0 +1,22 @@
+import type { IncomingMessage, Server, ServerResponse } from 'node:http';
+/** Connect-style middleware (Metro / cli-server-api 호환). */
+export type Middleware = (req: IncomingMessage, res: ServerResponse, next: (err?: unknown) => void) => void;
+/** RN runtime stack frame (metro `IntermediateStackFrame` 와 structural compat). */
+export interface FrameInfo {
+    file: string | null;
+    methodName: string | null;
+    lineNumber: number | null;
+    column: number | null;
+}
+/**
+ * enhanceMiddleware hook 의 ctx. `httpServer` 는 `listen()` 전 instance — `.on("upgrade")`
+ * 등 event 등록 용도. lifecycle (close / connection limits) 은 host (serveRn) 책임.
+ */
+export interface MiddlewareEnhanceContext {
+    readonly httpServer: Server;
+}
+/**
+ * WS broadcast — cli-server-api 의 `messageSocketEndpoint.broadcast(method, params)` 와
+ * 동일 시그니처. PR #G 가 zero-mapping wire.
+ */
+export type Broadcast = (method: string, params?: Record<string, unknown>) => void;

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export { HMR_RN_MSG, type HmrRnErrorMessage, type HmrRnLogMessage, type HmrRnMessage, type HmrRnMessageType, type HmrRnReloadMessage, type HmrRnUpdateDoneMessage, type HmrRnUpdateMessage, type HmrRnUpdateModule, type HmrRnUpdateStartMessage, } from '@zntc/server';
+export { type AssetResolverOptions, type Broadcast, buildRnDevServerOptions, createBaseMiddleware, createDevHttpServer, createHmrBridge, createPlatformState, type CliServerApi, type CliWebsocketEndpoint, type DevMiddleware, loadCliServerApi, loadDevMiddleware, type LoadCliServerApiOptions, type LoadDevMiddlewareOptions, createPlatformStateRegistry, type CustomizeFrame, type DevHttpServerDeps, type DevHttpServerHandle, type FrameInfo, getCachedSourceMap, type HmrBridge, type HmrBridgeOptions, applyCustomizeFrame, createSourceMapConsumer, extractCodeFrame, handleAssetRequest, handleBundleRequest, handleHmrMapRequest, handleIndexPage, handleMapRequest, handleSymbolicateRequest, isIndexRoute, isAssetRoute, isBundleRoute, isHmrMapRoute, isMapRoute, isSymbolicateRoute, normalizeFrame, symbolicateFrame, type SymbolicateCodeFrame, type SymbolicateRequest, type SymbolicateResponse, type Middleware, type MiddlewareEnhanceContext, type PlatformState, type PlatformStateCallbacks, type PlatformStateRegistry, colors, formatLogBadge, logBundle, logError, logInfo, logWarn, postProcessSourceMap, type SourcemapPathOptions, printZntcRnBanner, resolveAssetPath, type ServeRnExtras, serveRn, setupTerminalActions, type TerminalActionsCallbacks, type TerminalActionsOptions, type RnDevServerHandle, type RnDevServerOptions, type RnDevServerOptionsInput, waitForBuild, } from './dev-server/index.ts';
+export { createMetroHmrAdapter, type MetroHmrAdapter } from './metro-hmr-adapter.ts';
+export type { CustomResolver, MetroPlatform, Resolution, ResolutionContext, } from './metro-resolver-types.ts';
+export { createAssetPlugin } from './plugins/asset.ts';
+export { createBabelPlugin, createBabelTransformer, detectCustomPlugins, isZntcNativePlugin, ZNTC_NATIVE_PLUGIN_PATTERNS, } from './plugins/babel.ts';
+export { CODEGEN_NATIVE_COMPONENT_MARKER, createCodegenPlugin, createCodegenTransformer, } from './plugins/codegen.ts';
+export { escapeRegex } from './plugins/escape-regex.ts';
+export { createMetroResolveRequestPlugin, type MetroResolveRequestOptions, } from './plugins/metro-resolve-request.ts';
+export { createRequireContextPlugin } from './plugins/require-context.ts';
+export { createStyledComponentsNativePlugin, disableStyledComponentsNativeDomProbe, STYLED_COMPONENTS_NATIVE_PATH_RE, } from './plugins/styled-components-native.ts';
+export type { PluginConfig } from './plugins/types.ts';
+export { buildRnBundleOptions, bundleRn, DEFAULT_ASSET_EXTS, type RnBundleInput, type RnWatchInput, watchRn, } from './preset.ts';
+export { resolveRnPolyfills, RN_GLOBAL_IDENTIFIERS, tryResolve } from './rn-constants.ts';
+export { HMR_CLIENT_SUFFIX, ZNTC_HMR_CLIENT_CODE } from './runtime-loader.ts';
+export { detectExpo, WINTER_POLYFILL_WARNING_PATTERN, withExpo, type ZntcRnExpoConfig, } from './withExpo.ts';