@zntc/core 0.1.0

package/dist/core/index.d.ts

@@ -0,0 +1,1311 @@
+/**
+ * @zntc/core — Native NAPI bindings for the ZNTC TypeScript transpiler.
+ *
+ * A NAPI native module that supports Node.js, Bun, and Deno.
+ * Returns results directly on the JS heap with no global state.
+ *
+ * @example
+ * ```ts
+ * import { transpile } from "@zntc/core";
+ * const result = transpile("const x: number = 1;", { filename: "input.ts" });
+ * console.log(result.code);
+ * ```
+ */
+export type { Target, Platform, TranspileOptions, TranspileResult } from '../shared/index';
+import type { TranspileOptions, TranspileResult } from '../shared/index';
+import { isPlainObject, validateTsConfigRaw } from '../shared/index';
+import { type RuntimePolyfillOptions, type RuntimePolyfillsOption } from './src/runtime-polyfills.ts';
+export { isPlainObject, validateTsConfigRaw };
+export type { RuntimePolyfillOptions, RuntimePolyfillsOption };
+interface OutputFile {
+    path: string;
+    /** Raw byte content. Exposed by NAPI via `napi_create_buffer_copy` — avoids
+     * the string copy + UTF-8 validation cost (safe for binary asset / CSS bundle
+     * / source map alike). Equivalent to esbuild OutputFile.contents. */
+    contents: Uint8Array;
+    /** Lazy UTF-8 decode of `contents`. Decoded once on first access and cached.
+     * Equivalent to esbuild OutputFile.text. */
+    readonly text: string;
+    /** When code splitting, the absolute paths of the modules in this chunk
+     * (compatible with rolldown `chunk.moduleIds`). Empty array for a single
+     * bundle / asset output. */
+    moduleIds?: string[];
+    /** The list of symbol names this chunk exports (for cross-chunk validation). */
+    exports?: string[];
+    /** The final filenames of the other chunks this chunk imports (compatible
+     * with rolldown `chunk.imports`). Paths are resolved down to the
+     * content-hash. */
+    imports?: string[];
+}
+interface Diagnostic {
+    text: string;
+    code?: string;
+    location?: {
+        file: string;
+        line?: number;
+        column?: number;
+    };
+}
+/**
+ * RN AssetRegistry.registerAsset metadata — only exposes the fields actually
+ * read by the `rn-asset-copy` release copy path. width/height/hash are passed
+ * directly to the RN runtime via the in-bundle `registerAsset({...})` call, so
+ * they are not duplicated on this side channel.
+ */
+export interface RnAssetMetadata {
+    httpServerLocation: string;
+    fileSystemLocation: string;
+    name: string;
+    type: string;
+    scales: number[];
+}
+interface NativeTsconfigCacheHandle {
+    clear(): void;
+    size(): number;
+}
+export interface TokenizeToken {
+    kind: string;
+    text: string;
+    start: number;
+    end: number;
+    line: number;
+    column: number;
+    hasNewlineBefore: boolean;
+}
+export interface TokenizeOptions {
+    filename?: string;
+}
+/**
+ * `zntc.config.{ts,js}` 의 타입 체크 / 자동완성을 위한 identity helper.
+ *
+ * 객체 config 와 함수형 config 를 모두 지원한다.
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from "@zntc/core";
+ *
+ * export default defineConfig({
+ *   entryPoints: ["src/index.ts"],
+ *   format: "esm",
+ *   sourcemap: true,
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from "@zntc/core";
+ *
+ * export default defineConfig(({ command, mode, env }) => {
+ *   const production = command === "bundle" && mode === "production";
+ *
+ *   return {
+ *     entryPoints: ["src/index.ts"],
+ *     minify: production,
+ *     define: {
+ *       __APP_ENV__: JSON.stringify(env.ZNTC_APP_ENV ?? mode),
+ *     },
+ *   };
+ * });
+ * ```
+ */
+export declare function defineConfig<T extends UserConfigInput>(config: T): T;
+export { defaultConfigEnv, findConfigPath, findModeConfigPath, importAndResolveDefault, loadConfig, loadModuleDefault, mergeUserConfigs, } from './src/config-loader.ts';
+export type { ConfigEnv, ModuleKind, UserConfig, UserConfigFn, UserConfigInput, } from './src/config-loader.ts';
+export { envToDefine, loadEnv } from './src/load-env.ts';
+export { KNOWN_CONFIG_KEYS, suggestKey, warnUnknownKeys } from './src/typo-suggest.ts';
+export { defineWorkspace, filterWorkspaces, findWorkspacePath, identifyWorkspaceEntries, loadIdentifiedConfig, loadWorkspace, WORKSPACE_EXT_PRIORITY, } from './src/workspace.ts';
+export type { IdentifiedWorkspace, Workspace, WorkspaceEntry, WorkspaceEntryInline, WorkspaceEntryPath, WorkspaceFn, WorkspaceInput, } from './src/workspace.ts';
+import type { UserConfigInput } from './src/config-loader.ts';
+/**
+ * Loads the NAPI addon — called automatically on the first invocation of a
+ * native API such as `transpile()`/`build()`/`watch()`, so calling it
+ * explicitly is optional. Call it directly only when you need an addon path
+ * override (e.g. a custom prebuild). No-op if already loaded.
+ */
+export declare function init(addonPath?: string): void;
+/**
+ * Cache of tsconfig autodiscovery walk results (#2367). A NAPI consumer that
+ * repeatedly transpiles many files in-process (Vite/Rollup plugin, etc.)
+ * creates one instance and reuses it across transpile calls → saves 5–10 fs
+ * syscalls per file.
+ *
+ * Passed via the `cache` option of `transpile()`. When `tsconfigPath` /
+ * `tsconfigRaw` is specified, the cache is bypassed and the explicit value is
+ * used. The instance is cleaned up automatically on GC — explicit dispose is
+ * not required.
+ *
+ * Aligned with rolldown `TsconfigCache` (the design is an N-slot HashMap, not
+ * a single slot).
+ *
+ * @example
+ *   const cache = new TsconfigCache();
+ *   for (const file of files) {
+ *     transpile(source, { filename: file, cache });
+ *   }
+ */
+export declare class TsconfigCache {
+    /** @internal native handle — unwrapped and used by `transpile()`. Do not use externally. */
+    private readonly _handle;
+    constructor();
+    /** Reclaims all cache entries and internal string memory. The instance can be reused. */
+    clear(): void;
+    /** Current number of cached entries (testing / debugging). */
+    get size(): number;
+    /**
+     * Explicit Resource Management (TC39 Stage 4) — `using cache = new TsconfigCache();`
+     * automatically calls `clear()` on scope exit. The memory itself is reclaimed
+     * by the GC finalizer, so this method only "empties the cache" (the instance
+     * can be reused).
+     */
+    [Symbol.dispose](): void;
+    /** Used by transpile() to extract the native handle — do not use externally (private escape hatch). */
+    /** @internal */
+    static _unwrap(c: TsconfigCache): NativeTsconfigCacheHandle;
+}
+export declare function transpile(source: string, options?: TranspileOptions & {
+    cache?: TsconfigCache;
+}): TranspileResult;
+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;
+export type { OutputFile, Diagnostic };
+/** Return value of `meta.getModuleInfo(id)` in Rollup `manualChunks(id, meta)`. */
+export interface ManualChunksModuleInfo {
+    id: string;
+    isEntry: boolean;
+    /** A module not included in the bundle because it matched an `external`
+     * pattern. No AST/source — exposed only as a first-class graph traversal
+     * node. */
+    isExternal: boolean;
+    /** Whether the module may have side effects (compatible with Rollup
+     * `hasModuleSideEffects`). Determined by the `package.json` `sideEffects`
+     * field or the `treeShaking.moduleSideEffects` option. When `false`, the
+     * tree-shaker may remove it if unused. */
+    hasModuleSideEffects: boolean;
+    /** Module source code (compatible with Rollup `code`).
+     * null for external / asset / unparsed modules. Also null if UTF-8 decoding
+     * fails. */
+    code: string | null;
+    /** Whether the module is included in the bundle after tree-shaking
+     * (compatible with Rollup `isIncluded`). When `treeShaking: false`, all
+     * modules may appear false — it is a mirror flag on Module, so it stays at
+     * its default if the tree-shaker does not run. */
+    isIncluded: boolean;
+    /** The list of names this module exports (compatible with Rollup `exports`).
+     * Includes both default and re-export stars. Empty array for external (the
+     * graph has no export info). */
+    exports: string[];
+    /** Synthetic named exports defined by a plugin (compatible with Rollup
+     * `syntheticNamedExports`). Always false until the ZNTC plugin context API
+     * extension (#1880). */
+    syntheticNamedExports: boolean;
+    /** Result of the `implicitlyLoadedAfterOneOf` option of `this.emitFile`
+     * (Rollup-compatible). Always an empty array until the ZNTC plugin context
+     * API (#1880). */
+    implicitlyLoadedAfterOneOf: string[];
+    /** The opposite direction — modules that must be loaded after this module is
+     * implicitly loaded. */
+    implicitlyLoadedBefore: string[];
+    /** Modules that statically import this module. External modules are also
+     * included in the importer list (when itself is external, an in-graph module
+     * is the importer). */
+    importers: string[];
+    /** Modules that dynamically import (`import()`) this module. */
+    dynamicImporters: string[];
+    /** Modules that this module statically imports. Includes external modules. */
+    importedIds: string[];
+    /** Modules that this module dynamically imports (`import()`). Includes
+     * external modules. */
+    dynamicallyImportedIds: string[];
+}
+/** The second argument of the `manualChunks` callback — module graph topology lookup. */
+export interface ManualChunksMeta {
+    /** Look up module info by `id`. null if not found. */
+    getModuleInfo(id: string): ManualChunksModuleInfo | null;
+}
+/**
+ * The `compiler` namespace — per-library 1st-party transform settings
+ * (`@next/swc`-compatible surface).
+ *
+ * The 1st-party counterpart to `babel-plugin-styled-components` /
+ * `@emotion/babel-plugin`. Enabling the option alone, without registering a
+ * plugin, produces the same transform result.
+ */
+export interface CompilerOptions {
+    /**
+     * styled-components 1st-party transform.
+     * Same transform intent as `babel-plugin-styled-components` /
+     * `@swc/plugin-styled-components`.
+     */
+    styledComponents?: boolean | StyledComponentsOptions;
+    /**
+     * emotion 1st-party transform.
+     * Same transform intent as `@emotion/babel-plugin` / `@swc/plugin-emotion`.
+     */
+    emotion?: boolean | EmotionOptions;
+}
+/** styled-components transform options (`babel-plugin-styled-components`-compatible). */
+export interface StyledComponentsOptions {
+    /** Auto-assign a displayName for devtools display (default: NODE_ENV !== "production"). */
+    displayName?: boolean;
+    /** Deterministic componentId hash for stable SSR hydration (default: true). */
+    ssr?: boolean;
+    /** Include the file name in componentId (default: true). */
+    fileName?: boolean;
+    /** Minify CSS whitespace (default: true). */
+    minify?: boolean;
+    /** Recognize template literals downleveled to modern JS (default: true). */
+    transpileTemplateLiterals?: boolean;
+    /** Tell the minifier that styled.X is side-effect-free (default: false). */
+    pure?: boolean;
+    /** Namespace prefix for displayName / componentId — isolates multiple styled instances. */
+    namespace?: string;
+    /**
+     * List that makes the displayName prefix fall back to the parent dir when
+     * the basename is meaningless (default: `["index"]`). Equivalent to the
+     * option of the same name in babel-plugin-styled-components.
+     */
+    meaninglessFileNames?: string[];
+    /**
+     * List of import sources to recognize as vendored forks (e.g. `@my-org/styled`,
+     * `@my-org/*`, `@{my-org,co}/*`). picomatch-compatible glob — `*`, `?`,
+     * `[abc]`/`[a-z]`/`[!abc]`, `{a,b}` (nesting allowed).
+     */
+    topLevelImportPaths?: string[];
+    /**
+     * Extract the `<div css={...}>` JSX prop into a module-level styled component
+     * (default: false). Opt-in, unlike babel-plugin-styled-components which
+     * defaults to true. Supports intrinsic / custom (including
+     * jsx_member_expression) / `css\`\`` template / object form / `${expr}`
+     * dynamic prop forwarding. On auto-inject, a `styled` binding collision is
+     * automatically mangled to `_styled` / `_styled2`.
+     */
+    cssProp?: boolean;
+    /** Emit the [meta] marker (default: false). */
+    meta?: boolean;
+}
+/** emotion transform options (`@emotion/babel-plugin`-compatible). */
+export interface EmotionOptions {
+    /** Generate a sourceMap (default: true). */
+    sourceMap?: boolean;
+    /** Auto-assign the variable name as the CSS class label (default: "dev-only"). `false` disables autoLabel. */
+    autoLabel?: 'always' | 'dev-only' | 'never' | boolean;
+    /** label format string. tokens: `[local]`, `[filename]`, `[dirname]` (default: "[local]") */
+    labelFormat?: string;
+    /** Import path alias — for using a fork or vendored emotion. */
+    importMap?: Record<string, Record<string, {
+        canonicalImport: [string, string];
+    }>>;
+}
+/** Vite-style dev server options used by `zntc dev` / `zntc --serve`. */
+export interface DevServerOptions {
+    /** Port to listen on. CLI `--port` overrides this value. */
+    port?: number;
+    /** Host to listen on. `true` means `0.0.0.0`, matching Vite. CLI `--host` overrides this value. */
+    host?: string | boolean;
+    /** Exit if the configured port is already in use instead of trying the next port. */
+    strictPort?: boolean;
+    /** Open the served URL in the browser after startup. CLI `--open` overrides this value. */
+    open?: boolean;
+}
+type BuildTarget = import('../shared/index').Target | (string & {});
+/**
+ * Common build options shared by all platforms.
+ * The `platform` + `target` combination is constrained as a discriminated
+ * union in `BuildOptions`.
+ */
+/** Module Federation `shared` dependency options (a subset of MF2 `SharedConfig`, #3318). */
+export interface MfSharedConfig {
+    singleton?: boolean;
+    requiredVersion?: string;
+    strictVersion?: boolean;
+    eager?: boolean;
+}
+/** Module Federation config block (#3318 P1-0). A record shape isomorphic to
+ * the webpack/rspack `ModuleFederationPlugin` — targeting the
+ * `@module-federation/runtime` contract. **P1-0 is zntc.config parsing &
+ * validation only** (emit not wired up; consumed in P1-1+; build()/NAPI mf
+ * extraction is also P1-1+). The `shared` array/boolean shorthand is P1-1+ —
+ * P1-0 only supports record-of-object. */
+export interface ModuleFederationConfig {
+    /** remote identifier. Required when using `exposes`/`remotes`. */
+    name?: string;
+    /** Exposed modules: `{ "./Widget": "./src/Widget.tsx" }`. */
+    exposes?: Record<string, string>;
+    /** Consumed remotes: `{ remoteA: "remoteA@https://…/mf-manifest.json" }`. */
+    remotes?: Record<string, string>;
+    /** Shared dependencies: `{ react: { singleton: true, requiredVersion: "^18" } }`.
+     * (P1-0: record-of-object only. boolean/array shorthand is P1-1+.) */
+    shared?: Record<string, MfSharedConfig>;
+    /** share scope name (default `"default"`). */
+    shareScope?: string;
+}
+interface BuildOptionsCommon {
+    entryPoints: string[];
+    format?: 'esm' | 'cjs' | 'iife' | 'umd' | 'amd';
+    external?: string[];
+    minify?: boolean;
+    minifyWhitespace?: boolean;
+    minifyIdentifiers?: boolean;
+    minifySyntax?: boolean;
+    splitting?: boolean;
+    /** 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
+     * resulting bundle is runnable as a single file.
+     *
+     * Preservation guarantees:
+     * - namespace identity: `(await import("./x")) === (await import("./x"))`
+     * - top-level side effects run once (cached)
+     * - live bindings (if the module mutates an `export let`, the change is
+     *   reflected on the caller side too)
+     */
+    inlineDynamicImports?: boolean;
+    /** Like Rollup `output.experimentalMinChunkSize` — automatically merges a
+     * small common chunk whose (estimated) total module source is under this
+     * many bytes into a chunk whose reachability is a superset (no over-fetch).
+     * entry/manual/dynamic chunks are preserved. 0/unspecified = disabled. */
+    minChunkSize?: number;
+    /** Module Federation config (#3318 P1-0). Parsing & validation only — emit
+     * is a follow-up (P1-1+). Being a nested object, it is config/`build()`-only
+     * (no CLI flag — the whole ecosystem is config-driven). MF2 contract
+     * (`name`/`exposes`/`remotes`/`shared`/`shareScope`). */
+    mf?: ModuleFederationConfig;
+    sourcemap?: boolean;
+    /**
+     * Source map output format (only meaningful when `sourcemap: true`).
+     * esbuild / rolldown-compatible (#2152).
+     *  - `"linked"` (default): emit a `.map` file +
+     *    `//# sourceMappingURL=<file>.map` comment.
+     *  - `"external"`: emit a `.map` file, no URL comment (Sentry/CI standard —
+     *    location not disclosed).
+     *  - `"inline"`: no `.map` file, embed the JSON as a base64 data URL in a
+     *    comment.
+     *
+     * In watch / dev server environments, `linked` is forced (guarantees
+     * HMR + DevTools integration).
+     */
+    sourcemapMode?: 'linked' | 'external' | 'inline';
+    sourcemapDebugIds?: boolean;
+    sourcesContent?: boolean;
+    treeShaking?: boolean;
+    metafile?: boolean;
+    keepNames?: boolean;
+    shimMissingExports?: boolean;
+    flow?: boolean;
+    jsxInJs?: boolean;
+    charsetUtf8?: boolean;
+    useDefineForClassFields?: boolean;
+    experimentalDecorators?: boolean;
+    emitDecoratorMetadata?: boolean;
+    /** `import { x } from 'mod'` cherry-pick decomposition mapping. The ZNTC
+     * equivalent of babel-plugin-lodash and the like (#2393).
+     * key = source module name (exact match), value = template (the `{name}`
+     * placeholder is replaced with the specifier name).
+     *
+     * e.g. with `{ lodash: 'lodash/{name}' }`, `import { map } from 'lodash'`
+     *      becomes `import map from 'lodash/map'`.
+     *
+     * Transform conditions (all must hold): named specifiers only, no alias, not
+     * type-only. If not met, the original import is kept — a safety net for when
+     * the library does not support path imports.
+     */
+    moduleSpecifierMap?: Record<string, string>;
+    banner?: string;
+    footer?: string;
+    /** Rollup `output.intro`: text to insert before the code inside the format wrapper. */
+    intro?: string;
+    /** Rollup `output.outro`: text to insert after the code inside the format wrapper. */
+    outro?: string;
+    globalName?: string;
+    /** Rollup `output.globals`: IIFE/UMD external specifier → global variable mapping */
+    globals?: Record<string, string>;
+    publicPath?: string;
+    entryNames?: string;
+    chunkNames?: string;
+    assetNames?: 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)
+     * - `string`: wrap with the registerAsset at that path as
+     *   `module.exports = require(path).registerAsset({...})`
+     * - `false`: disabled (export the same URL string as web)
+     * Default path: `"react-native/Libraries/Image/AssetRegistry"` */
+    assetRegistry?: string | false;
+    /** JSX runtime mode. `'preserve'` emits JSX unchanged — only TS annotations
+     * are stripped. Use this to delegate JSX handling to a downstream tool (e.g.
+     * `@vitejs/plugin-react` / `@preact/preset-vite` / `vite-plugin-solid`).
+     * Equivalent to tsc `"jsx": "preserve"`.
+     * Known limitation — TS annotations inside an expression container within JSX
+     * (e.g. `<Foo prop={value as Type}>`) are left raw, not stripped. */
+    jsx?: 'classic' | 'automatic' | 'automatic-dev' | 'preserve';
+    jsxFactory?: string;
+    jsxFragment?: string;
+    jsxImportSource?: string;
+    /** Compile-time constant substitution (esbuild `define`-compatible).
+     * Keys are identifiers or member expressions like `obj.prop`; values are JS
+     * expression strings.
+     * e.g. `{ "__DEV__": "false", "process.env.NODE_ENV": '"production"' }` */
+    define?: Record<string, string>;
+    /** Dev server defaults for `zntc dev` / `zntc --serve`. CLI flags still take precedence. */
+    server?: DevServerOptions;
+    /** Import path aliases — two forms supported (esbuild / Vite-compatible):
+     *
+     * 1. **Object form** (esbuild `alias`): exact + prefix matching. Only the
+     *    given specifier is substituted.
+     *    e.g. `{ react: "preact/compat" }` — `react` or `react/hooks` →
+     *    `preact/compat[/hooks]`
+     *
+     * 2. **Array form** (Vite `resolve.alias`, #2153): supports `RegExp` find.
+     *    The first match in order is applied. When `find` is a string it is
+     *    prefix-matched; when a RegExp, the host runtime matches and substitutes
+     *    via `replacement`.
+     *    e.g. `[{ find: /^@\/(.*)$/, replacement: "./src/$1" }]`
+     *
+     * Substituted **unconditionally before** normal resolution — even an
+     * actually-installed package is ignored. For an optional shim, use
+     * `fallback` instead (applied only on failure). The array form is also
+     * supported in buildSync(), which uses only sync hooks. */
+    alias?: Record<string, string> | Array<{
+        find: string | RegExp;
+        replacement: 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`,
+     * substitute an empty module.
+     * e.g. `{ crypto: "crypto-browserify", fs: false }` */
+    fallback?: Record<string, string | false>;
+    /** Resolution-blocking patterns (Metro `resolver.blockList` / webpack
+     * `IgnorePlugin`-compatible). Absolute paths that match are failed by the
+     * resolver and not included in the bundle graph.
+     * - `RegExp`: `.source` is extracted and used as the pattern
+     * - `string`: used as the regex string as-is
+     *
+     * Supported syntax: literals, `.*`, `^`, `$`, `\x` escapes. `|`, `[]`, `()`,
+     * `+?`, `\w\d` are not supported.
+     *
+     * With `platform: "react-native"`, Metro's default patterns (`__tests__`,
+     * iOS/Android build folders, etc.) are auto-prepended. User patterns are
+     * appended after them. */
+    blockList?: (RegExp | string)[];
+    inject?: string[];
+    jobs?: number;
+    plugins?: ZntcPlugin[];
+    /** User-defined chunk splitting — Rollup/rolldown `manualChunks`-compatible
+     * (#1027). Receives a module id (absolute path); returning a chunk name
+     * groups that module into the chunk of that name. Returning null/undefined
+     * uses the existing automatic distribution. Transitive dependencies follow
+     * into the same chunk (avoids cross-chunk cycles). Dynamic import targets
+     * prefer the manual chunk over an async chunk.
+     *
+     * The second argument `meta.getModuleInfo(id)` is a graph topology lookup —
+     * Rollup-compatible.
+     *
+     * e.g.:
+     * ```ts
+     * manualChunks: (id, meta) => {
+     *   const info = meta.getModuleInfo(id);
+     *   if (info && info.importers.length >= 2) return 'shared';
+     *   if (/node_modules\/react/.test(id)) return 'react';
+     *   return null;
+     * }
+     * ```
+     */
+    manualChunks?: (id: string, meta: ManualChunksMeta) => string | null | undefined;
+    /** Per-extension loader override (e.g. { ".png": "file", ".svg": "text" }). */
+    loader?: Record<string, string>;
+    /** Custom package.json exports conditions. */
+    conditions?: string[];
+    /** Extension resolution order (e.g. [".ts", ".tsx", ".js"]). */
+    resolveExtensions?: string[];
+    /** package.json field order (e.g. ["module", "main"]). */
+    mainFields?: string[];
+    /** Output directory (used when write: true). */
+    outdir?: string;
+    /** Output file path (for a single entry, used when write: true). */
+    outfile?: string;
+    /**
+     * Multi-format emit (rolldown-style). 배열 길이 >= 2 시 같은 entry 로 각 format 별
+     * build() 호출 후 BuildResult.outputsByFormat 에 결과 묶음. 사용자가 한 호출로
+     * ESM+CJS 동시 출력. graph 재사용은 현재 미지원 (각 format 마다 graph 재빌드).
+     */
+    output?: OutputOptions[];
+    /** Whether to write to disk (default: false, automatically true when outdir/outfile is set). */
+    write?: boolean;
+    /** Allow output files to overwrite input files. */
+    allowOverwrite?: boolean;
+    /** Common base path for entry points (determines the output directory structure). */
+    outbase?: string;
+    /** Treat all bare imports as external. */
+    packagesExternal?: boolean;
+    /** Resolve to the link path instead of following symlinks (esbuild/Node-compatible). */
+    preserveSymlinks?: boolean;
+    /**
+     * When normal `node_modules` resolution fails, search once more in the
+     * realpath directory of `source_dir`. Used as a fallback when an RN/pnpm
+     * peer dependency exists only in a sibling `node_modules` beyond a symlink.
+     * Orthogonal to `preserveSymlinks` — they are commonly enabled together.
+     */
+    resolveSymlinkSiblings?: boolean;
+    /**
+     * Metro `resolver.disableHierarchicalLookup`-compatible. When true, blocks
+     * `node_modules` walk-up resolution outside the entry directory — used in a
+     * monorepo to force dependency hoisting or to prevent leakage of modules
+     * outside the workspace.
+     */
+    disableHierarchicalLookup?: boolean;
+    /** Ignore @__PURE__ and sideEffects annotations. */
+    ignoreAnnotations?: boolean;
+    /** Do not tree-shake unused JSX. */
+    jsxSideEffects?: boolean;
+    /** Bundle analysis output (forces metafile on). */
+    analyze?: boolean;
+    /** List of label names of labeled statements to remove. */
+    dropLabels?: string[];
+    /** Remove `console.*` call expression statements in the transformer (#2155). Applied identically for bundle/transpile. */
+    dropConsole?: boolean;
+    /** Remove `debugger;` statements in the transformer (#2155). Applied identically for bundle/transpile. */
+    dropDebugger?: boolean;
+    /** List of global function names to mark as pure. */
+    pure?: string[];
+    /**
+     * Diagnostic output level (esbuild-compatible, #2158). NAPI filters the
+     * build result's errors/warnings arrays by this level — the items included
+     * in `result.errors` / `result.warnings` themselves are reduced.
+     *
+     *  - `"silent"`: both errors / warnings are empty arrays — even a failure is
+     *    observed via the result object (no throw)
+     *  - `"error"`: only warnings is an empty array, errors as-is
+     *  - `"warning"` (default): both errors + warnings as-is
+     *  - `"info"` / `"debug"` / `"verbose"`: same as warning (info-level
+     *    diagnostics are not emitted currently)
+     */
+    logLevel?: 'silent' | 'error' | 'warning' | 'info' | 'debug' | 'verbose';
+    /**
+     * Diagnostic count limit (esbuild `logLimit`, #2158). 0 means unlimited
+     * (default). The same limit applies to each of the errors / warnings arrays
+     * — excess items are auto-truncated.
+     */
+    logLimit?: number;
+    /**
+     * CJS / UMD entry export format (Rollup `output.exports`-compatible, #2159).
+     * Ignored for ESM output.
+     *
+     *  - `"auto"` (default): default-only → `module.exports = X`. named-only → `exports.X = X`
+     *    (no `__esModule` flag). mixed → `exports.X = X` + `__esModule` flag.
+     *  - `"named"`: always named (`exports.X = X`). If a default exists, the
+     *    `__esModule` flag is added automatically (rolldown `IfDefaultProp`
+     *    behavior — no flag when there is no default).
+     *  - `"default"`: single `module.exports = X` — only when default-only. If
+     *    named is mixed in, warning + empty output.
+     *  - `"none"`: no export output.
+     */
+    outputExports?: 'auto' | 'named' | 'default' | 'none';
+    /**
+     * Inline tsconfig JSON string (same meaning as esbuild's `tsconfigRaw`).
+     * When set, both `tsconfigPath` and autodiscovery are ignored — raw is the
+     * single source of truth. compilerOptions such as jsx/target/decorators are
+     * applied by the Zig-side `tsconfig_merge`.
+     *
+     * @example
+     *   tsconfigRaw: JSON.stringify({ compilerOptions: { jsx: "react-jsx", jsxImportSource: "preact" } })
+     */
+    tsconfigRaw?: string;
+    /**
+     * Path to tsconfig.json (file or directory). When set, compilerOptions are
+     * auto-loaded and merged. Fields set explicitly via JS options take
+     * precedence — only unspecified fields are filled from the tsconfig values.
+     * e.g. "./tsconfig.json" or "./project-dir".
+     */
+    tsconfigPath?: string;
+    /** Additional NODE_PATH resolution paths. */
+    nodePaths?: string[];
+    /** Line length limit (0=unlimited). */
+    lineLimit?: number;
+    /** Output file extension override (e.g. ".mjs"). */
+    outExtension?: string;
+    /** Source map sourceRoot field. */
+    sourceRoot?: string;
+    /** License comment handling ("none" | "inline" | "eof" | "linked"). */
+    legalComments?: 'none' | 'inline' | 'eof' | 'linked';
+    /** Emit a separate file per module (library build). */
+    preserveModules?: boolean;
+    /** Base path for the preserve-modules output directory structure. */
+    preserveModulesRoot?: string;
+    /**
+     * List of profile categories to enable (union with the ZNTC_PROFILE env).
+     * e.g. `["all"]`, `["parse", "transform"]`, `["transform.jsx"]`.
+     * Specifying a parent auto-enables children too (e.g. "transform" →
+     * "transform.jsx"/"transform.ts_strip"/...).
+     * Available categories: see docs/design/profile-infrastructure.md.
+     */
+    profile?: string[];
+    /**
+     * Profile detail level.
+     * - "summary": phase totals only (default)
+     * - "detailed": includes sub-phases
+     * - "per-module": per-module breakdown
+     * - "per-pass": transformer visit level
+     */
+    profileLevel?: 'summary' | 'detailed' | 'per-module' | 'per-pass';
+    /**
+     * Profile report output format.
+     * - "table": human-readable (default)
+     * - "tree": parent/child tree
+     * - "json": machine-readable
+     * - "csv": spreadsheet
+     */
+    profileFormat?: 'table' | 'tree' | 'json' | 'csv';
+    /** dev mode: wrap modules in a __zntc_register() factory + inject the HMR runtime. */
+    devMode?: boolean;
+    /** dev mode module ID base path. */
+    rootDir?: string;
+    /** Enable React Fast Refresh. */
+    reactRefresh?: boolean;
+    /** Collect dev mode per-module codes (for HMR rebuilds). */
+    collectModuleCodes?: boolean;
+    /** Add configurable: true to Object.defineProperty (RN/Hermes-compatible). */
+    configurableExports?: boolean;
+    /** Guarantee ESM execution order — downgrade function declarations to
+     * assignments inside the factory to prevent hoisting. Same as Rolldown's
+     * strictExecutionOrder. Auto-enabled on the React Native platform. */
+    strictExecutionOrder?: boolean;
+    /** Wrap entry trigger (`init_X()` / `require_X()`) calls in try/catch +
+     * ErrorUtils.reportFatalError. Equivalent mechanism to Metro
+     * `guardedLoadModule` (top-level `__r` wrapper) — a module factory throw is
+     * shown as fatal in the standard RN LogBox instead of blocking boot. In
+     * environments without ErrorUtils (test / browser), the throw is re-thrown
+     * as-is. It was discovered when iOS 26.4 Hermes pre-registers spec globals
+     * such as `Location` with an immutable descriptor (`configurable: false`)
+     * and expo-metro-runtime's unguarded `defineProperty` attempt threw, but the
+     * mechanism is OS/engine-agnostic — it covers every module factory throw
+     * case. Auto-enabled on the React Native platform. */
+    entryErrorGuard?: boolean;
+    /** Inject a `console.error` setter intercept into the prologue — console.error
+     * calls matching any one of the RegExp source string array are silently
+     * swallowed. Orthogonal to `entryErrorGuard`. The consumer detects the
+     * environment (e.g. expo) and injects the patterns. When empty or
+     * unspecified, the wrap itself is not emitted → a vanilla RN CLI build has
+     * zero dead code. Not auto-enabled even by the RN preset (the trigger is
+     * environment-specific).
+     *
+     * e.g.: `["^Failed to set polyfill\\.\\s+\\w+\\s+is not configurable\\.?$"]`
+     * (the native immutable global collision message of expo `installGlobal.ts`
+     * + RN `polyfillObjectProperty`) */
+    silentConsoleErrorPatterns?: string[];
+    /** Enable scope hoisting (default true). Removes module boundaries within a single chunk and flattens symbols. */
+    scopeHoist?: boolean;
+    /** Reanimated worklet transform — injects __workletHash/__closure/__initData
+     * into functions with the "worklet" directive. Auto-enabled on the React
+     * Native platform. */
+    workletTransform?: boolean;
+    /** The worklet's `__pluginVersion` value (for cross-checking Reanimated dev
+     * mode jsVersion). Must be passed the react-native-worklets package version
+     * from the user's environment to avoid a runtime error. */
+    workletPluginVersion?: string;
+    /** RN view config codegen — replaces the `codegenNativeComponent` call in
+     * `*NativeComponent.{js,ts}` with an inline view config (#2348). Auto-enabled
+     * on the React Native platform. Same as the
+     * `GenerateViewConfigJs.generate()` fileTemplate of `@react-native/codegen`.
+     * Avoids the Fabric early-register race (`View config not found for
+     * component 'X'`). */
+    codegenTransform?: boolean;
+    /** Global identifiers to reserve during scope hoisting. */
+    globalIdentifiers?: string[];
+    /** Paths of polyfills to run immediately at bundle start. */
+    polyfills?: string[];
+    /**
+     * Auto-inject core-js-based runtime API polyfills.
+     *
+     * - `"off"` (default): no automatic runtime polyfills.
+     * - `"auto"` / `"usage"`: after resolve/load/transform, detect the APIs
+     *   actually used in the bundle graph and inject the modules unsupported by
+     *   the target.
+     * - `"entry"`: comprehensively inject the core-js ES/Web modules required by
+     *   the target into the entry prelude.
+     * - Target specification uses a Browserslist query array, like Rspack/SWC
+     *   `env.targets`.
+     */
+    runtimePolyfills?: RuntimePolyfillsOption;
+    /** core-js version used for the core-js-compat computation (e.g. `"3.49"`). Same role as `runtimePolyfills.coreJs`. */
+    coreJs?: string;
+    /** Paths of modules to run immediately before the entry module. */
+    runBeforeMain?: string[];
+    /** Add directories outside the bundle graph to the watch roots (Metro
+     * watchFolders-compatible). Both absolute and relative paths are allowed.
+     * The given paths are recursively scanned and included in the watch set. */
+    watchFolders?: string[];
+    /** File glob whitelist to include when scanning watchFolders (paths relative to the root). */
+    watchInclude?: string[];
+    /** File globs to exclude when scanning watchFolders (paths relative to the root). */
+    watchExclude?: string[];
+    /** watch-mode build-complete callback. */
+    onReady?: (event: WatchReadyEvent) => void | Promise<void>;
+    /** watch-mode rebuild callback. */
+    onRebuild?: (event: WatchRebuildEvent) => void | Promise<void>;
+    /**
+     * Whether to write the `.map` file to disk (Issue #1727 Phase B).
+     *
+     * - Default `true` — save `bundle.js.map` to the `output_filename + ".map"`
+     *   path.
+     * - `false` — skip disk I/O. Recommended when a dev server such as bungae
+     *   serves it from a lazy endpoint by calling
+     *   {@link WatchHandle.getBundleSourceMap} /
+     *   {@link WatchHandle.getHmrSourceMap}.
+     */
+    emitDiskSourcemap?: boolean;
+    /**
+     * Per-library 1st-party transform settings (`@next/swc` `compiler`-compatible
+     * surface).
+     *
+     * Currently a type stub — no runtime effect since the Zig transformer does
+     * not recognize it yet. Activated in a follow-up epic when the
+     * styled-components / emotion 1st-party transforms are introduced.
+     *
+     * @example
+     * ```ts
+     * defineConfig({
+     *   compiler: {
+     *     styledComponents: true,
+     *     emotion: { autoLabel: "dev-only" },
+     *   },
+     * });
+     * ```
+     */
+    compiler?: CompilerOptions;
+}
+/**
+ * BuildOptions: the user-facing public API.
+ *
+ * When `platform === "react-native"`, the Hermes compatibility matrix is
+ * forced, so `target` / `browserslist` cannot be passed (they are ignored at
+ * runtime too).
+ */
+export type BuildOptions = (BuildOptionsCommon & {
+    /** React Native (Hermes) preset. target is forced to the Hermes matrix. */
+    platform: Extract<import('../shared/index').Platform, 'react-native'>;
+    target?: BuildTarget;
+    browserslist?: never;
+}) | (BuildOptionsCommon & {
+    platform?: Exclude<import('../shared/index').Platform, 'react-native'>;
+    /** ES downlevel target. Rspack-style node/hermes target strings are accepted by the JS wrapper. */
+    target?: BuildTarget;
+    /** browserslist query (string or string[]). Takes precedence over target when set. */
+    browserslist?: string | string[];
+});
+export interface WatchReadyEvent {
+    files: number;
+    bytes: number;
+}
+export interface WatchRebuildEvent {
+    success: boolean;
+    error?: string;
+    changed?: string[];
+    graphChanged?: boolean;
+    updates?: Array<{
+        id: string;
+        code: string;
+        /**
+         * Per-module standalone source map (V3 JSON). Populated when the sourcemap
+         * option is enabled. When the HMR client attaches it to the eval'd code as
+         * a sourceMappingURL data URL, debugger mapping is preserved without
+         * regenerating the whole bundle sourcemap (Issue #1248).
+         */
+        map?: string;
+    }>;
+    bytes?: number;
+    /**
+     * Per-phase build time (milliseconds). Exposed only on a successful rebuild.
+     *
+     * **Base phases** (always measured):
+     * - `detect` / `graph` / `link` / `shake` / `emit` / `delta` / `total`
+     * Field names exactly match their actual values. The pre-2026-04-22 `parse` /
+     * `semantic` were in fact legacy names that held `graph` / `link+shake`
+     * respectively and have been removed — they are now exposed only as
+     * sub-phases (the real parser / SemanticAnalyzer times).
+     *
+     * **Sub-phases** (when `ZNTC_PROFILE=<cat>` / `BUNGAE_HMR_PROFILE=1` /
+     * `profile: ["<cat>"]` is active):
+     * - `scan` / `parse` / `resolve` / `semantic` / `transform` / `codegen` / `metadata`
+     * - All 0 when inactive. `parse` is now the real parser time, `semantic` the
+     *   real SemanticAnalyzer.
+     */
+    phaseDurations?: {
+        /** Change detection (mtime scan). */
+        detect: number;
+        /** Module graph build — resolve + parse + semantic + finalize */
+        graph: number;
+        /** Scope hoisting + linker */
+        link: number;
+        /** Tree shaking */
+        shake: number;
+        /** Code generation (transform + codegen + emit). */
+        emit: number;
+        /** HMR delta extraction. */
+        delta: number;
+        /** Total rebuild time (sum of detect → delta). */
+        total: number;
+        /** Scanner tokenization */
+        scan: number;
+        /** Parser — real parser time only. */
+        parse: number;
+        /** Dependency resolution */
+        resolve: number;
+        /** SemanticAnalyzer — real semantic analysis time only. */
+        semantic: number;
+        /** Transformer total. */
+        transform: number;
+        /** Codegen total. */
+        codegen: number;
+        /** Linker metadata build */
+        metadata: number;
+        /** `graph.build()` / `graph.buildIncremental()` — the module graph construction body. */
+        graphBuild: number;
+        /** Separate build of the `new Worker(new URL(...))` pattern entry. */
+        graphWorker: number;
+        /** Phase 1: event queue BFS scan (module discovery + parsing + resolve). */
+        graphDiscover: number;
+        /** Phase 2-4: DFS exec_index + ExportsKind promotion + TLA propagation. */
+        graphFinalize: number;
+        /** Loading `--polyfill` file contents + Flow transpilation. */
+        emitPolyfill: number;
+        /** Assembling the React Refresh runtime preamble/epilogue (dev + browser). */
+        emitRefresh: number;
+        /** `emitter.emitWithTreeShaking` / `emitChunks` — the bundle output generation body. */
+        emitOutput: number;
+        /** `--metafile` / `--analyze` JSON generation. */
+        emitMetafile: number;
+        /** Per-CSS-entry bundling + lightningcss post-processing. */
+        emitCss: number;
+        /** Format prologue + polyfill IIFE + runtime helper injection. */
+        emitPrelude: number;
+        /** Phase 1/1.5/2/2.5 — used_names + cache lookup + emitModule + cache put */
+        emitModulePass: number;
+        /** Phase 3: module concat + runtime helpers summation + renderChunk + epilogue. */
+        emitConcat: number;
+        /** Source map V3 JSON generation (VLQ encode + sources content + debugId). */
+        emitSourcemapFinalize: number;
+    };
+    /** Number of modules reparsed in the incremental graph. Counts cache-missed
+     * modules only. Not exposed for full builds. */
+    reparsedModules?: number;
+}
+export interface WatchHandle {
+    stop(): void;
+    /**
+     * Lazily generates and returns the full-bundle sourcemap JSON of the latest
+     * rebuild (Issue #1727 Phase B).
+     *
+     * The emit step skips VLQ encoding + sourcesContent attachment, deferring
+     * that cost out of HMR latency until request time. Called when the dev
+     * server receives a `/bundle.js.map` request.
+     *
+     * - `null` when sourcemap is disabled / before the initial build / after
+     *   `stop()`.
+     * - Metro `_processSourceMapRequest` pattern.
+     */
+    getBundleSourceMap(): string | null;
+    /**
+     * Lazily generates and returns the per-module sourcemap JSON of the latest
+     * rebuild.
+     *
+     * Called when the dev server receives a `/hmr-map/:moduleId` request.
+     * `null` if `moduleId` was not included in this rebuild.
+     */
+    getHmrSourceMap(moduleId: string): string | null;
+}
+export interface ZntcPlugin {
+    name: string;
+    setup(build: PluginBuild): void;
+}
+/** Plugin hook return value: both sync and async allowed. null/undefined for pass-through. */
+type HookResult<T> = T | null | undefined | Promise<T | null | undefined>;
+export interface PluginBuild {
+    onResolve(options: {
+        filter: RegExp;
+    }, callback: (args: {
+        path: string;
+        importer: string | null;
+    }) => HookResult<{
+        path?: string;
+        /** Keep the import statement as-is — resolved at runtime (esbuild-compatible). */
+        external?: boolean;
+        /** Substitute the module with an empty object (`module.exports = {}`).
+         * For mapping when Metro `resolveRequest` returns `{ type: 'empty' }`, or
+         * when webpack `resolve.fallback` is `false`. If `path` is omitted, the
+         * specifier is used as the identifier. */
+        disabled?: boolean;
+    }>): void;
+    onLoad(options: {
+        filter: RegExp;
+    }, callback: (args: {
+        path: string;
+    }) => HookResult<{
+        contents: string | Uint8Array;
+        loader?: string;
+        map?: unknown;
+    }>): void;
+    onTransform(options: {
+        filter: RegExp;
+    }, callback: (args: {
+        code: string;
+        path: string;
+    }) => HookResult<{
+        code: string;
+        map?: unknown;
+    }>): void;
+    onRenderChunk(options: {
+        filter: RegExp;
+    }, callback: (args: {
+        code: string;
+        chunk: string;
+    }) => HookResult<{
+        code: string;
+    }>): void;
+    onGenerateBundle(callback: (outputs: OutputFile[]) => void | Promise<void>): void;
+    /**
+     * Called once at bundle start. Same as esbuild `onStart`,
+     * Rollup/Vite/rolldown `buildStart` (#2156). In watch mode it is called for
+     * the initial build and on every rebuild (same as the Rollup 5+ policy).
+     *
+     * No arguments — same as esbuild `onStart`. `BuildOptions` is already passed
+     * during the plugin's own setup.
+     */
+    onBuildStart(callback: () => void | Promise<void>): void;
+    /**
+     * Called once at bundle end. Dispatched for both success and failure. On
+     * failure, the first fatal diagnostic item is wrapped in an `Error` and
+     * passed (#2156). In watch mode it is called for the initial build and on
+     * every rebuild.
+     *
+     * Called before `onCloseBundle`.
+     */
+    onBuildEnd(callback: (error?: Error) => void | Promise<void>): void;
+    /**
+     * Called once after output files are written (#2156). Same as Rollup
+     * `closeBundle` — used for temp file cleanup, notifying external systems of
+     * build completion, etc. In watch mode it is called for the initial build
+     * and on every rebuild.
+     */
+    onCloseBundle(callback: () => void | Promise<void>): void;
+    onAstFunction(options: {
+        filter: RegExp;
+    }, callback: (info: AstFunctionInfo) => HookResult<AstFunctionResult>): void;
+    /**
+     * Fills in the match results of `require.context(dir, recursive, filter,
+     * mode)` from the host runtime. (#1579) Since ZNTC has no regex executor of
+     * its own (#1771), this is delegated to the host's RegExp — Node V8 / Bun
+     * JSC.
+     *
+     * `options.filter` applies to `dir` (e.g. `/^\.\/app/` to process only a
+     * specific directory).
+     * Callback return:
+     *   - `{ context: string[] }` — array of matched file paths (empty array =
+     *     empty context)
+     *   - `null`/`undefined` — try the next plugin (if all are null, the graph
+     *     emits a require_context_no_handler diagnostic)
+     *
+     * The callback argument `filter` is the regex body of require.context
+     * (without slashes), and `flags` are the regex flags. The host compiles it
+     * with `new RegExp(filter, flags)` and then matches.
+     */
+    onResolveContext(options: {
+        filter: RegExp;
+    }, callback: (args: {
+        dir: string;
+        recursive: boolean;
+        filter?: string;
+        flags?: string;
+        importer: string;
+    }) => HookResult<{
+        context: string[];
+    }>): void;
+}
+export interface AstFunctionInfo {
+    name: string | null;
+    directives: string[];
+    closureVars: string[];
+    params: string[];
+    sourcePath: string;
+    bodyText: string;
+    flags: {
+        async: boolean;
+        generator: boolean;
+    };
+}
+export interface AstFunctionResult {
+    stripDirective?: string;
+    trailingCode?: string[];
+}
+export interface BuildResult {
+    outputFiles: OutputFile[];
+    errors: Diagnostic[];
+    warnings: Diagnostic[];
+    metafile?: string;
+    outputCount?: number;
+    rnAssetMetadata?: RnAssetMetadata[];
+    outputsByFormat?: Array<{
+        format: 'esm' | 'cjs' | 'iife' | 'umd' | 'amd';
+        outputFiles: OutputFile[];
+    }>;
+}
+/**
+ * Options for building a Vite-style browser application from an HTML entry.
+ */
+export interface AppBuildOptions {
+    /** Application root directory used to resolve index.html, public/, and env files. */
+    root?: string;
+    /** Output directory for the production app build. Defaults to "dist". */
+    outdir?: string;
+    /** HTML entry file to scan for module scripts, stylesheets, and static assets. */
+    entryHtml?: string;
+    /** Public assets directory to copy as-is, or false to disable public asset copying. */
+    publicDir?: string | false;
+    /** Base URL prefix used when rewriting HTML and emitted asset URLs. */
+    base?: string;
+    /** Environment mode used for .env resolution and import.meta.env defaults. */
+    mode?: string;
+    /** Directory to load .env files from. Defaults to the application root. */
+    envDir?: string;
+    /** Environment variable prefixes that are exposed to import.meta.env. */
+    envPrefixes?: string[];
+    /** Additional compile-time defines merged into the underlying bundle build. */
+    define?: Record<string, string>;
+    /** Minify emitted JavaScript and CSS when supported by the underlying builder. */
+    minify?: boolean;
+    /** Emit sourcemaps for bundled application assets. */
+    sourcemap?: boolean;
+    /** Enable code splitting for the application bundle. */
+    splitting?: boolean;
+    /** JSX runtime: "automatic" / "automatic-dev" / "classic" / "preserve". */
+    jsx?: 'classic' | 'automatic' | 'automatic-dev' | 'preserve';
+    /** JSX import source for the automatic runtime (e.g. "react", "@emotion/react"). */
+    jsxImportSource?: string;
+    /** Classic-runtime JSX factory (e.g. "React.createElement", "h"). */
+    jsxFactory?: string;
+    /** Classic-runtime JSX fragment (e.g. "React.Fragment"). */
+    jsxFragment?: string;
+    /**
+     * Per-library 1st-party transform (`@next/swc` `compiler`-compatible
+     * surface). Same meaning as in BuildOptions — both bundle / app builds use
+     * the same option representation.
+     */
+    compiler?: CompilerOptions;
+}
+/**
+ * Options for preparing a Vite-style application for the development server.
+ */
+export interface AppDevPrepareOptions {
+    /** Application root directory used to resolve index.html, public/, and env files. */
+    root?: string;
+    /** Temporary output directory used by the dev server. Defaults to ".zntc-dev". */
+    outdir?: string;
+    /** HTML entry file to scan for module scripts, stylesheets, and static assets. */
+    entryHtml?: string;
+    /** Public assets directory to copy as-is, or false to disable public asset copying. */
+    publicDir?: string | false;
+    /** Base URL prefix used when rewriting dev HTML and asset URLs. */
+    base?: string;
+    /** Environment mode used for .env resolution. Defaults to "development". */
+    mode?: string;
+    /** Directory to load .env files from. Defaults to the application root. */
+    envDir?: string;
+    /** Environment variable prefixes that are exposed to import.meta.env. */
+    envPrefixes?: string[];
+}
+/**
+ * Result produced after preparing an application entry for dev-server bundling.
+ */
+export interface AppDevPrepareResult {
+    /** Prepared JavaScript entry path that the dev server should bundle and serve. */
+    entryPath: string;
+    /** Number of files emitted while preparing the dev app, when available. */
+    outputCount?: number;
+}
+/**
+ * Runs bundling asynchronously. Does not block the event loop.
+ * Promise/async hooks of JS plugins are supported in this function.
+ *
+ * Plugin lifecycle call order: buildStart → (NAPI build) → buildEnd → write →
+ * closeBundle.
+ * `buildEnd` is called even on NAPI failure, with the error argument passed
+ * (same as Rollup).
+ * `closeBundle` is called only on a successful write.
+ */
+export declare function build(options: BuildOptions): Promise<BuildResult>;
+/**
+ * Runs bundling synchronously.
+ * JS plugins support only sync hooks. Promise/async hooks fail with a
+ * plugin_error.
+ */
+export declare function buildSync(options: BuildOptions): BuildResult;
+export interface OutputOptions {
+    format?: 'esm' | 'cjs' | 'iife' | 'umd' | 'amd';
+    dir?: string;
+    file?: string;
+    globals?: Record<string, string>;
+}
+export declare class BuildInstance {
+    #private;
+    constructor(base: BuildOptions);
+    get closed(): boolean;
+    write(output?: OutputOptions): Promise<BuildResult>;
+    generate(output?: OutputOptions): Promise<BuildResult>;
+    close(): Promise<void>;
+}
+export declare function zntc(options: BuildOptions): Promise<BuildInstance>;
+export declare function buildAppSync(options?: AppBuildOptions): BuildResult;
+export declare function prepareAppDevSync(options?: AppDevPrepareOptions): AppDevPrepareResult;
+/**
+ * Releases resources (the NAPI module is released automatically on process
+ * exit). Kept for API compatibility.
+ */
+export declare function close(): void;
+/**
+ * Benchmark options. One of `source` or `file` must be specified.
+ */
+export interface BenchmarkOptions {
+    /** Source code string (one of this or file). */
+    source?: string;
+    /** File path (one of this or source). */
+    file?: string;
+    /** filename (used together with source, for extension detection). */
+    filename?: string;
+    /**
+     * List of profile categories to measure (required, non-empty).
+     * e.g. `["parse"]`, `["scan", "parse", "transform"]`, `["transform.jsx"]`.
+     * `all` / `none` are not allowed — concrete phase names only.
+     */
+    phases: string[];
+    /** Number of iterations (default 100). */
+    iterations?: number;
+    /** Warmup iterations (default 10). */
+    warmup?: number;
+}
+/**
+ * Statistics for a single phase (all values in ms).
+ */
+export interface BenchmarkPhaseStats {
+    samples: number;
+    mean_ms: number;
+    median_ms: number;
+    p95_ms: number;
+    p99_ms: number;
+    min_ms: number;
+    max_ms: number;
+    stddev_ms: number;
+}
+/**
+ * Benchmark result — statistics per category specified in the `phases` option.
+ */
+export interface BenchmarkResult {
+    phases: Record<string, BenchmarkPhaseStats>;
+}
+/**
+ * Runs a specific phase N times and returns statistics
+ * (mean/median/p95/p99/stddev/min/max).
+ *
+ * The NAPI counterpart of CLI `zntc bench --phase=...` — uses the same engine.
+ *
+ * @example
+ * ```ts
+ * import { benchmark } from "@zntc/core";
+ *
+ * const result = benchmark({
+ *   file: "./src/App.tsx",
+ *   phases: ["parse"],
+ *   iterations: 100,
+ * });
+ * console.log(result.phases.parse.mean_ms);  // 42.3
+ * ```
+ */
+export declare function benchmark(options: BenchmarkOptions): BenchmarkResult;
+/**
+ * Converts a Rollup/Vite-style plugin into a ZNTC plugin.
+ *
+ * @example
+ * ```ts
+ * import { vitePlugin } from "@zntc/core";
+ *
+ * const result = await build({
+ *   entryPoints: ["src/index.ts"],
+ *   plugins: [
+ *     vitePlugin({
+ *       name: "my-rollup-plugin",
+ *       resolveId(source) { ... },
+ *       load(id) { ... },
+ *       transform(code, id) { ... },
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+type MaybePromise<T> = T | Promise<T>;
+/** vite 4+ 신형 hook object. plugin 작성자가 hook 단위로 filter 를 선언하는 형식.
+ *  ZNTC 는 현재 filter 를 native 단계에서 활용하지 않고 handler 만 추출해 호출한다. */
+type HookObject<F extends (...args: never[]) => unknown> = {
+    filter?: unknown;
+    order?: 'pre' | 'post' | null;
+    handler: F;
+};
+type Hook<F extends (...args: never[]) => unknown> = F | HookObject<F>;
+export interface RollupPluginContext {
+    /** Throw an error from within the plugin. Rollup `this.error`-compatible. */
+    error(error: unknown): never;
+    /** Print a warning to the console. Rollup `this.warn`-compatible — does not stop the build. */
+    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. */
+    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. */
+    emitFile(file: unknown): string;
+}
+type ResolveIdResult = string | null | undefined | void | {
+    id: string;
+    external?: boolean;
+};
+type LoadResult = string | null | undefined | void | {
+    code: string;
+    map?: unknown;
+};
+type TransformResult = string | null | undefined | void | {
+    code: string;
+    map?: unknown;
+};
+type RenderChunkResult = string | null | undefined | void | {
+    code: string;
+};
+export interface RollupPlugin {
+    name: string;
+    /** Rollup `resolveId`. Both a function and a vite 4+ new-style hook object `{ filter, handler }` are allowed. */
+    resolveId?: Hook<(this: RollupPluginContext, source: string, importer?: string | null) => MaybePromise<ResolveIdResult>>;
+    load?: Hook<(this: RollupPluginContext, id: string) => MaybePromise<LoadResult>>;
+    transform?: Hook<(this: RollupPluginContext, code: string, id: string) => MaybePromise<TransformResult>>;
+    renderChunk?: Hook<(this: RollupPluginContext, code: string, chunk: string) => MaybePromise<RenderChunkResult>>;
+    generateBundle?: Hook<(this: RollupPluginContext, outputs: OutputFile[]) => MaybePromise<void>>;
+    /** Once at bundle start. esbuild `onStart` / Rollup `buildStart`-compatible
+     *  (#2156). ZNTC calls it with no arguments (esbuild style) — if a Rollup
+     *  plugin expects the `options` argument, capture it in the plugin's own
+     *  closure. */
+    buildStart?: Hook<(this: RollupPluginContext) => MaybePromise<void>>;
+    /** Once at bundle end. Rollup `buildEnd`-compatible — if there is an error, the build fails. */
+    buildEnd?: Hook<(this: RollupPluginContext, error?: Error) => MaybePromise<void>>;
+    /** After output files are written. Rollup `closeBundle`-compatible. */
+    closeBundle?: Hook<(this: RollupPluginContext) => MaybePromise<void>>;
+}
+export declare function vitePlugin(rollupPlugin: RollupPlugin): ZntcPlugin;
+/**
+ * Bundles in watch mode. On file changes: incremental rebuild + HMR diff.
+ * Calls the onReady callback when the initial build completes, and onRebuild
+ * on each rebuild.
+ *
+ * Plugin lifecycle call order: buildStart → (NAPI build/rebuild) → buildEnd
+ * → onReady/onRebuild → closeBundle. closeBundle is called even if there is no
+ * callback or it throws.
+ */
+export declare function watch(options: BuildOptions): WatchHandle;