@zntc/core 0.1.1 → 0.1.2

package/dist/core/index.d.cts

@@ -168,6 +168,100 @@ export declare function transpile(source: string, options?: TranspileOptions & {
 export declare function tokenize(source: string, options?: TokenizeOptions): TokenizeToken[];
 export declare function configureProfile(profile: string[], level?: 'summary' | 'detailed' | 'per-module' | 'per-pass'): void;
 export declare function profileReport(format?: 'table' | 'tree' | 'json' | 'csv'): string;
+/** @see {@link NativeModule.tlsSelfCheck} */
+export interface TlsSelfCheckOptions {
+    certPath: string;
+    keyPath: string;
+}
+/**
+ * TLS context init/deinit 만 호출하는 BoringSSL sanity 진입점.
+ *
+ * cert/key 파일을 한 번 로드해 BoringSSL 의 SSL_CTX 가 정상 생성되는지 검증.
+ * Throw 시 message 에 Zig error name 이 포함되어 caller 가 분류 가능
+ * (CertLoadFailed / KeyLoadFailed / KeyMismatch 등).
+ *
+ * NAPI binary 에 BoringSSL 이 static link 되어 있는지 + dlopen 후 symbol resolve
+ * 가 동작하는지 빠르게 확인하는 용도. 향후 본격 HTTPS dev server NAPI entry 가
+ * 추가되면 그 entry 가 같은 path 사용.
+ */
+export declare function tlsSelfCheck(options: TlsSelfCheckOptions): void;
+/** @see {@link NativeModule.startDevServer} */
+export interface StartDevServerOptions {
+    rootDir: string;
+    /**
+     * TCP port (0-65535). Default 12300. 0 은 OS-assigned ephemeral port —
+     * `getDevServerPort(handle)` 로 실제 값 조회.
+     */
+    port?: number;
+    /** Bind host. "localhost"/"127.0.0.1" (default) 또는 "0.0.0.0". */
+    host?: string;
+    /** `--bundle` entry. 지정 시 dev server 가 bundle 결과 서빙. */
+    entry?: string;
+    /** Open default browser at server URL. Default false. */
+    open?: boolean;
+    /** HTTPS cert (PEM). keyPath 와 함께 줘야. */
+    certPath?: string;
+    /** HTTPS key (PEM). certPath 와 함께 줘야. */
+    keyPath?: string;
+    /**
+     * stderr 의 banner + 모든 routine log silence. NAPI embed default true
+     * (자체 logger 가정). false 로 명시하면 stderr 출력. quiet 가드되는 카테고리
+     * 전체 리스트는 `src/server/dev_server.zig` 의 `DevServer.routineLog` doc
+     * (CANONICAL SCOPE LIST) 참조 — 단일 진실 소스.
+     *
+     * **critical 진단은 quiet 와 무관 항상 stderr** — init failure (cert 로드 /
+     * 디렉토리 못 찾음 / overlay sentinel), start fatal (host parse / listen 실패
+     * / watch thread spawn), deinit UAF 경고. 사용자가 throw 메시지 너머의 root
+     * cause 를 추적할 수 있도록 보장.
+     */
+    quiet?: boolean;
+    /**
+     * Lazy on-demand compilation. Default false. When true, the dev server builds
+     * with code-splitting + lazy mode (IIFE registry): only the entry chunk is
+     * served at `/bundle.js`, and each dynamic `import()` target is compiled on
+     * demand when the browser requests its chunk URL. Reduces cold-start time for
+     * large apps (parse work is deferred to first use).
+     *
+     * **Note**: this is honored by the native (`startDevServer`) dev server only.
+     * The `zntc dev` web CLI runs a separate JS dev server that does not yet
+     * support lazy compilation — tracked as a backlog item.
+     */
+    lazyCompilation?: boolean;
+}
+/** Opaque handle from {@link startDevServer}. */
+export type DevServerHandle = object;
+/**
+ * In-process dev server (HTTP / HTTPS) 를 native thread 에서 시작.
+ *
+ * 일반 `zntc --serve` 와 동일한 listener / routing / HMR / SSE 동작. NAPI 임베드라
+ * Node event loop 는 자유 (별도 thread 에서 listen).
+ *
+ * 반환된 handle 은 opaque. `stopDevServer(handle)` 로 graceful shutdown. JS GC
+ * 가 handle 수거 시 finalizer 가 자동 stop (safety net) — 명시 stop 권장.
+ *
+ * @example
+ * const handle = startDevServer({ rootDir: './public', port: 5173 });
+ * try {
+ *   await new Promise(r => setTimeout(r, 60_000));
+ * } finally {
+ *   stopDevServer(handle);
+ * }
+ */
+export declare function startDevServer(options: StartDevServerOptions): DevServerHandle;
+/** Graceful shutdown — idempotent. */
+export declare function stopDevServer(handle: DevServerHandle): void;
+/**
+ * startDevServer handle 의 실제 listen port.
+ *
+ * port=0 (OS-assigned ephemeral) 로 시작했을 때 실 bound port 조회. 일반적인
+ * test fixture / dynamic 환경에서 free port 자동 할당받고 그 값을 즉시 사용.
+ *
+ * @example
+ * const handle = startDevServer({ rootDir: './public', port: 0 });
+ * const port = getDevServerPort(handle);
+ * const res = await fetch(`http://127.0.0.1:${port}/`);
+ */
+export declare function getDevServerPort(handle: DevServerHandle): number;
 export type { OutputFile, Diagnostic };
 /** Return value of `meta.getModuleInfo(id)` in Rollup `manualChunks(id, meta)`. */
 export interface ManualChunksModuleInfo {
@@ -217,6 +311,9 @@ export interface ManualChunksModuleInfo {
     /** Modules that this module dynamically imports (`import()`). Includes
      * external modules. */
     dynamicallyImportedIds: string[];
+    /** Plugin이 load hook의 `{ meta }`로 부여한 메타데이터 (Rollup `info.meta` 호환).
+     * plugin이 meta를 설정하지 않은 모듈은 빈 객체 `{}` (#1880 PR2). */
+    meta: Record<string, unknown>;
 }
 /** The second argument of the `manualChunks` callback — module graph topology lookup. */
 export interface ManualChunksMeta {
@@ -297,7 +394,13 @@ export interface EmotionOptions {
         canonicalImport: [string, string];
     }>>;
 }
-/** Vite-style dev server options used by `zntc dev` / `zntc --serve`. */
+/**
+ * Vite-style dev server options used by `zntc dev` / `zntc --serve`.
+ *
+ * Note: `startDevServer()` (native NAPI) accepts extra options such as
+ * `lazyCompilation` — see {@link StartDevServerOptions}. The `zntc dev` web CLI
+ * runs a separate JS dev server and does not honor those yet (backlog).
+ */
 export interface DevServerOptions {
     /** Port to listen on. CLI `--port` overrides this value. */
     port?: number;
@@ -349,6 +452,29 @@ interface BuildOptionsCommon {
     minifyIdentifiers?: boolean;
     minifySyntax?: boolean;
     splitting?: boolean;
+    /**
+     * Lazy on-demand compilation primitive (dev-only). Requires `splitting: true` +
+     * `devMode: true`. When true, dynamic `import()` targets are left as UNPARSED
+     * "lazy seeds" (emit-skipped); the entry references them by stable path-hash name
+     * (`__zntc_load_chunk("<stem>-<pathHash>.js")`), and the result exposes
+     * {@link NativeBuildResult.lazySeeds}. A dev server compiles each seed on demand
+     * by rebuilding with `lazyForceParse: [seedPath]`. Low-level primitive — the web
+     * CLI dev server orchestrates this; most users use it indirectly.
+     */
+    lazyCompilation?: boolean;
+    /**
+     * Force-parse specific lazy seeds even under `lazyCompilation: true` — array of
+     * dynamic-import target paths to compile eagerly instead of deferring. A dev
+     * server passes the requested seed's path here to materialize exactly that
+     * on-demand chunk. No effect without `lazyCompilation: true`.
+     *
+     * **Contract**: each entry must be the EXACT path from a {@link NativeBuildResult.lazySeeds}
+     * entry's `.path` (the bundler-resolved absolute path — e.g. symlink-resolved
+     * `/private/tmp/...`, not your own `./x` specifier). A path that doesn't match a
+     * seed is **silently ignored** (that seed stays lazy). Source these from a prior
+     * `lazySeeds` result, never reconstruct them.
+     */
+    lazyForceParse?: string[];
     /** Rollup `output.inlineDynamicImports` — absorbs the dynamic import target
      * into the importer's chunk and rewrites the `import("./x")` call into an
      * `__esm` wrapper init/exports call. Combine with `splitting: true`. The
@@ -424,6 +550,9 @@ interface BuildOptionsCommon {
     entryNames?: string;
     chunkNames?: string;
     assetNames?: string;
+    /** CSS chunk path pattern. Default: `[dir]/[name]` (PR B-4b sub-2; esbuild parity).
+     * Supports `[name]`, `[hash]` (content), and `[dir]` (entry-relative). */
+    cssNames?: string;
     /** Metro AssetRegistry module path (React Native-only layer).
      * - `undefined`: determined by the platform preset (with
      *   `platform: "react-native"`, the default path is used automatically)
@@ -470,6 +599,17 @@ interface BuildOptionsCommon {
         find: string | RegExp;
         replacement: string;
     }>;
+    /** alias 의 prefix matching 을 끄는 from 목록 — exact 매칭만 허용.
+     *
+     * `alias` object form 의 기본 동작은 esbuild 처럼 정확/접두사 둘 다 매칭이라
+     * `react: "preact/compat"` 가 `react/hooks → preact/compat/hooks` 로도 동작한다.
+     * 그러나 alias 값이 **단일 파일** 인 경우 prefix 매칭이 `from/subpath → file.js/subpath`
+     * (파일을 디렉토리 취급) 로 깨진다. 이 list 에 from 을 적으면 그 entry 는 exact
+     * 매칭만 적용 — subpath import 는 alias 미적용되어 원본 패키지로 resolve.
+     *
+     * 일반적인 package-to-package alias (`react → preact/compat`) 는 list 에 안 넣음.
+     * 주로 wrapper / shim 파일 alias 에서 사용. */
+    aliasExact?: string[];
     /** Fallback resolution — applied **only when** normal resolution fails
      * (webpack `resolve.fallback` / Metro `resolver.extraNodeModules`-compatible).
      * If the value is a string, re-resolve to that specifier; if `false`,
@@ -665,6 +805,15 @@ interface BuildOptionsCommon {
     reactRefresh?: boolean;
     /** Collect dev mode per-module codes (for HMR rebuilds). */
     collectModuleCodes?: boolean;
+    /**
+     * `watch()` 가 *initial* 빌드 결과를 outdir 에 쓰지 않는다 (#3779 follow-up).
+     * caller 가 이미 별도 `build()` / `buildSync()` 로 outdir 를 채워 둔 상태에서
+     * watch handle 만 띄울 때 사용 — `runServe` 가 `runBundle` 1회 후 `watch()` 를
+     * 띄우는 패턴. caller 가 outdir 를 미리 준비하지 않으면 dev server 가 404 — 위험은
+     * caller 책임. incremental rebuild 의 출력 동작은 watch handle 이 자동으로 별도
+     * 제어. 기본 false (RN dev 등 기존 단독 watch 사용자 호환).
+     */
+    skipInitialOutput?: boolean;
     /** Add configurable: true to Object.defineProperty (RN/Hermes-compatible). */
     configurableExports?: boolean;
     /** Guarantee ESM execution order — downgrade function declarations to
@@ -711,6 +860,12 @@ interface BuildOptionsCommon {
      * Avoids the Fabric early-register race (`View config not found for
      * component 'X'`). */
     codegenTransform?: boolean;
+    /**
+     * PR-3: HMR 위상 보존에서 plugin 게이트를 완화하는 **빌드 수준** opt-in 신호(per-plugin 아님).
+     * 이 빌드의 모든 plugin 이 결정적·모듈별 순수(ModuleGraph 무접근, 전역 상태/lifecycle 출력 영향
+     * 없음)임을 호출자가 보장할 때만 true. RN preset 이 내장 plugin 구성에 대해 자동으로 켠다.
+     * 임의 custom plugin 은 비결정 가능하므로 default false. */
+    preserveSafePlugins?: boolean;
     /** Global identifiers to reserve during scope hoisting. */
     globalIdentifiers?: string[];
     /** Paths of polyfills to run immediately at bundle start. */
@@ -744,6 +899,14 @@ interface BuildOptionsCommon {
     onReady?: (event: WatchReadyEvent) => void | Promise<void>;
     /** watch-mode rebuild callback. */
     onRebuild?: (event: WatchRebuildEvent) => void | Promise<void>;
+    /**
+     * watch debounce window in milliseconds — after the first file event, the
+     * watcher waits this long for idle before rebuilding, merging rapid saves
+     * into one rebuild. Default `16`. Set `0` to rebuild immediately (no debounce;
+     * lower latency, but rapid saves may trigger multiple rebuilds). Mirrors the
+     * CLI `--watch-delay` flag. Only affects the NAPI `watch()` path.
+     */
+    watchDelay?: number;
     /**
      * Whether to write the `.map` file to disk (Issue #1727 Phase B).
      *
@@ -797,10 +960,40 @@ export type BuildOptions = (BuildOptionsCommon & {
 export interface WatchReadyEvent {
     files: number;
     bytes: number;
+    /**
+     * #3796 — initial 빌드의 output 파일 path 목록. caller (예: `runServe`) 가 outdir scan 없이
+     * 정확한 outputFiles 정보를 받아 후속 hook (예: `injectBundleCssLinks`) 호출 가능. contents
+     * 는 메모리 비용이 커 path 만 노출 — caller 가 fs read 또는 path 기반 분기.
+     */
+    outputs?: string[];
+    /**
+     * D105 PR-B-1 — lazy 빌드(`lazyCompilation: true`)일 때만. 미파싱 lazy seed 들의
+     * `{ pathHash, path }` (build 결과 {@link NativeBuildResult.lazySeeds} 와 동일 shape).
+     * dev 서버가 watch(lazy)로 HMR 을 유지하며 on-demand lazy 라우팅을 구현하기 위한 **토대 데이터**
+     * — 요청 청크 URL `<stem>-<pathHash>.js` 의 해시로 seed 경로를 역참조해 on-demand 컴파일
+     * (`build({ lazyForceParse: [path] })`)할 수 있다.
+     *
+     * **범위**: *initial* 빌드(onReady)에서만 노출. rebuild(HMR)에서 동적 import 추가/삭제로
+     * seed 집합이 바뀌는 경우의 갱신 전략(델타 vs full-reload)은 PR-B-2(dev 서버 연동)에서 정한다.
+     */
+    lazySeeds?: Array<{
+        pathHash: string;
+        path: string;
+    }>;
 }
 export interface WatchRebuildEvent {
     success: boolean;
+    /** Single error tag from native `@errorName(err)` (catch path). */
     error?: string;
+    /**
+     * #3799 — Multiple error diagnostics from bundler (success-but-errors path). When the
+     * bundler 자체가 throw 하지 않고 success-결과를 반환했지만 diagnostics 에 error severity
+     * 가 있는 경우 채워진다. `error` (single tag) 와 별개 — `errors` 가 있으면 우선 사용.
+     */
+    errors?: Array<{
+        file: string;
+        message: string;
+    }>;
     changed?: string[];
     graphChanged?: boolean;
     updates?: Array<{
@@ -886,10 +1079,36 @@ export interface WatchRebuildEvent {
         emitConcat: number;
         /** Source map V3 JSON generation (VLQ encode + sources content + debugId). */
         emitSourcemapFinalize: number;
+        /** Link: per-module export map build. */
+        linkBuildExportMap: number;
+        /** Link: import resolution (binding cross-reference). */
+        linkResolveImports: number;
+        /**
+         * Link: canonical_name 계산. lodash 측정에서 ~50ms — RFC #3940 의 RenameTable
+         * 도입 (Phase 2) 후 baseline 으로 활용.
+         */
+        linkComputeRenames: number;
+        /** Link: re-export alias 채우기 (cross-module export name 매핑). */
+        linkPopulateReExportAliases: number;
+        /** Link: import symbol 채우기. */
+        linkPopulateImportSymbols: number;
+        /** Link: namespace access 채우기 (namespace import 사용처). */
+        linkPopulateNamespaceAccesses: number;
     };
     /** Number of modules reparsed in the incremental graph. Counts cache-missed
      * modules only. Not exposed for full builds. */
     reparsedModules?: number;
+    /**
+     * D105 PR-C-1: lazy 빌드의 미파싱 seed 목록 `{ pathHash, path }`
+     * ({@link WatchReadyEvent.lazySeeds} 와 동일 shape/공식). `lazyCompilation` 이 켜진
+     * watch 세션에서 매 rebuild 마다 노출 → dev 서버가 rebuild 중 새로 추가/제거된 동적
+     * import seed 집합을 갱신할 수 있다 (onReady 한정이던 PR-B-1 의 rebuild 확장).
+     * lazy 빌드가 아니거나 동적 import 가 없으면 생략(`undefined`).
+     */
+    lazySeeds?: Array<{
+        pathHash: string;
+        path: string;
+    }>;
 }
 export interface WatchHandle {
     stop(): void;
@@ -914,6 +1133,18 @@ export interface WatchHandle {
      * `null` if `moduleId` was not included in this rebuild.
      */
     getHmrSourceMap(moduleId: string): string | null;
+    /**
+     * #4079 PR-2 — 요청된 lazy seed(동적 import 타겟)를 watch 그래프에서 force-parse 하도록
+     * 누적 등록한다. `path` 는 {@link WatchReadyEvent.lazySeeds} / {@link WatchRebuildEvent.lazySeeds}
+     * 의 *정확한* 절대경로여야 한다(번들러 해석 경로 — `resolve()` 로 재구성 금지).
+     *
+     * 호출 즉시 worker 가 다음 rebuild(파일 변경 없이도, ≤200ms 내)에서 그 seed 를 정식 파싱·
+     * emit 하고 그 transitive 정적 deps 를 감시 대상에 포함시킨다(dev materialize — `--lazy`
+     * 라우트를 방문하면 그 안쪽 파일 편집도 HMR 동작). 중복/`stop()` 후 호출은 no-op.
+     *
+     * `lazyCompilation`+`splitting` watch 세션에서만 의미 있다.
+     */
+    requestLazySeed(path: string): void;
 }
 export interface ZntcPlugin {
     name: string;
@@ -945,6 +1176,8 @@ export interface PluginBuild {
         contents: string | Uint8Array;
         loader?: string;
         map?: unknown;
+        /** Rollup `ModuleInfo.meta` 호환 — getModuleInfo(id).meta 로 노출 (#1880 PR2). */
+        meta?: Record<string, unknown>;
     }>): void;
     onTransform(options: {
         filter: RegExp;
@@ -1092,6 +1325,12 @@ export interface AppBuildOptions {
      * the same option representation.
      */
     compiler?: CompilerOptions;
+    /**
+     * Rollup-compatible JS plugins. Same `resolveId`/`load`/`transform` hooks as
+     * `BuildOptions.plugins` — app build pipeline 도 같은 dispatcher 를 받는다
+     * (#2538 4-4 PR-1).
+     */
+    plugins?: ZntcPlugin[];
 }
 /**
  * Options for preparing a Vite-style application for the development server.
@@ -1257,13 +1496,31 @@ export interface RollupPluginContext {
     warn(message: unknown): void;
     /** Register an additional file to watch in watch mode. Currently a no-op (graph mutation not supported). */
     addWatchFile(id: string): void;
-    /** Module resolve. Currently unsupported — throws an Error when called to notify the plugin author. */
+    /** Module resolve (Rollup `this.resolve` 호환, #1880 PR4). async build() 의 resolveId/load/transform
+     * hook 에서 native resolver(순수 path resolution)로 해석 → `{ id, external }` 또는 null(미해결).
+     * `options`(skipSelf 등)는 현재 no-op (native resolver 가 plugin 을 재진입하지 않아 skipSelf 자명 충족).
+     * 그 외 hook / buildSync / vitePlugin() 어댑터에서는 throw. */
     resolve(source: string, importer?: string | null, options?: unknown): Promise<{
         id: string;
         external?: boolean;
     } | null>;
-    /** Emit an additional asset/chunk. Currently unsupported — throws an Error when called. */
+    /** Emit an additional asset (Rollup `this.emitFile` 호환, #1880 PR5/6). async build() 의
+     * resolveId/load/transform hook 에서 `{ type: 'asset', fileName | name, source }` 를 emit →
+     * reference id 반환, 해당 asset 은 `result.outputFiles` 에 나타난다. `fileName` 은 그대로,
+     * `name` 은 source hash 로 파일명 자동 생성(file/copy loader 와 동일 `assetNames` 패턴).
+     * vitePlugin() 어댑터의 resolveId/load/transform hook 에서도 동작(#1880 PR7).
+     * `{ type: 'chunk', id }` 는 id(이미 graph 에 있는 모듈)를 별도 chunk 로 분리(#1880 PR7-2b-i,
+     * splitting:true). 신규 모듈 chunk emit 은 미지원(build 진단). 그 외 hook / buildSync 는 throw.
+     * **반드시 hook 본문에서 동기적으로 호출**해야 한다 — `await` 이후나 detached promise 에서
+     * 호출하면 EmitStore 수명을 벗어나 asset 이 누락되거나 정의되지 않은 동작이 된다 (follow-up). */
     emitFile(file: unknown): string;
+    /** Resolve an emitted file's final output name (Rollup `this.getFileName` 호환, #1880 PR6).
+     * `this.emitFile` 이 돌려준 reference id → 최종 출력 파일명. asset hash 는 source 기반이라 emit
+     * 시점에 확정되므로 같은(또는 먼저 완료된) hook 에서 즉시 조회 가능. 미등록 id 는 throw. */
+    getFileName(referenceId: string): string;
+    /** 모듈 그래프 정보(+plugin meta) 조회 (Rollup `this.getModuleInfo` 호환).
+     * async build() 의 transform hook 에서만 사용 가능 (#1880 PR3). 그 외 hook/buildSync 에선 throw. */
+    getModuleInfo(id: string): ManualChunksModuleInfo | null;
 }
 type ResolveIdResult = string | null | undefined | void | {
     id: string;