@chidchanun/bcp 0.1.0

package/packages/bundler/src/index.ts

@@ -0,0 +1,1991 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import {
+    createRequire,
+} from "node:module";
+
+import {
+    build,
+    context,
+    type BuildContext,
+    type BuildResult,
+    type Plugin,
+} from "esbuild";
+
+import {
+    transformAsync,
+} from "@babel/core";
+
+import {
+    createClientEnvironmentDefines,
+} from "../../env/src/index.js";
+
+import type {
+    Route,
+} from "../../router/src/index.js";
+
+/*
+ * =====================================
+ * CommonJS / Babel Helpers
+ * =====================================
+ */
+
+const require =
+    createRequire(
+        import.meta.url
+    );
+
+function unwrapModule<T>(
+    value: any
+): T {
+    return (
+        value?.default ??
+        value
+    ) as T;
+}
+
+const reactRefreshBabel =
+    unwrapModule<any>(
+        require(
+            "react-refresh/babel"
+        )
+    );
+
+const presetReact =
+    unwrapModule<any>(
+        require(
+            "@babel/preset-react"
+        )
+    );
+
+const presetTypeScript =
+    unwrapModule<any>(
+        require(
+            "@babel/preset-typescript"
+        )
+    );
+
+/*
+ * =====================================
+ * Types
+ * =====================================
+ */
+
+export interface ClientBundle {
+    pathname: string;
+
+    publicPath: string;
+
+    filePath: string;
+
+    content: Buffer;
+}
+
+export interface DevAsset {
+    publicPath: string;
+
+    filePath: string;
+
+    content: Buffer;
+
+    contentType: string;
+}
+
+export interface ClientBuildOptions {
+    fastRefresh?: boolean;
+}
+
+interface RouteBuildState {
+    route: Route;
+
+    context: BuildContext;
+
+    outputFile: string;
+
+    bundle: ClientBundle;
+
+    /*
+     * Dependency files ของ route นี้
+     */
+    inputFiles: Set<string>;
+}
+
+interface RouteBuildSnapshot {
+    bundle: ClientBundle;
+
+    inputFiles: Set<string>;
+}
+
+/*
+ * =====================================
+ * Public Paths
+ * =====================================
+ */
+
+const VENDOR_PATH =
+    "/_bcp/vendor";
+
+export const DEV_RUNTIME_PATH =
+    "/_bcp/dev-runtime.js";
+
+/*
+ * =====================================
+ * Vendor Proxy
+ * =====================================
+ */
+
+function createVendorProxySource(
+    packageName: string
+): string {
+    const packageModule =
+        require(
+            packageName
+        );
+
+    const exportNames =
+        Object.keys(
+            packageModule
+        )
+            .filter(
+                (name) =>
+                    name !==
+                    "default" &&
+                    /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(
+                        name
+                    )
+            );
+
+    const namedExports =
+        exportNames
+            .map(
+                (name) => `
+export const ${name} =
+  __bcpModule[${JSON.stringify(name)}];
+        `.trim()
+            )
+            .join("\n\n");
+
+    return `
+import __bcpModule from ${JSON.stringify(packageName)};
+
+${namedExports}
+
+export default __bcpModule;
+  `.trim();
+}
+
+/*
+ * =====================================
+ * React Vendor + Refresh Runtime
+ * =====================================
+ */
+
+export async function buildDevAssets(
+    rootDirectory: string
+): Promise<DevAsset[]> {
+    const frameworkDirectory =
+        path.join(
+            rootDirectory,
+            ".bcp-framework"
+        );
+
+    const vendorSourceDirectory =
+        path.join(
+            frameworkDirectory,
+            "vendor-src"
+        );
+
+    const vendorOutputDirectory =
+        path.join(
+            frameworkDirectory,
+            "vendor"
+        );
+
+    const runtimeDirectory =
+        path.join(
+            frameworkDirectory,
+            "runtime"
+        );
+
+    fs.rmSync(
+        vendorSourceDirectory,
+        {
+            recursive: true,
+            force: true,
+        }
+    );
+
+    fs.rmSync(
+        vendorOutputDirectory,
+        {
+            recursive: true,
+            force: true,
+        }
+    );
+
+    fs.rmSync(
+        runtimeDirectory,
+        {
+            recursive: true,
+            force: true,
+        }
+    );
+
+    fs.mkdirSync(
+        vendorSourceDirectory,
+        {
+            recursive: true,
+        }
+    );
+
+    fs.mkdirSync(
+        vendorOutputDirectory,
+        {
+            recursive: true,
+        }
+    );
+
+    fs.mkdirSync(
+        runtimeDirectory,
+        {
+            recursive: true,
+        }
+    );
+
+    /*
+     * =================================
+     * Vendor Entry Files
+     * =================================
+     */
+
+    const reactEntry =
+        path.join(
+            vendorSourceDirectory,
+            "react.ts"
+        );
+
+    const jsxRuntimeEntry =
+        path.join(
+            vendorSourceDirectory,
+            "react-jsx-runtime.ts"
+        );
+
+    const jsxDevRuntimeEntry =
+        path.join(
+            vendorSourceDirectory,
+            "react-jsx-dev-runtime.ts"
+        );
+
+    const reactDomEntry =
+        path.join(
+            vendorSourceDirectory,
+            "react-dom.ts"
+        );
+
+    const reactDomClientEntry =
+        path.join(
+            vendorSourceDirectory,
+            "react-dom-client.ts"
+        );
+
+    fs.writeFileSync(
+        reactEntry,
+        createVendorProxySource(
+            "react"
+        )
+    );
+
+    fs.writeFileSync(
+        jsxRuntimeEntry,
+        createVendorProxySource(
+            "react/jsx-runtime"
+        )
+    );
+
+    fs.writeFileSync(
+        jsxDevRuntimeEntry,
+        createVendorProxySource(
+            "react/jsx-dev-runtime"
+        )
+    );
+
+    fs.writeFileSync(
+        reactDomEntry,
+        createVendorProxySource(
+            "react-dom"
+        )
+    );
+
+    fs.writeFileSync(
+        reactDomClientEntry,
+        createVendorProxySource(
+            "react-dom/client"
+        )
+    );
+
+    /*
+     * Build shared React vendor
+     */
+    await build({
+        entryPoints: {
+            react:
+                reactEntry,
+
+            "react-jsx-runtime":
+                jsxRuntimeEntry,
+
+            "react-jsx-dev-runtime":
+                jsxDevRuntimeEntry,
+
+            "react-dom":
+                reactDomEntry,
+
+            "react-dom-client":
+                reactDomClientEntry,
+        },
+
+        outdir:
+            vendorOutputDirectory,
+
+        bundle:
+            true,
+
+        splitting:
+            true,
+
+        format:
+            "esm",
+
+        platform:
+            "browser",
+
+        target: [
+            "es2022",
+        ],
+
+        entryNames:
+            "[name]",
+
+        chunkNames:
+            "chunks/[name]-[hash]",
+
+        define: {
+            "process.env.NODE_ENV":
+                '"development"',
+        },
+
+        sourcemap:
+            "inline",
+
+        logLevel:
+            "silent",
+    });
+
+    /*
+     * =================================
+     * HMR Runtime
+     * =================================
+     */
+
+    const runtimeOutput =
+        path.join(
+            runtimeDirectory,
+            "dev-runtime.js"
+        );
+
+    const runtimeSource = `
+import RefreshRuntime from "react-refresh/runtime";
+
+/*
+ * Inject React Refresh
+ */
+if (!globalThis.__BCP_REFRESH_RUNTIME__) {
+  RefreshRuntime.injectIntoGlobalHook(
+    window
+  );
+
+  globalThis.__BCP_REFRESH_RUNTIME__ =
+    RefreshRuntime;
+}
+
+const config =
+  globalThis.__BCP_DEV_CONFIG__;
+
+if (!config) {
+  throw new Error(
+    "BCP Framework: dev configuration was not found."
+  );
+}
+
+/*
+ * EventSource เปิดแค่ครั้งเดียว
+ */
+if (!globalThis.__BCP_HMR_SOURCE__) {
+  const source =
+    new EventSource(
+      config.eventsPath
+    );
+
+  globalThis.__BCP_HMR_SOURCE__ =
+    source;
+
+  /*
+   * =================================
+   * Fast Refresh
+   * =================================
+   */
+
+  source.addEventListener(
+    "refresh",
+    async (event) => {
+      const data =
+        JSON.parse(
+          event.data
+        );
+
+      /*
+       * สำคัญ:
+       *
+       * Server ส่ง affected routes มา
+       *
+       * ถ้า route ปัจจุบันไม่ได้รับผลกระทบ
+       * ไม่ต้อง import bundle ใหม่
+       */
+      if (
+        Array.isArray(
+          data.routes
+        ) &&
+        !data.routes.includes(
+          config.route
+        )
+      ) {
+        return;
+      }
+
+      const separator =
+        config.clientScript.includes("?")
+          ? "&"
+          : "?";
+
+      const moduleUrl =
+        config.clientScript +
+        separator +
+        "v=" +
+        encodeURIComponent(
+          data.version
+        );
+
+      try {
+        await import(
+          moduleUrl
+        );
+
+        RefreshRuntime
+          .performReactRefresh();
+
+        console.log(
+          "[BCP] Fast Refresh applied:",
+          config.route
+        );
+      } catch (error) {
+        console.error(
+          "[BCP] Fast Refresh failed:",
+          error
+        );
+
+        window.location.reload();
+      }
+    }
+  );
+
+  /*
+   * =================================
+   * Full Reload
+   * =================================
+   */
+
+  source.addEventListener(
+    "reload",
+    () => {
+      console.log(
+        "[BCP] Full reload"
+      );
+
+      window.location.reload();
+    }
+  );
+}
+  `.trim();
+
+    await build({
+        stdin: {
+            contents:
+                runtimeSource,
+
+            resolveDir:
+                rootDirectory,
+
+            sourcefile:
+                "bcp-dev-runtime.js",
+
+            loader:
+                "js",
+        },
+
+        outfile:
+            runtimeOutput,
+
+        bundle:
+            true,
+
+        format:
+            "iife",
+
+        platform:
+            "browser",
+
+        target: [
+            "es2022",
+        ],
+
+        define: {
+            "process.env.NODE_ENV":
+                '"development"',
+        },
+
+        sourcemap:
+            "inline",
+
+        logLevel:
+            "silent",
+    });
+
+    /*
+     * =================================
+     * Assets → RAM
+     * =================================
+     */
+
+    const assets:
+        DevAsset[] = [];
+
+    collectFiles(
+        vendorOutputDirectory,
+        (filePath) => {
+            const relative =
+                path.relative(
+                    vendorOutputDirectory,
+                    filePath
+                )
+                    .replace(
+                        /\\/g,
+                        "/"
+                    );
+
+            assets.push({
+                publicPath:
+                    `${VENDOR_PATH}/${relative}`,
+
+                filePath,
+
+                content:
+                    fs.readFileSync(
+                        filePath
+                    ),
+
+                contentType:
+                    "text/javascript; charset=utf-8",
+            });
+        }
+    );
+
+    assets.push({
+        publicPath:
+            DEV_RUNTIME_PATH,
+
+        filePath:
+            runtimeOutput,
+
+        content:
+            fs.readFileSync(
+                runtimeOutput
+            ),
+
+        contentType:
+            "text/javascript; charset=utf-8",
+    });
+
+    return assets;
+}
+
+/*
+ * =====================================
+ * Incremental Client Bundler
+ * =====================================
+ */
+
+export class DevClientBundler {
+    private readonly states =
+        new Map<
+            string,
+            RouteBuildState
+        >();
+
+    /*
+     * Dependency graph:
+     *
+     * filePath
+     *
+     * ↓
+     *
+     * Set<Route Pathname>
+     */
+    private readonly moduleToRoutes =
+        new Map<
+            string,
+            Set<string>
+        >();
+
+    private constructor(
+        private readonly rootDirectory:
+            string,
+
+        private readonly options:
+            ClientBuildOptions
+    ) { }
+
+    /*
+     * =================================
+     * Create
+     * =================================
+     */
+
+    static async create(
+        routes: Route[],
+        rootDirectory: string,
+        options:
+            ClientBuildOptions = {}
+    ): Promise<DevClientBundler> {
+        const bundler =
+            new DevClientBundler(
+                rootDirectory,
+                options
+            );
+
+        try {
+            await bundler.initialize(
+                routes
+            );
+
+            return bundler;
+        } catch (error) {
+            await bundler.dispose();
+
+            throw error;
+        }
+    }
+
+    /*
+     * =================================
+     * Initial Build
+     * =================================
+     */
+
+    private async initialize(
+        routes: Route[]
+    ) {
+        const outputDirectory =
+            path.join(
+                this.rootDirectory,
+                ".bcp-framework",
+                "client"
+            );
+
+        fs.rmSync(
+            outputDirectory,
+            {
+                recursive: true,
+                force: true,
+            }
+        );
+
+        fs.mkdirSync(
+            outputDirectory,
+            {
+                recursive: true,
+            }
+        );
+
+        /*
+         * สร้าง esbuild Context
+         * ต่อ Route
+         */
+        for (
+            const route
+            of routes
+        ) {
+            const state =
+                await this.createRouteState(
+                    route,
+                    outputDirectory
+                );
+
+            this.states.set(
+                route.pathname,
+                state
+            );
+        }
+
+        /*
+         * Initial build
+         *
+         * build ทุก route ครั้งแรก
+         */
+        const states =
+            Array.from(
+                this.states.values()
+            );
+
+        const snapshots =
+            await Promise.all(
+                states.map(
+                    (state) =>
+                        this.buildState(
+                            state
+                        )
+                )
+            );
+
+        /*
+         * ทุก route build ผ่านแล้ว
+         * จึงค่อย commit state
+         */
+        for (
+            let index = 0;
+            index <
+            states.length;
+            index++
+        ) {
+            this.commitSnapshot(
+                states[index],
+                snapshots[index]
+            );
+        }
+
+        this.rebuildModuleGraph();
+    }
+
+    /*
+     * =================================
+     * Create Route Context
+     * =================================
+     */
+
+    private async createRouteState(
+        route: Route,
+        outputDirectory: string
+    ): Promise<RouteBuildState> {
+        const bundleName =
+            routeToBundleName(
+                route.pathname
+            );
+
+        const outputFile =
+            path.join(
+                outputDirectory,
+                bundleName
+            );
+
+        const clientEntry =
+            createClientEntry(
+                route,
+                this.rootDirectory
+            );
+
+        const plugins:
+            Plugin[] = [];
+
+        if (
+            this.options.fastRefresh
+        ) {
+            plugins.push(
+                createReactVendorPlugin()
+            );
+
+            plugins.push(
+                createReactRefreshPlugin(
+                    this.rootDirectory
+                )
+            );
+        }
+
+        /*
+         * esbuild context()
+         *
+         * Context นี้จะถูกเก็บไว้
+         * ตลอด Dev Server lifetime
+         */
+        const buildContext =
+            await context({
+                absWorkingDir:
+                    this.rootDirectory,
+
+                stdin: {
+                    contents:
+                        clientEntry,
+
+                    resolveDir:
+                        this.rootDirectory,
+
+                    sourcefile:
+                        `bcp-entry-${sanitizeBundleId(route.pathname)}.js`,
+
+                    loader:
+                        "js",
+                },
+
+                outfile:
+                    outputFile,
+
+                bundle:
+                    true,
+
+                /*
+                 * สำคัญ:
+                 *
+                 * ไม่ให้ esbuild เขียนลง disk
+                 * ทุก rebuild
+                 *
+                 * เราจะอ่าน outputFiles
+                 * เข้า RAM โดยตรง
+                 */
+                write:
+                    false,
+
+                metafile:
+                    true,
+
+                platform:
+                    "browser",
+
+                format:
+                    "esm",
+
+                target: [
+                    "es2022",
+                ],
+
+                plugins,
+
+                jsx:
+                    "automatic",
+
+                define:
+                    createClientEnvironmentDefines(
+                        "development"
+                    ),
+
+                sourcemap:
+                    "inline",
+
+                logLevel:
+                    "silent",
+            });
+
+        const publicPath =
+            `/_bcp/client/${bundleName}`;
+
+        return {
+            route,
+
+            context:
+                buildContext,
+
+            outputFile,
+
+            /*
+             * Placeholder
+             * จะถูกแทนหลัง initial rebuild
+             */
+            bundle: {
+                pathname:
+                    route.pathname,
+
+                publicPath,
+
+                filePath:
+                    outputFile,
+
+                content:
+                    Buffer.alloc(0),
+            },
+
+            inputFiles:
+                new Set(),
+        };
+    }
+
+    /*
+     * =================================
+     * Incremental Rebuild
+     * =================================
+     */
+
+    async rebuildAffected(
+        changedFiles: string[]
+    ): Promise<string[]> {
+        const affected =
+            this.findAffectedRoutes(
+                changedFiles
+            );
+
+        if (
+            affected.length ===
+            0
+        ) {
+            return [];
+        }
+
+        const states =
+            affected
+                .map(
+                    (pathname) =>
+                        this.states.get(
+                            pathname
+                        )
+                )
+                .filter(
+                    (
+                        state
+                    ): state is
+                        RouteBuildState =>
+                        Boolean(
+                            state
+                        )
+                );
+
+        /*
+         * context.rebuild()
+         *
+         * esbuild จะ reuse cache
+         * ของ context เดิม
+         */
+        const snapshots =
+            await Promise.all(
+                states.map(
+                    (state) =>
+                        this.buildState(
+                            state
+                        )
+                )
+            );
+
+        /*
+         * Atomic-ish commit:
+         *
+         * ถ้า Promise.all fail
+         * จะยังไม่ commit bundle ใหม่
+         */
+        for (
+            let index = 0;
+            index <
+            states.length;
+            index++
+        ) {
+            this.commitSnapshot(
+                states[index],
+                snapshots[index]
+            );
+        }
+
+        /*
+         * Dependency อาจเปลี่ยนหลัง build
+         *
+         * เช่น:
+         *
+         * Page
+         *   เดิม import A
+         *
+         * เปลี่ยนเป็น
+         *
+         * Page
+         *   import A
+         *   import B
+         *
+         * จึง rebuild graph ใหม่
+         */
+        this.rebuildModuleGraph();
+
+        return affected;
+    }
+
+    /*
+     * =================================
+     * Build One Route
+     * =================================
+     */
+
+    private async buildState(
+        state: RouteBuildState
+    ): Promise<RouteBuildSnapshot> {
+        const result =
+            await state.context
+                .rebuild();
+
+        const output =
+            findJavaScriptOutput(
+                result,
+                state.outputFile
+            );
+
+        if (!output) {
+            throw new Error(
+                `BCP Framework: output bundle was not found for route "${state.route.pathname}".`
+            );
+        }
+
+        const inputFiles =
+            collectInputFiles(
+                result,
+                this.rootDirectory
+            );
+
+        /*
+         * Page/Layout ต้องอยู่ graph
+         * เสมอ แม้ metafile มี behavior
+         * แตกต่างจาก plugin
+         */
+        inputFiles.add(
+            normalizeGraphPath(
+                state.route.filePath
+            )
+        );
+
+        for (
+            const layoutFile
+            of state.route.layouts
+        ) {
+            inputFiles.add(
+                normalizeGraphPath(
+                    layoutFile
+                )
+            );
+        }
+
+        return {
+            bundle: {
+                pathname:
+                    state.route.pathname,
+
+                publicPath:
+                    state.bundle.publicPath,
+
+                filePath:
+                    state.outputFile,
+
+                content:
+                    Buffer.from(
+                        output.contents
+                    ),
+            },
+
+            inputFiles,
+        };
+    }
+
+    /*
+     * =================================
+     * Commit Route Build
+     * =================================
+     */
+
+    private commitSnapshot(
+        state: RouteBuildState,
+        snapshot: RouteBuildSnapshot
+    ) {
+        state.bundle =
+            snapshot.bundle;
+
+        state.inputFiles =
+            snapshot.inputFiles;
+    }
+
+    /*
+     * =================================
+     * Module Graph
+     * =================================
+     */
+
+    private rebuildModuleGraph() {
+        this.moduleToRoutes
+            .clear();
+
+        for (
+            const state
+            of this.states.values()
+        ) {
+            for (
+                const filePath
+                of state.inputFiles
+            ) {
+                let routeSet =
+                    this.moduleToRoutes
+                        .get(
+                            filePath
+                        );
+
+                if (!routeSet) {
+                    routeSet =
+                        new Set<string>();
+
+                    this.moduleToRoutes.set(
+                        filePath,
+                        routeSet
+                    );
+                }
+
+                routeSet.add(
+                    state.route.pathname
+                );
+            }
+        }
+    }
+
+    /*
+     * =================================
+     * Find Affected Routes
+     * =================================
+     */
+
+    findAffectedRoutes(
+        changedFiles: string[]
+    ): string[] {
+        const affected =
+            new Set<string>();
+
+        for (
+            const filePath
+            of changedFiles
+        ) {
+            const normalized =
+                normalizeGraphPath(
+                    filePath
+                );
+
+            const routes =
+                this.moduleToRoutes
+                    .get(
+                        normalized
+                    );
+
+            if (!routes) {
+                continue;
+            }
+
+            for (
+                const pathname
+                of routes
+            ) {
+                affected.add(
+                    pathname
+                );
+            }
+        }
+
+        return Array.from(
+            affected
+        ).sort();
+    }
+
+    /*
+     * =================================
+     * Debug Graph
+     * =================================
+     */
+
+    printAffectedRoutes(
+        filePath: string
+    ) {
+        const affected =
+            this.findAffectedRoutes([
+                filePath,
+            ]);
+
+        console.log(
+            `[module-graph] ${path.relative(
+                this.rootDirectory,
+                filePath
+            )}`
+        );
+
+        if (
+            affected.length ===
+            0
+        ) {
+            console.log(
+                "  → no client routes"
+            );
+
+            return;
+        }
+
+        for (
+            const pathname
+            of affected
+        ) {
+            console.log(
+                `  → ${pathname}`
+            );
+        }
+    }
+
+    /*
+     * =================================
+     * Bundles
+     * =================================
+     */
+
+    getBundles():
+        ClientBundle[] {
+        return Array.from(
+            this.states.values()
+        ).map(
+            (state) =>
+                state.bundle
+        );
+    }
+
+    /*
+     * =================================
+     * Dispose
+     * =================================
+     */
+
+    async dispose() {
+        const contexts =
+            Array.from(
+                this.states.values()
+            ).map(
+                (state) =>
+                    state.context
+            );
+
+        this.states.clear();
+
+        this.moduleToRoutes
+            .clear();
+
+        await Promise.all(
+            contexts.map(
+                (buildContext) =>
+                    buildContext.dispose()
+            )
+        );
+    }
+}
+
+/*
+ * =====================================
+ * Client Entry Generator
+ * =====================================
+ */
+
+function createClientEntry(
+    route: Route,
+    rootDirectory: string
+): string {
+    const pageImport =
+        toImportSpecifier(
+            rootDirectory,
+            route.filePath
+        );
+
+    const layoutImports =
+        route.layouts
+            .map(
+                (
+                    layoutFile,
+                    index
+                ) => {
+                    const importPath =
+                        toImportSpecifier(
+                            rootDirectory,
+                            layoutFile
+                        );
+
+                    return `
+import Layout${index} from ${JSON.stringify(importPath)};
+          `.trim();
+                }
+            )
+            .join("\n");
+
+    const layoutNames =
+        route.layouts
+            .map(
+                (
+                    _,
+                    index
+                ) =>
+                    `Layout${index}`
+            )
+            .join(", ");
+
+    return `
+import {
+  createElement
+} from "react";
+
+import {
+  hydrateRoot
+} from "react-dom/client";
+
+import Page from ${JSON.stringify(pageImport)};
+
+${layoutImports}
+
+const rootElement =
+  document.getElementById(
+    "root"
+  );
+
+if (!rootElement) {
+  throw new Error(
+    "BCP Framework: root element was not found."
+  );
+}
+
+const dataElement =
+  document.getElementById(
+    "__BCP_DATA__"
+  );
+
+if (!dataElement) {
+  throw new Error(
+    "BCP Framework: framework data was not found."
+  );
+}
+
+const data =
+  JSON.parse(
+    dataElement.textContent ||
+    "{}"
+  );
+
+const params =
+  data.params || {};
+
+const layouts = [
+  ${layoutNames}
+];
+
+let tree =
+  createElement(
+    Page,
+    {
+      params
+    }
+  );
+
+for (
+  let index =
+    layouts.length - 1;
+
+  index >= 0;
+
+  index--
+) {
+  const Layout =
+    layouts[index];
+
+  tree =
+    createElement(
+      Layout,
+      {
+        params
+      },
+      tree
+    );
+}
+
+/*
+ * Initial navigation:
+ * hydrate the server-rendered HTML once.
+ *
+ * Client navigation / HMR:
+ * render into the existing hydrated root.
+ * React can then reconcile the tree and keep
+ * state for layouts that remain at the same
+ * position.
+ */
+if (
+  globalThis.__BCP_REACT_ROOT__
+) {
+  globalThis.__BCP_REACT_ROOT__
+    .render(tree);
+} else {
+  globalThis.__BCP_REACT_ROOT__ =
+    hydrateRoot(
+      rootElement,
+      tree
+    );
+}
+  `.trim();
+}
+
+/*
+ * =====================================
+ * Build Result → Input Files
+ * =====================================
+ */
+
+function collectInputFiles(
+    result: BuildResult,
+    rootDirectory: string
+): Set<string> {
+    const files =
+        new Set<string>();
+
+    const metafile =
+        result.metafile;
+
+    if (!metafile) {
+        return files;
+    }
+
+    for (
+        const input
+        of Object.keys(
+            metafile.inputs
+        )
+    ) {
+        /*
+         * Virtual entry
+         *
+         * เช่น:
+         *
+         * bcp-entry-index.js
+         *
+         * ไม่ใช่ application file
+         */
+        if (
+            input.startsWith(
+                "<"
+            ) ||
+            input.startsWith(
+                "bcp-entry-"
+            )
+        ) {
+            continue;
+        }
+
+        const absolute =
+            path.isAbsolute(
+                input
+            )
+                ? input
+                : path.resolve(
+                    rootDirectory,
+                    input
+                );
+
+        files.add(
+            normalizeGraphPath(
+                absolute
+            )
+        );
+    }
+
+    return files;
+}
+
+/*
+ * =====================================
+ * Output Helper
+ * =====================================
+ */
+
+function findJavaScriptOutput(
+    result: BuildResult,
+    outputFile: string
+) {
+    const outputs =
+        result.outputFiles ??
+        [];
+
+    const normalizedTarget =
+        path.normalize(
+            outputFile
+        );
+
+    const exact =
+        outputs.find(
+            (file) =>
+                path.normalize(
+                    file.path
+                ) ===
+                normalizedTarget
+        );
+
+    if (exact) {
+        return exact;
+    }
+
+    return outputs.find(
+        (file) =>
+            file.path.endsWith(
+                ".js"
+            )
+    );
+}
+
+/*
+ * =====================================
+ * Graph Path
+ * =====================================
+ */
+
+function normalizeGraphPath(
+    filePath: string
+): string {
+    let normalized =
+        path.normalize(
+            path.resolve(
+                filePath
+            )
+        );
+
+    /*
+     * Windows file system
+     * ปกติ case insensitive
+     *
+     * D:\\App\\Page.tsx
+     * d:\\app\\page.tsx
+     *
+     * ให้ถือเป็นไฟล์เดียวกัน
+     */
+    if (
+        process.platform ===
+        "win32"
+    ) {
+        normalized =
+            normalized.toLowerCase();
+    }
+
+    return normalized;
+}
+
+/*
+ * =====================================
+ * React Vendor Plugin
+ * =====================================
+ */
+
+function createReactVendorPlugin():
+    Plugin {
+    const mappings =
+        new Map<
+            string,
+            string
+        >([
+            [
+                "react",
+                `${VENDOR_PATH}/react.js`,
+            ],
+
+            [
+                "react/jsx-runtime",
+                `${VENDOR_PATH}/react-jsx-runtime.js`,
+            ],
+
+            [
+                "react/jsx-dev-runtime",
+                `${VENDOR_PATH}/react-jsx-dev-runtime.js`,
+            ],
+
+            [
+                "react-dom",
+                `${VENDOR_PATH}/react-dom.js`,
+            ],
+
+            [
+                "react-dom/client",
+                `${VENDOR_PATH}/react-dom-client.js`,
+            ],
+        ]);
+
+    return {
+        name:
+            "bcp-react-vendor",
+
+        setup(buildApi) {
+            buildApi.onResolve(
+                {
+                    filter:
+                        /^(react|react\/jsx-runtime|react\/jsx-dev-runtime|react-dom|react-dom\/client)$/,
+                },
+
+                (args) => {
+                    const publicPath =
+                        mappings.get(
+                            args.path
+                        );
+
+                    if (!publicPath) {
+                        return;
+                    }
+
+                    return {
+                        path:
+                            publicPath,
+
+                        external:
+                            true,
+                    };
+                }
+            );
+        },
+    };
+}
+
+/*
+ * =====================================
+ * React Refresh Plugin
+ * =====================================
+ */
+
+function createReactRefreshPlugin(
+    rootDirectory: string
+): Plugin {
+    return {
+        name:
+            "bcp-react-refresh",
+
+        setup(buildApi) {
+            buildApi.onLoad(
+                {
+                    filter:
+                        /\.[jt]sx?$/,
+                },
+
+                async (args) => {
+                    /*
+                     * node_modules
+                     */
+                    if (
+                        args.path.includes(
+                            `${path.sep}node_modules${path.sep}`
+                        )
+                    ) {
+                        return;
+                    }
+
+                    /*
+                     * generated framework files
+                     */
+                    if (
+                        args.path.includes(
+                            `${path.sep}.bcp-framework${path.sep}`
+                        )
+                    ) {
+                        return;
+                    }
+
+                    const relative =
+                        path.relative(
+                            rootDirectory,
+                            args.path
+                        );
+
+                    /*
+                     * ไม่ transform file
+                     * นอก application
+                     */
+                    if (
+                        relative.startsWith(
+                            ".."
+                        )
+                    ) {
+                        return;
+                    }
+
+                    const source =
+                        await fs.promises
+                            .readFile(
+                                args.path,
+                                "utf8"
+                            );
+
+                    const extension =
+                        path.extname(
+                            args.path
+                        );
+
+                    const isTypeScript =
+                        extension === ".ts" ||
+                        extension === ".tsx";
+
+                    const presets:
+                        any[] = [];
+
+                    /*
+                     * Babel 8
+                     *
+                     * ไม่ใช้:
+                     *
+                     * allowDeclareFields
+                     * allExtensions
+                     * isTSX
+                     */
+                    if (
+                        isTypeScript
+                    ) {
+                        presets.push([
+                            presetTypeScript,
+                        ]);
+                    }
+
+                    presets.push([
+                        presetReact,
+                        {
+                            runtime:
+                                "automatic",
+
+                            development:
+                                true,
+                        },
+                    ]);
+
+                    const result =
+                        await transformAsync(
+                            source,
+                            {
+                                filename:
+                                    args.path,
+
+                                babelrc:
+                                    false,
+
+                                configFile:
+                                    false,
+
+                                sourceType:
+                                    "module",
+
+                                presets,
+
+                                plugins: [
+                                    reactRefreshBabel,
+                                ],
+                            }
+                        );
+
+                    if (
+                        !result?.code
+                    ) {
+                        return;
+                    }
+
+                    const moduleId =
+                        path.relative(
+                            rootDirectory,
+                            args.path
+                        )
+                            .replace(
+                                /\\/g,
+                                "/"
+                            );
+
+                    const transformed =
+                        `
+const __bcpRefreshRuntime =
+  globalThis.__BCP_REFRESH_RUNTIME__;
+
+if (!__bcpRefreshRuntime) {
+  throw new Error(
+    "BCP Framework: React Refresh runtime is missing."
+  );
+}
+
+const $RefreshReg$ =
+  (type, id) => {
+    __bcpRefreshRuntime.register(
+      type,
+      ${JSON.stringify(moduleId)} + " " + id
+    );
+  };
+
+const $RefreshSig$ =
+  __bcpRefreshRuntime
+    .createSignatureFunctionForTransform;
+
+${result.code}
+            `.trim();
+
+                    return {
+                        contents:
+                            transformed,
+
+                        loader:
+                            "js",
+
+                        resolveDir:
+                            path.dirname(
+                                args.path
+                            ),
+                    };
+                }
+            );
+        },
+    };
+}
+
+/*
+ * =====================================
+ * File Utilities
+ * =====================================
+ */
+
+function collectFiles(
+    directory: string,
+    callback:
+        (
+            filePath: string
+        ) => void
+) {
+    const entries =
+        fs.readdirSync(
+            directory,
+            {
+                withFileTypes: true,
+            }
+        );
+
+    for (
+        const entry
+        of entries
+    ) {
+        const filePath =
+            path.join(
+                directory,
+                entry.name
+            );
+
+        if (
+            entry.isDirectory()
+        ) {
+            collectFiles(
+                filePath,
+                callback
+            );
+
+            continue;
+        }
+
+        callback(
+            filePath
+        );
+    }
+}
+
+/*
+ * =====================================
+ * Import Specifier
+ * =====================================
+ */
+
+function toImportSpecifier(
+    rootDirectory: string,
+    filePath: string
+): string {
+    let result =
+        path.relative(
+            rootDirectory,
+            filePath
+        );
+
+    result =
+        result.replace(
+            /\\/g,
+            "/"
+        );
+
+    if (
+        !result.startsWith(
+            "."
+        )
+    ) {
+        result =
+            `./${result}`;
+    }
+
+    return result;
+}
+
+/*
+ * =====================================
+ * Bundle Names
+ * =====================================
+ */
+
+function routeToBundleName(
+    pathname: string
+): string {
+    if (
+        pathname === "/"
+    ) {
+        return "index.js";
+    }
+
+    const name =
+        pathname
+            .slice(1)
+            .split("/")
+            .map(
+                sanitizeSegment
+            )
+            .join("__");
+
+    return `${name}.js`;
+}
+
+function sanitizeBundleId(
+    pathname: string
+): string {
+    if (
+        pathname === "/"
+    ) {
+        return "root";
+    }
+
+    return pathname
+        .slice(1)
+        .split("/")
+        .map(
+            sanitizeSegment
+        )
+        .join("-");
+}
+
+function sanitizeSegment(
+    segment: string
+): string {
+    const dynamicMatch =
+        /^\[([A-Za-z_][A-Za-z0-9_]*)\]$/.exec(
+            segment
+        );
+
+    if (
+        dynamicMatch
+    ) {
+        return (
+            `param-${dynamicMatch[1]}`
+        );
+    }
+
+    return segment.replace(
+        /[^A-Za-z0-9._-]/g,
+        "_"
+    );
+}