@nitronjs/framework 0.1.0

package/lib/Build/Manager.js

@@ -0,0 +1,1232 @@
+#!/usr/bin/env node
+import dotenv from "dotenv";
+import fs from "fs";
+import path from "path";
+import esbuild from "esbuild";
+import { parse } from "@babel/parser";
+import traverse from "@babel/traverse";
+import postcss from "postcss";
+import tailwindPostcss from "@tailwindcss/postcss";
+import Paths from "../Core/Paths.js";
+
+dotenv.config({ quiet: true });
+
+const COLORS = {
+    reset: "\x1b[0m",
+    dim: "\x1b[2m",
+    red: "\x1b[31m",
+    green: "\x1b[32m",
+    yellow: "\x1b[33m",
+    cyan: "\x1b[36m"
+};
+
+const CLIENT_HOOKS = new Set([
+    "useState",
+    "useEffect",
+    "useRef",
+    "useReducer",
+    "useLayoutEffect",
+    "useCallback",
+    "useMemo"
+]);
+
+const MAX_DEPTH = 50;
+
+function sanitizeName(name) {
+    return name.replace(/[^a-zA-Z0-9_$]/g, "_");
+}
+
+const JSX_RUNTIME = `
+import * as React from 'react';
+import * as OriginalJsx from '__react_jsx_original__';
+
+const CTX = Symbol.for('__nitron_view_context__');
+const MARK = Symbol.for('__nitron_client_component__');
+const UNSAFE_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+function getContext() {
+    return globalThis[CTX]?.getStore?.();
+}
+
+globalThis.csrf = () => getContext()?.csrf || '';
+
+globalThis.request = () => {
+    const ctx = getContext();
+    return ctx?.request || { params: {}, query: {}, url: '', method: 'GET', headers: {} };
+};
+
+const DepthContext = React.createContext(false);
+const componentCache = new WeakMap();
+
+function sanitizeProps(obj, seen = new WeakSet()) {
+    if (obj == null) return obj;
+    
+    const type = typeof obj;
+    if (type === 'function' || type === 'symbol') return undefined;
+    if (type === 'bigint') return obj.toString();
+    if (type !== 'object') return obj;
+    
+    if (seen.has(obj)) return undefined;
+    seen.add(obj);
+    
+    if (Array.isArray(obj)) {
+        return obj.map(item => {
+            const sanitized = sanitizeProps(item, seen);
+            return sanitized === undefined ? null : sanitized;
+        });
+    }
+    
+    if (obj instanceof Date) return obj.toISOString();
+    if (obj._attributes && typeof obj._attributes === 'object') {
+        return sanitizeProps(obj._attributes, seen);
+    }
+    if (typeof obj.toJSON === 'function') {
+        return sanitizeProps(obj.toJSON(), seen);
+    }
+    
+    const proto = Object.getPrototypeOf(obj);
+    if (proto !== Object.prototype && proto !== null) return undefined;
+    
+    const result = {};
+    for (const key of Object.keys(obj)) {
+        if (UNSAFE_KEYS.has(key)) continue;
+        const value = sanitizeProps(obj[key], seen);
+        if (value !== undefined) result[key] = value;
+    }
+    return result;
+}
+
+function wrapWithDepth(children) {
+    return OriginalJsx.jsx(DepthContext.Provider, { value: true, children });
+}
+
+function createIsland(Component, name) {
+    function IslandBoundary(props) {
+        if (React.useContext(DepthContext)) {
+            return OriginalJsx.jsx(Component, props);
+        }
+        
+        const id = React.useId();
+        const safeProps = sanitizeProps(props) || {};
+        
+        const ctx = getContext();
+        if (ctx) {
+            ctx.props = ctx.props || {};
+            ctx.props[id] = safeProps;
+        }
+        
+        return OriginalJsx.jsx('div', {
+            'data-cid': id,
+            'data-island': name,
+            children: wrapWithDepth(OriginalJsx.jsx(Component, props))
+        });
+    }
+    
+    IslandBoundary.displayName = 'Island(' + name + ')';
+    return IslandBoundary;
+}
+
+function getWrappedComponent(Component) {
+    if (!componentCache.has(Component)) {
+        const name = Component.displayName || Component.name || 'Anonymous';
+        componentCache.set(Component, createIsland(Component, name));
+    }
+    return componentCache.get(Component);
+}
+
+export function jsx(type, props, key) {
+    if (typeof type === 'function' && type[MARK]) {
+        return OriginalJsx.jsx(getWrappedComponent(type), props, key);
+    }
+    return OriginalJsx.jsx(type, props, key);
+}
+
+export function jsxs(type, props, key) {
+    if (typeof type === 'function' && type[MARK]) {
+        return OriginalJsx.jsx(getWrappedComponent(type), props, key);
+    }
+    return OriginalJsx.jsxs(type, props, key);
+}
+
+export const Fragment = OriginalJsx.Fragment;
+`;
+
+class Builder {
+    #isDev = process.env.APP_DEV === "true";
+    #traverse = traverse.default;
+    #manifest = {};
+    #paths;
+    #stats = { user: 0, framework: 0, islands: 0, css: 0 };
+    #cache = { imports: new Map(), css: new Map(), hydrationTemplate: null };
+
+    constructor() {
+        this.#paths = {
+            // User project paths
+            userViews: Paths.views,
+            userOutput: Paths.buildViews,
+            frameworkOutput: Paths.buildFrameworkViews,
+            cssInput: Paths.css,
+            cssOutput: Paths.publicCss,
+            jsOutput: Paths.publicJs,
+            jsxRuntime: Paths.jsxRuntime,
+            nitronTemp: Paths.nitronTemp,
+            // Framework paths
+            frameworkViews: Paths.frameworkViews,
+            templates: Paths.frameworkTemplates
+        };
+    }
+
+    async run(only = null) {
+        const startTime = Date.now();
+
+        try {
+            console.log(`\n${COLORS.cyan}⚡ NitronJS Build${COLORS.reset}\n`);
+
+            if (!only) {
+                this.#cleanOutputDirs();
+            }
+
+            this.#writeJsxRuntime();
+
+            await Promise.all([
+                (!only || only === "views") ? this.#buildViews() : null,
+                (!only || only === "css") ? this.#buildCss() : null
+            ]);
+
+            this.#cleanupTemp();
+            this.#printSummary(Date.now() - startTime);
+            return true;
+        } catch (error) {
+            this.#cleanupTemp();
+            console.log(`\n${COLORS.red}✖ Build failed: ${error.message}${COLORS.reset}\n`);
+            if (this.#isDev) console.error(error);
+            return false;
+        }
+    }
+
+    #printSummary(duration) {
+        const { user, framework, islands, css } = this.#stats;
+        const lines = [];
+
+        if (user || framework) {
+            const parts = [];
+            if (user) parts.push(`${user} user`);
+            if (framework) parts.push(`${framework} framework`);
+            lines.push(`  ${COLORS.green}✔${COLORS.reset} Views      ${parts.join(", ")}`);
+        }
+
+        if (islands) {
+            const plural = islands > 1 ? "s" : "";
+            lines.push(`  ${COLORS.green}✔${COLORS.reset} Hydration  ${islands} bundle${plural}`);
+        }
+
+        if (css) {
+            const plural = css > 1 ? "s" : "";
+            lines.push(`  ${COLORS.green}✔${COLORS.reset} CSS        ${css} stylesheet${plural}`);
+        }
+
+        console.log(lines.join("\n"));
+        console.log(`\n${COLORS.dim}Completed in ${duration}ms${COLORS.reset}\n`);
+    }
+
+    async #buildViews() {
+        const [, userBundle, frameworkBundle] = await Promise.all([
+            this.#buildVendor(),
+            this.#buildViewBundle("user", this.#paths.userViews, this.#paths.userOutput),
+            this.#buildViewBundle("framework", this.#paths.frameworkViews, this.#paths.frameworkOutput)
+        ]);
+
+        await this.#buildHydrationBundles(userBundle, frameworkBundle);
+        this.#writeManifest();
+    }
+
+    async #buildVendor() {
+        await esbuild.build({
+            entryPoints: [path.join(this.#paths.templates, "vendor.tsx")],
+            outfile: path.join(this.#paths.jsOutput, "vendor.js"),
+            bundle: true,
+            platform: "browser",
+            format: "iife",
+            target: "es2020",
+            sourcemap: this.#isDev,
+            minify: !this.#isDev,
+            jsx: "automatic"
+        });
+    }
+
+    async #buildViewBundle(namespace, srcDir, outDir) {
+        if (!fs.existsSync(srcDir)) {
+            return { entries: [], meta: new Map(), srcDir, namespace };
+        }
+
+        const { entries, meta } = this.#discoverEntries(srcDir);
+
+        if (!entries.length) {
+            return { entries: [], meta: new Map(), srcDir, namespace };
+        }
+
+        this.#addToManifest(entries, meta, srcDir, namespace);
+        await this.#runEsbuild(entries, outDir, { meta, outbase: srcDir });
+        await this.#postProcessMeta(entries, srcDir, outDir);
+
+        this.#stats[namespace === "user" ? "user" : "framework"] = entries.length;
+
+        return { entries, meta, srcDir, namespace };
+    }
+
+    async #postProcessMeta(entries, srcDir, outDir) {
+        const getExportedName = (specifier) => {
+            const match = specifier.match(/^.+\s+as\s+(\w+)$/);
+            return match ? match[1] : specifier.trim();
+        };
+
+        const processEntry = async (entry) => {
+            const relativePath = path.relative(srcDir, entry).replace(/\.tsx$/, ".js");
+            const outputFile = path.join(outDir, relativePath);
+
+            let code;
+            try {
+                code = await fs.promises.readFile(outputFile, "utf8");
+            } catch {
+                return;
+            }
+
+            if (code.includes("__mergedMeta__")) {
+                return;
+            }
+
+            const metaMatches = [...code.matchAll(/\b(?:var|let|const)\s+(Meta\d*)\s*=\s*\{/g)];
+            const metaNames = metaMatches.map(m => m[1]);
+
+            const exportMatches = [...code.matchAll(/export\s*\{([\s\S]*?)\};/g)];
+            if (!exportMatches.length) {
+                return;
+            }
+
+            const lastExport = exportMatches[exportMatches.length - 1];
+            const exportStart = lastExport.index;
+            const exportLength = lastExport[0].length;
+            const exportInner = lastExport[1];
+
+            const seenNames = new Set();
+            const exportItems = [];
+
+            for (const item of exportInner.split(",").map(s => s.trim()).filter(Boolean)) {
+                const exportedName = getExportedName(item);
+                if (!seenNames.has(exportedName)) {
+                    seenNames.add(exportedName);
+                    exportItems.push(item);
+                }
+            }
+
+            const hasMetaExport = seenNames.has("Meta");
+
+            if (metaNames.length >= 2) {
+                const mergeCode = `var __mergedMeta__=(()=>{var r={};[${metaNames.join(",")}].forEach(m=>{if(!m)return;Object.keys(m).forEach(k=>{if(k==='title'){var p=r.title,c=m.title;r.title=p&&typeof p==='object'&&p.template&&c?p.template.replace('%s',typeof c==='object'?c.default:c):c}else if(!(k in r))r[k]=m[k]})});return r})();\n`;
+
+                const finalItems = exportItems.filter(item => getExportedName(item) !== "Meta");
+                finalItems.unshift("__mergedMeta__ as Meta");
+
+                const newExport = `export {\n  ${finalItems.join(",\n  ")}\n};`;
+                code = code.slice(0, exportStart) + mergeCode + newExport + code.slice(exportStart + exportLength);
+
+                await fs.promises.writeFile(outputFile, code);
+                return;
+            }
+
+            if (metaNames.length === 1 && !hasMetaExport) {
+                exportItems.unshift(`${metaNames[0]} as Meta`);
+            }
+
+            const newExport = `export {\n  ${exportItems.join(",\n  ")}\n};`;
+            code = code.slice(0, exportStart) + newExport + code.slice(exportStart + exportLength);
+
+            await fs.promises.writeFile(outputFile, code);
+        };
+
+        await Promise.all(entries.map(processEntry));
+    }
+
+    async #buildHydrationBundles(userBundle, frameworkBundle) {
+        const hydrationFiles = [];
+
+        for (const bundle of [userBundle, frameworkBundle]) {
+            if (!bundle?.entries.length) continue;
+
+            for (const viewPath of bundle.entries) {
+                const clientComponents = this.#findClientComponents(viewPath, bundle.meta, new Set());
+
+                if (clientComponents.size) {
+                    const hydrationFile = this.#generateHydrationFile(
+                        viewPath,
+                        bundle.srcDir,
+                        clientComponents,
+                        bundle.meta,
+                        bundle.namespace
+                    );
+                    hydrationFiles.push(hydrationFile);
+                }
+            }
+        }
+
+        if (!hydrationFiles.length) {
+            return;
+        }
+
+        await this.#runEsbuild(hydrationFiles, this.#paths.jsOutput, {
+            platform: "browser",
+            target: "es2020",
+            outbase: path.join(Paths.project, ".nitron/hydration"),
+            external: ["react", "react-dom", "react-dom/client", "react/jsx-runtime"],
+            vendor: true,
+            serverFunctions: true
+        });
+
+        this.#stats.islands = hydrationFiles.length;
+    }
+
+    #findClientComponents(file, meta, seen, depth = 0) {
+        const result = new Set();
+
+        if (depth > MAX_DEPTH || seen.has(file)) {
+            return result;
+        }
+        seen.add(file);
+
+        const fileMeta = meta.get(file);
+        if (!fileMeta) {
+            return result;
+        }
+
+        if (fileMeta.isClient) {
+            result.add(file);
+        }
+
+        for (const importPath of fileMeta.imports) {
+            const resolvedPath = this.#resolveImport(file, importPath);
+
+            if (meta.has(resolvedPath)) {
+                const childComponents = this.#findClientComponents(resolvedPath, meta, seen, depth + 1);
+                for (const component of childComponents) {
+                    result.add(component);
+                }
+            }
+        }
+
+        return result;
+    }
+
+    #generateHydrationFile(viewPath, srcDir, clientComponents, meta, namespace) {
+        if (!this.#cache.hydrationTemplate) {
+            const templatePath = path.join(this.#paths.templates, "page-hydration.tsx");
+            this.#cache.hydrationTemplate = fs.readFileSync(templatePath, "utf8");
+        }
+
+        const viewRelative = path.relative(srcDir, viewPath).replace(/\.tsx$/, "").toLowerCase();
+        const outputDir = path.join(Paths.project, ".nitron/hydration", path.dirname(viewRelative));
+        const outputFile = path.join(outputDir, path.basename(viewRelative) + ".tsx");
+
+        fs.mkdirSync(outputDir, { recursive: true });
+
+        const imports = [];
+        const manifestEntries = [];
+        let index = 0;
+
+        for (const componentPath of clientComponents) {
+            const componentMeta = meta.get(componentPath);
+            if (!componentMeta) continue;
+
+            const baseName = path.basename(componentPath, ".tsx");
+            const relativePath = path.relative(outputDir, componentPath)
+                .replace(/\\/g, "/")
+                .replace(/\.tsx$/, "");
+
+            if (componentMeta.hasDefault) {
+                const importName = sanitizeName(baseName) + "_" + index++;
+                imports.push(`import ${importName} from "${relativePath}";`);
+                manifestEntries.push(`  "${baseName}": ${importName}`);
+            }
+
+            for (const namedExport of componentMeta.named || []) {
+                const importName = sanitizeName(namedExport) + "_" + index++;
+                imports.push(`import { ${namedExport} as ${importName} } from "${relativePath}";`);
+                manifestEntries.push(`  "${namedExport}": ${importName}`);
+            }
+        }
+
+        const code = this.#cache.hydrationTemplate
+            .replace("// __COMPONENT_IMPORTS__", imports.join("\n"))
+            .replace(
+                "// __COMPONENT_MANIFEST__",
+                `Object.assign(componentManifest, {\n${manifestEntries.join(",\n")}\n});`
+            );
+
+        fs.writeFileSync(outputFile, code);
+
+        const manifestKey = `${namespace}:${viewRelative.replace(/\\/g, "/")}`;
+        if (this.#manifest[manifestKey]) {
+            this.#manifest[manifestKey].hydrationScript = `/js/${viewRelative.replace(/\\/g, "/")}.js`;
+        }
+
+        return outputFile;
+    }
+
+    async #buildCss() {
+        if (!fs.existsSync(this.#paths.cssInput)) {
+            return;
+        }
+
+        const cssFiles = fs.readdirSync(this.#paths.cssInput).filter(f => f.endsWith(".css"));
+        if (!cssFiles.length) {
+            return;
+        }
+
+        await Promise.all(cssFiles.map(async (filename) => {
+            const filePath = path.join(this.#paths.cssInput, filename);
+            if (!this.#cache.css.has(filePath)) {
+                const content = await fs.promises.readFile(filePath, "utf8");
+                this.#cache.css.set(filePath, content);
+            }
+        }));
+
+        const hasTailwind = this.#detectTailwind();
+        const processor = hasTailwind ? postcss([tailwindPostcss()]) : null;
+
+        await Promise.all(cssFiles.map(filename => this.#processCss(filename, hasTailwind, processor)));
+
+        this.#stats.css = cssFiles.length;
+    }
+
+    async #runEsbuild(entries, outDir, options = {}) {
+        const plugins = [
+            this.#createCssStubPlugin(),
+            this.#createMarkerPlugin(options),
+            this.#createPathAliasPlugin()
+        ];
+
+        if (options.vendor) {
+            plugins.push(this.#createVendorGlobalsPlugin());
+            plugins.push(this.#createServerStubPlugin());
+        }
+
+        if (options.serverFunctions) {
+            plugins.push(this.#createServerFunctionsPlugin());
+        }
+
+        const isNode = (options.platform ?? "node") === "node";
+
+        const config = {
+            entryPoints: entries,
+            outdir: outDir,
+            outbase: options.outbase,
+            bundle: true,
+            platform: options.platform ?? "node",
+            format: "esm",
+            jsx: "automatic",
+            target: options.target ?? "node20",
+            sourcemap: this.#isDev,
+            minify: !this.#isDev,
+            external: options.external ?? ["react", "react-dom", "react-dom/server"],
+            plugins
+        };
+
+        if (isNode) {
+            config.packages = "external";
+            config.treeShaking = false;
+        }
+
+        if (options.platform !== "browser") {
+            config.alias = { "react/jsx-runtime": this.#paths.jsxRuntime };
+            plugins.push(this.#createOriginalJsxPlugin());
+        }
+
+        await esbuild.build(config);
+    }
+
+    #createPathAliasPlugin() {
+        const root = Paths.project;
+        return {
+            name: "path-alias",
+            setup: (build) => {
+                // Handle @/* alias -> ./app/* with high priority
+                // Using filter with higher specificity to run before packages: "external"
+                build.onResolve({ filter: /^@\// }, async (args) => {
+                    const relativePath = args.path.replace(/^@\//, "");
+                    const absolutePath = path.join(root, "app", relativePath);
+                    
+                    // Try with .js extension first, then without
+                    const extensions = [".js", ".ts", ".jsx", ".tsx", ""];
+                    for (const ext of extensions) {
+                        const fullPath = absolutePath + ext;
+                        if (fs.existsSync(fullPath)) {
+                            // Return with explicit namespace to ensure it's bundled
+                            return { path: fullPath, external: false };
+                        }
+                    }
+                    
+                    // If it's a directory, try index files
+                    if (fs.existsSync(absolutePath) && fs.statSync(absolutePath).isDirectory()) {
+                        for (const ext of [".js", ".ts", ".jsx", ".tsx"]) {
+                            const indexPath = path.join(absolutePath, "index" + ext);
+                            if (fs.existsSync(indexPath)) {
+                                return { path: indexPath, external: false };
+                            }
+                        }
+                    }
+                    
+                    return { path: absolutePath + ".js", external: false };
+                });
+            }
+        };
+    }
+
+    #createOriginalJsxPlugin() {
+        return {
+            name: "original-jsx",
+            setup: (build) => {
+                build.onResolve({ filter: /^__react_jsx_original__$/ }, () => ({
+                    path: "react/jsx-runtime",
+                    external: true
+                }));
+            }
+        };
+    }
+
+    #createVendorGlobalsPlugin() {
+        const escapeRegex = (str) => str.replace(/[.*+?^${}()|[\]\\\/]/g, "\\$&");
+
+        const packages = {
+            "react": "__NITRON_REACT__",
+            "react-dom": "__NITRON_REACT_DOM__",
+            "react-dom/client": "__NITRON_REACT_DOM_CLIENT__",
+            "react/jsx-runtime": "__NITRON_JSX_RUNTIME__"
+        };
+
+        const patterns = Object.entries(packages).map(([pkg, global]) => ({
+            filter: new RegExp(`^${escapeRegex(pkg)}$`),
+            pkg,
+            global
+        }));
+
+        return {
+            name: "vendor-globals",
+            setup: (build) => {
+                for (const { filter, pkg, global } of patterns) {
+                    build.onResolve({ filter }, () => ({
+                        path: pkg,
+                        namespace: "vendor-global"
+                    }));
+
+                    build.onLoad({ filter, namespace: "vendor-global" }, () => ({
+                        contents: `module.exports = window.${global};`,
+                        loader: "js"
+                    }));
+                }
+            }
+        };
+    }
+
+    #createServerStubPlugin() {
+        return {
+            name: "server-stub",
+            setup: (build) => {
+                build.onResolve({ filter: /lib\/Storage\.js$/ }, (args) => ({
+                    path: args.path,
+                    namespace: "storage-stub"
+                }));
+
+                build.onLoad({ filter: /.*/, namespace: "storage-stub" }, () => ({
+                    contents: `export default { url: p => '/storage/' + (p.startsWith('/') ? p.slice(1) : p) };`,
+                    loader: "js"
+                }));
+
+                build.onResolve(
+                    { filter: /lib\/(DB|Mail|Log|Hash|Environment|Server|Model|Validator)\.js$/ },
+                    (args) => ({ path: args.path, namespace: "server-only" })
+                );
+
+                build.onLoad({ filter: /.*/, namespace: "server-only" }, (args) => {
+                    const moduleName = args.path.split("/").pop()?.replace(".js", "") || "Module";
+                    return {
+                        contents: `const err = () => { throw new Error("${moduleName} is server-only") }; export default new Proxy({}, { get: err, apply: err });`,
+                        loader: "js"
+                    };
+                });
+            }
+        };
+    }
+
+    #createServerFunctionsPlugin() {
+        return {
+            name: "server-functions",
+            setup: (build) => {
+                build.onLoad({ filter: /\.(tsx?|jsx?)$/ }, async (args) => {
+                    if (args.path.includes("node_modules")) {
+                        return null;
+                    }
+
+                    let source = await fs.promises.readFile(args.path, "utf8");
+
+                    if (!source.includes("csrf(") && !source.includes("route(")) {
+                        return null;
+                    }
+
+                    source = source.replace(
+                        /\bcsrf\s*\(\s*\)/g,
+                        "window.__NITRON_RUNTIME__.csrf"
+                    );
+
+                    source = source.replace(
+                        /\broute\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
+                        (_, routeName) => `window.__NITRON_RUNTIME__.routes["${routeName}"]`
+                    );
+
+                    const ext = args.path.split(".").pop();
+                    const loader = ext === "tsx" ? "tsx" : ext === "ts" ? "ts" : ext === "jsx" ? "jsx" : "js";
+
+                    return { contents: source, loader };
+                });
+            }
+        };
+    }
+
+    #createCssStubPlugin() {
+        return {
+            name: "css-stub",
+            setup: (build) => {
+                build.onResolve({ filter: /\.css$/ }, (args) => ({
+                    path: args.path,
+                    namespace: "css-stub"
+                }));
+
+                build.onLoad({ filter: /.*/, namespace: "css-stub" }, () => ({
+                    contents: "",
+                    loader: "js"
+                }));
+            }
+        };
+    }
+
+    #createMarkerPlugin(options) {
+        const isDev = this.#isDev;
+
+        return {
+            name: "client-marker",
+            setup: (build) => {
+                if (options.platform === "browser") {
+                    return;
+                }
+
+                build.onLoad({ filter: /\.tsx$/ }, async (args) => {
+                    const source = await fs.promises.readFile(args.path, "utf8");
+
+                    if (!/^\s*["']use client["']/.test(source.slice(0, 50))) {
+                        return null;
+                    }
+
+                    let ast;
+                    try {
+                        ast = parse(source, {
+                            sourceType: "module",
+                            plugins: ["typescript", "jsx"]
+                        });
+                    } catch {
+                        if (isDev) {
+                            console.warn(`${COLORS.yellow}⚠ Parse: ${args.path}${COLORS.reset}`);
+                        }
+                        return null;
+                    }
+
+                    const exports = this.#findExports(ast);
+                    if (!exports.length) {
+                        return null;
+                    }
+
+                    const symbolCode = `Symbol.for('__nitron_client_component__')`;
+                    let additionalCode = "\n";
+
+                    for (const exp of exports) {
+                        additionalCode += `try { Object.defineProperty(${exp.name}, ${symbolCode}, { value: true }); ${exp.name}.displayName = "${exp.name}"; } catch {}\n`;
+                    }
+
+                    return { contents: source + additionalCode, loader: "tsx" };
+                });
+            }
+        };
+    }
+
+    async #processCss(filename, hasTailwind, processor) {
+        const inputPath = path.join(this.#paths.cssInput, filename);
+        const outputPath = path.join(this.#paths.cssOutput, filename);
+
+        await fs.promises.mkdir(path.dirname(outputPath), { recursive: true });
+
+        let content = this.#cache.css.get(inputPath);
+        if (!content) {
+            content = await fs.promises.readFile(inputPath, "utf8");
+            this.#cache.css.set(inputPath, content);
+        }
+
+        if (!hasTailwind) {
+            await fs.promises.writeFile(outputPath, content);
+            return;
+        }
+
+        const result = await processor.process(content, {
+            from: inputPath,
+            to: outputPath,
+            map: this.#isDev ? { inline: false } : false
+        });
+
+        await fs.promises.writeFile(outputPath, result.css);
+
+        if (result.map) {
+            await fs.promises.writeFile(`${outputPath}.map`, result.map.toString());
+        }
+    }
+
+    #detectTailwind() {
+        if (!fs.existsSync(this.#paths.cssInput)) {
+            return false;
+        }
+
+        const tailwindPattern = /@(import\s+["']tailwindcss["']|tailwind\s+(base|components|utilities))/;
+
+        for (const filename of fs.readdirSync(this.#paths.cssInput).filter(f => f.endsWith(".css"))) {
+            const filePath = path.join(this.#paths.cssInput, filename);
+
+            let content = this.#cache.css.get(filePath);
+            if (!content) {
+                content = fs.readFileSync(filePath, "utf8");
+                this.#cache.css.set(filePath, content);
+            }
+
+            if (tailwindPattern.test(content)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    #discoverEntries(baseDir) {
+        if (!fs.existsSync(baseDir)) {
+            return { entries: [], meta: new Map() };
+        }
+
+        const files = this.#findTsxFiles(baseDir);
+        const { graph, imported, importedBy } = this.#buildDependencyGraph(files);
+
+        const entries = [...graph.entries()]
+            .filter(([file, meta]) => !imported.has(file) && meta.hasDefault && meta.jsx)
+            .map(([file]) => file);
+
+        this.#validateGraph(graph, entries, importedBy);
+
+        return { entries, meta: graph };
+    }
+
+    #findTsxFiles(dir, result = []) {
+        if (!fs.existsSync(dir)) {
+            return result;
+        }
+
+        for (const item of fs.readdirSync(dir)) {
+            const fullPath = path.join(dir, item);
+            const stat = fs.lstatSync(fullPath);
+
+            if (stat.isSymbolicLink()) {
+                continue;
+            }
+
+            if (stat.isDirectory()) {
+                this.#findTsxFiles(fullPath, result);
+            } else if (fullPath.endsWith(".tsx")) {
+                result.push(fullPath);
+            }
+        }
+
+        return result;
+    }
+
+    #buildDependencyGraph(files) {
+        const graph = new Map();
+        const imported = new Set();
+        const importedBy = new Map();
+
+        for (const file of files) {
+            const meta = this.#analyzeFile(file);
+            graph.set(file, meta);
+
+            for (const importPath of meta.imports) {
+                const resolvedPath = this.#resolveImport(file, importPath);
+
+                if (this.#isInRoot(resolvedPath)) {
+                    imported.add(resolvedPath);
+
+                    if (!importedBy.has(resolvedPath)) {
+                        importedBy.set(resolvedPath, []);
+                    }
+                    importedBy.get(resolvedPath).push(file);
+                }
+            }
+        }
+
+        return { graph, imported, importedBy };
+    }
+
+    #analyzeFile(filePath) {
+        const source = fs.readFileSync(filePath, "utf8");
+
+        let ast;
+        try {
+            ast = parse(source, {
+                sourceType: "module",
+                plugins: ["typescript", "jsx"]
+            });
+        } catch {
+            return {
+                imports: [],
+                css: [],
+                hasDefault: false,
+                named: [],
+                jsx: false,
+                needsClient: false,
+                isClient: false
+            };
+        }
+
+        const isClient = ast.program.directives?.some(d => d.value?.value === "use client");
+
+        const meta = {
+            imports: new Set(),
+            css: new Set(),
+            hasDefault: false,
+            named: [],
+            jsx: false,
+            needsClient: false,
+            isClient,
+            reactNamespace: null
+        };
+
+        this.#traverse(ast, {
+            ImportDeclaration: (p) => {
+                const source = p.node.source.value;
+
+                if (source.startsWith(".")) {
+                    meta.imports.add(source);
+                }
+
+                if (source.endsWith(".css")) {
+                    const resolved = path.resolve(path.dirname(filePath), source);
+                    if (resolved.startsWith(Paths.project)) {
+                        meta.css.add(resolved);
+                    }
+                }
+
+                if (source === "react") {
+                    for (const specifier of p.node.specifiers) {
+                        if (specifier.type === "ImportSpecifier" && CLIENT_HOOKS.has(specifier.imported.name)) {
+                            meta.needsClient = true;
+                        }
+                        if (specifier.type === "ImportNamespaceSpecifier" || specifier.type === "ImportDefaultSpecifier") {
+                            meta.reactNamespace = specifier.local.name;
+                        }
+                    }
+                }
+            },
+
+            MemberExpression: (p) => {
+                if (!meta.needsClient &&
+                    p.node.object.name === meta.reactNamespace &&
+                    CLIENT_HOOKS.has(p.node.property.name)) {
+                    meta.needsClient = true;
+                }
+            },
+
+            CallExpression: (p) => {
+                if (!meta.needsClient &&
+                    p.node.callee.type === "Identifier" &&
+                    /^use[A-Z]/.test(p.node.callee.name)) {
+                    meta.needsClient = true;
+                }
+            },
+
+            ExportNamedDeclaration: (p) => this.#extractNamedExports(p, meta),
+            ExportDefaultDeclaration: () => { meta.hasDefault = true; },
+            JSXElement: () => { meta.jsx = true; },
+            JSXFragment: () => { meta.jsx = true; }
+        });
+
+        if (meta.needsClient && !meta.isClient) {
+            throw this.#createError('Missing "use client"', {
+                File: path.relative(Paths.project, filePath),
+                Fix: 'Add "use client" at top'
+            });
+        }
+
+        return {
+            ...meta,
+            imports: [...meta.imports],
+            css: [...meta.css]
+        };
+    }
+
+    #extractNamedExports(path, meta) {
+        const declaration = path.node.declaration;
+
+        if (declaration?.type === "VariableDeclaration") {
+            for (const decl of declaration.declarations) {
+                if (decl.id.type === "Identifier" && decl.init?.type === "ArrowFunctionExpression") {
+                    meta.named.push(decl.id.name);
+                }
+            }
+        }
+
+        if (declaration?.type === "FunctionDeclaration" && declaration.id?.name) {
+            meta.named.push(declaration.id.name);
+        }
+    }
+
+    #findExports(ast) {
+        const exports = [];
+
+        this.#traverse(ast, {
+            ExportDefaultDeclaration: (p) => {
+                const declaration = p.node.declaration;
+                let name;
+
+                if (declaration.type === "Identifier") {
+                    name = declaration.name;
+                } else if (declaration.type === "FunctionDeclaration" && declaration.id?.name) {
+                    name = declaration.id.name;
+                } else if (declaration.type === "CallExpression" &&
+                    ["memo", "forwardRef", "lazy"].includes(declaration.callee?.name)) {
+                    name = declaration.arguments[0]?.name || "__default__";
+                } else {
+                    name = "__default__";
+                }
+
+                exports.push({ name, isDefault: true });
+            },
+
+            ExportNamedDeclaration: (p) => {
+                for (const specifier of p.node.specifiers || []) {
+                    if (specifier.type === "ExportSpecifier") {
+                        const name = specifier.exported.name === "default"
+                            ? specifier.local.name
+                            : specifier.exported.name;
+                        exports.push({
+                            name,
+                            isDefault: specifier.exported.name === "default"
+                        });
+                    }
+                }
+
+                const declaration = p.node.declaration;
+
+                if (declaration?.type === "FunctionDeclaration" && declaration.id?.name) {
+                    exports.push({ name: declaration.id.name, isDefault: false });
+                }
+
+                if (declaration?.type === "VariableDeclaration") {
+                    for (const decl of declaration.declarations) {
+                        if (decl.id.type === "Identifier" && decl.init?.type === "ArrowFunctionExpression") {
+                            exports.push({ name: decl.id.name, isDefault: false });
+                        }
+                    }
+                }
+            }
+        });
+
+        return exports;
+    }
+
+    #validateGraph(graph, entries, importedBy) {
+        const entrySet = new Set(entries);
+        const relativePath = (p) => path.relative(Paths.project, p);
+
+        for (const [filePath, meta] of graph.entries()) {
+            if (!meta.isClient) {
+                continue;
+            }
+
+            if (entrySet.has(filePath) && meta.hasDefault && meta.jsx) {
+                const importers = importedBy.get(filePath);
+                if (importers?.length) {
+                    throw this.#createError("Client Entry Imported", {
+                        Entry: relativePath(filePath),
+                        By: relativePath(importers[0]),
+                        Fix: "Use as island"
+                    });
+                }
+            }
+
+            // Next.js pattern: Client component cannot import server component
+            // Server component can render client component as children
+            for (const importPath of meta.imports) {
+                const resolvedPath = this.#resolveImport(filePath, importPath);
+                const resolvedMeta = graph.get(resolvedPath);
+
+                // If importing a non-client component (server component)
+                if (resolvedMeta && !resolvedMeta.isClient) {
+                    throw this.#createError("Boundary Violation", {
+                        Client: relativePath(filePath),
+                        Server: relativePath(resolvedPath),
+                        Fix: `Server components cannot be imported into client components. Use composition pattern: render "${path.basename(resolvedPath, ".tsx")}" as a parent and pass client component as children.`
+                    });
+                }
+            }
+        }
+    }
+
+    #addToManifest(entries, meta, baseDir, namespace) {
+        for (const file of entries) {
+            const fileMeta = meta.get(file);
+            const viewPath = path.relative(baseDir, file)
+                .replace(/\.tsx$/, "")
+                .toLowerCase()
+                .replace(/\\/g, "/");
+
+            const key = `${namespace}:${viewPath}`;
+
+            if (this.#manifest[key]) {
+                throw new Error(`Duplicate: ${key}`);
+            }
+
+            const cssFiles = [...this.#collectCss(file, meta, new Set())]
+                .map(cssPath => `/css/${path.basename(cssPath)}`);
+
+            this.#manifest[key] = {
+                css: cssFiles,
+                hydrationScript: null
+            };
+        }
+    }
+
+    #writeManifest() {
+        const manifestPath = path.join(Paths.project, "build", "manifest.json");
+        fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+        fs.writeFileSync(manifestPath, JSON.stringify(this.#manifest, null, 2));
+    }
+
+    #collectCss(file, meta, seen, depth = 0) {
+        if (depth > MAX_DEPTH || seen.has(file)) {
+            return new Set();
+        }
+        seen.add(file);
+
+        const fileMeta = meta.get(file);
+        if (!fileMeta) {
+            return new Set();
+        }
+
+        const result = new Set(fileMeta.css);
+
+        for (const importPath of fileMeta.imports) {
+            const resolvedPath = this.#resolveImport(file, importPath);
+
+            if (meta.has(resolvedPath)) {
+                const childCss = this.#collectCss(resolvedPath, meta, seen, depth + 1);
+                for (const cssPath of childCss) {
+                    result.add(cssPath);
+                }
+            }
+        }
+
+        return result;
+    }
+
+    #resolveImport(fromFile, relativePath) {
+        const cacheKey = `${fromFile}|${relativePath}`;
+        const cached = this.#cache.imports.get(cacheKey);
+
+        if (cached) {
+            return cached;
+        }
+
+        const resolved = path.resolve(path.dirname(fromFile), relativePath);
+
+        if (!this.#isInRoot(resolved)) {
+            throw this.#createError("Path Traversal", {
+                Import: relativePath,
+                Outside: resolved
+            });
+        }
+
+        const extensions = [".tsx", ".ts", ".jsx", ".js", "/index.tsx", "/index.ts", ""];
+
+        for (const ext of extensions) {
+            const fullPath = resolved + ext;
+
+            if (ext === "" && fs.existsSync(fullPath) && fs.statSync(fullPath).isFile()) {
+                this.#cache.imports.set(cacheKey, fullPath);
+                return fullPath;
+            }
+
+            if (ext && fs.existsSync(fullPath)) {
+                this.#cache.imports.set(cacheKey, fullPath);
+                return fullPath;
+            }
+        }
+
+        this.#cache.imports.set(cacheKey, resolved);
+        return resolved;
+    }
+
+    #isInRoot(filePath) {
+        const normalized = path.normalize(filePath);
+        const projectNormalized = path.normalize(Paths.project);
+        const frameworkNormalized = path.normalize(Paths.framework);
+        
+        // Allow both project paths and framework paths
+        return normalized.startsWith(projectNormalized + path.sep) || 
+               normalized === projectNormalized ||
+               normalized.startsWith(frameworkNormalized + path.sep) ||
+               normalized === frameworkNormalized;
+    }
+
+    #writeJsxRuntime() {
+        fs.mkdirSync(path.dirname(this.#paths.jsxRuntime), { recursive: true });
+        fs.writeFileSync(this.#paths.jsxRuntime, JSX_RUNTIME);
+    }
+
+    #cleanOutputDirs() {
+        const dirsToClean = [
+            this.#paths.cssOutput,
+            this.#paths.jsOutput,
+            this.#paths.nitronTemp
+        ];
+
+        for (const dir of dirsToClean) {
+            if (!dir.startsWith(Paths.project)) {
+                throw new Error(`Unsafe path: ${dir}`);
+            }
+
+            if (fs.existsSync(dir)) {
+                fs.rmSync(dir, { recursive: true, force: true });
+            }
+        }
+    }
+
+    #cleanupTemp() {
+        if (fs.existsSync(this.#paths.nitronTemp)) {
+            if (!this.#paths.nitronTemp.startsWith(Paths.project)) {
+                throw new Error(`Unsafe path: ${this.#paths.nitronTemp}`);
+            }
+            fs.rmSync(this.#paths.nitronTemp, { recursive: true, force: true });
+        }
+    }
+
+    #createError(title, details = {}) {
+        let message = `\n${COLORS.red}✖ ${title}${COLORS.reset}\n\n`;
+
+        for (const [key, value] of Object.entries(details)) {
+            message += `  ${key}: ${COLORS.yellow}${value}${COLORS.reset}\n`;
+        }
+
+        return new Error(message);
+    }
+}
+
+export default Builder;