@nitronjs/framework 0.2.26 → 0.3.0

package/lib/Build/Manager.js

@@ -10,17 +10,19 @@ import Layout from "../View/Layout.js";
 import JSX_RUNTIME from "./jsxRuntime.js";
 import FileAnalyzer from "./FileAnalyzer.js";
 import CssBuilder from "./CssBuilder.js";
-import HydrationBuilder from "./HydrationBuilder.js";
 import {
     createPathAliasPlugin,
     createOriginalJsxPlugin,
     createVendorGlobalsPlugin,
     createServerFunctionsPlugin,
     createCssStubPlugin,
-    createMarkerPlugin,
-    createServerModuleBlockerPlugin
+    createServerModuleBlockerPlugin,
+    createClientReferencePlugin,
+    createPropFilterPlugin
 } from "./plugins.js";
 import { transformFile as factoryTransform } from "./FactoryTransform.js";
+import PropUsageAnalyzer from "./PropUsageAnalyzer.js";
+import EffectivePropUsage from "./EffectivePropUsage.js";
 import COLORS from "./colors.js";
 
 dotenv.config({ quiet: true });
@@ -43,21 +45,21 @@ class Builder {
         css: new Map(),
         cssHashes: new Map(),
         viewHashes: new Map(),
-        hydrationTemplate: null,
-        hydrationTemplateDev: null,
         vendorBuilt: false,
         spaBuilt: false,
         hmrBuilt: false,
+        rscConsumerBuilt: false,
         tailwindProcessor: null,
         viewsChanged: false,
         fileMeta: new Map(),
-        fileHashes: new Map()
+        fileHashes: new Map(),
+        propAnalysis: new Map()
     };
     #diskCachePath = path.join(Paths.nitronTemp, "build-cache.json");
     #changedFiles = new Set();
+    #devBuiltOnce = false;
     #analyzer;
     #cssBuilder;
-    #hydrationBuilder;
 
     constructor() {
         this.#paths = {
@@ -74,8 +76,7 @@ class Builder {
         };
 
         this.#analyzer = new FileAnalyzer(this.#cache);
-        this.#cssBuilder = new CssBuilder(this.#cache, this.#isDev, this.#paths.cssInput, this.#paths.cssOutput);
-        this.#hydrationBuilder = new HydrationBuilder(this.#cache, this.#isDev, this.#paths.templates, this.#analyzer);
+        this.#cssBuilder = new CssBuilder(this.#cache, this.#paths.cssInput, this.#paths.cssOutput);
     }
 
     /**
@@ -96,7 +97,7 @@ class Builder {
         try {
             if (this.#isDev) this.#loadDiskCache();
             if (!silent) console.log(`\n${COLORS.cyan}⚡ NitronJS Build${COLORS.reset}\n`);
-            if (!only) this.#cleanOutputDirs();
+            if (!only && !(this.#isDev && this.#devBuiltOnce)) this.#cleanOutputDirs();
 
             this.#cache.viewsChanged = false;
             this.#writeJsxRuntime();
@@ -104,7 +105,10 @@ class Builder {
             if (!only || only === "views") await this.#buildViews();
             if (!only || only === "css") await this.#buildCss();
 
-            if (this.#isDev) this.#saveDiskCache();
+            if (this.#isDev) {
+                this.#devBuiltOnce = true;
+                this.#saveDiskCache();
+            }
             this.#cleanupTemp();
             if (!silent) this.#printSummary(Date.now() - startTime);
 
@@ -116,7 +120,8 @@ class Builder {
                 time: Date.now() - startTime
             };
         } catch (error) {
-            this.#cleanupTemp();
+            try { this.#cleanupTemp(); }
+            catch {}
 
             if (!silent) {
                 console.log(this.#formatBuildError(error));
@@ -133,8 +138,8 @@ class Builder {
 
                 if (data.fileMeta) {
                     for (const [key, value] of Object.entries(data.fileMeta)) {
-                        value.imports = new Set(value.imports || []);
-                        value.css = new Set(value.css || []);
+                        value.imports = value.imports || [];
+                        value.css = value.css || [];
                         this.#cache.fileMeta.set(key, value);
                     }
                 }
@@ -153,6 +158,11 @@ class Builder {
                         this.#cache.cssHashes.set(key, value);
                     }
                 }
+                if (data.propAnalysis) {
+                    for (const [key, value] of Object.entries(data.propAnalysis)) {
+                        this.#cache.propAnalysis.set(key, value);
+                    }
+                }
             }
         } catch {}
     }
@@ -168,10 +178,12 @@ class Builder {
                 fileMeta: {},
                 fileHashes: {},
                 viewHashes: {},
-                cssHashes: {}
+                cssHashes: {},
+                propAnalysis: {}
             };
 
             for (const [key, value] of this.#cache.fileMeta) {
+                if (!fs.existsSync(key)) continue;
                 data.fileMeta[key] = {
                     ...value,
                     imports: Array.from(value.imports || []),
@@ -179,16 +191,30 @@ class Builder {
                 };
             }
             for (const [key, value] of this.#cache.fileHashes) {
+                if (!fs.existsSync(key)) continue;
                 data.fileHashes[key] = value;
             }
             for (const [key, value] of this.#cache.viewHashes) {
+                const filePath = key.endsWith(":mtime") ? key.slice(0, -6) : key;
+                if (!fs.existsSync(filePath)) continue;
                 data.viewHashes[key] = value;
             }
             for (const [key, value] of this.#cache.cssHashes) {
+                if (!fs.existsSync(key)) continue;
                 data.cssHashes[key] = value;
             }
+            for (const [key, value] of this.#cache.propAnalysis) {
+                if (!fs.existsSync(key)) continue;
+                data.propAnalysis[key] = value;
+            }
 
-            fs.writeFileSync(this.#diskCachePath, JSON.stringify(data));
+            const tmpPath = this.#diskCachePath + ".tmp";
+            fs.writeFileSync(tmpPath, JSON.stringify(data));
+
+            try { fs.renameSync(tmpPath, this.#diskCachePath); }
+            catch {
+                fs.writeFileSync(this.#diskCachePath, JSON.stringify(data));
+            }
         } catch {}
     }
 
@@ -218,10 +244,11 @@ class Builder {
     }
 
     async #buildViews() {
-        const [, , , userBundle, frameworkBundle] = await Promise.all([
+        const [, , , , userBundle, frameworkBundle] = await Promise.all([
             this.#buildVendor(),
             this.#buildSpaRuntime(),
             this.#buildHmrClient(),
+            this.#buildRscConsumer(),
             this.#buildViewBundle("user", this.#paths.userViews, this.#paths.userOutput),
             this.#buildViewBundle("framework", this.#paths.frameworkViews, this.#paths.frameworkOutput)
         ]);
@@ -231,19 +258,27 @@ class Builder {
             ...(frameworkBundle.changedFiles || [])
         ]);
 
+        // Include changed client component sources so their hydration bundles rebuild
+        for (const bundle of [userBundle, frameworkBundle]) {
+            if (!bundle?.changedSources) continue;
+
+            for (const file of bundle.changedSources) {
+                const fileMeta = bundle.meta?.get(file);
+                if (fileMeta?.isClient) changedViews.add(file);
+            }
+        }
+
         for (const file of changedViews) {
             this.#changedFiles.add(file);
         }
 
-        const isFirstBuild = changedViews.size === 0 &&
-            (userBundle.entries.length > 0 || frameworkBundle.entries.length > 0);
-
-        await this.#buildHydrationBundles(
+        const clientComponents = await this.#buildClientComponents(
             userBundle,
             frameworkBundle,
-            isFirstBuild ? null : (changedViews.size > 0 ? changedViews : null)
+            changedViews
         );
 
+        this.#writeClientManifest(clientComponents);
         this.#writeManifest();
     }
 
@@ -304,36 +339,92 @@ class Builder {
         this.#cache.spaBuilt = true;
     }
 
+    async #buildRscConsumer() {
+        const outfile = path.join(this.#paths.jsOutput, "rsc-consumer.js");
+        if (this.#cache.rscConsumerBuilt && fs.existsSync(outfile)) return;
+
+        const consumerFile = path.join(this.#paths.templates, "rsc-consumer.tsx");
+
+        await esbuild.build({
+            entryPoints: [consumerFile],
+            outfile,
+            bundle: true,
+            platform: "browser",
+            format: "iife",
+            target: "es2020",
+            sourcemap: this.#isDev,
+            minify: !this.#isDev,
+            keepNames: true,
+            jsx: "automatic",
+            plugins: [
+                createVendorGlobalsPlugin(),
+                createCssStubPlugin()
+            ]
+        });
+        this.#cache.rscConsumerBuilt = true;
+    }
+
     async #buildViewBundle(namespace, srcDir, outDir) {
         if (!fs.existsSync(srcDir)) {
-            return { entries: [], layouts: [], meta: new Map(), srcDir, namespace, changedFiles: [] };
+            return { entries: [], layouts: [], meta: new Map(), srcDir, namespace, changedFiles: [], changedSources: new Set() };
         }
 
-        const { entries, layouts, meta } = this.#analyzer.discoverEntries(srcDir);
+        const { entries, layouts, meta, importedBy } = this.#analyzer.discoverEntries(srcDir);
 
         if (!entries.length && !layouts.length) {
-            return { entries: [], layouts: [], meta: new Map(), srcDir, namespace, changedFiles: [] };
+            return { entries: [], layouts: [], meta: new Map(), srcDir, namespace, changedFiles: [], changedSources: new Set() };
         }
 
-        this.#addToManifest(entries, layouts, meta, srcDir, namespace);
+        // Pre-scan: compute effective prop usage for server→client boundary filtering.
+        // Must run before addToManifest so manifest gets effective (forward-aware) usage.
+        const { effectiveMap, clientPathSet } = this.#preScanPropUsage(meta);
+
+        this.#addToManifest(entries, layouts, meta, srcDir, namespace, effectiveMap);
 
         const allFiles = [...entries, ...layouts];
-        const changedFiles = [];
+        const entryLayoutSet = new Set(allFiles);
+        const changedSources = new Set();
+
+        await Promise.all([...meta.keys()].map(async (file) => {
+            const stat = await fs.promises.stat(file);
+            const mtimeKey = file + ":mtime";
+            const cachedMtime = this.#cache.viewHashes.get(mtimeKey);
+
+            if (cachedMtime === stat.mtimeMs && this.#cache.viewHashes.has(file)) {
+                return;
+            }
 
-        for (const file of allFiles) {
             const content = await fs.promises.readFile(file, "utf8");
             const hash = crypto.createHash("md5").update(content).digest("hex");
             const cachedHash = this.#cache.viewHashes.get(file);
 
+            this.#cache.viewHashes.set(mtimeKey, stat.mtimeMs);
+
             if (cachedHash !== hash) {
                 this.#cache.viewHashes.set(file, hash);
-                changedFiles.push(file);
+                changedSources.add(file);
+            }
+        }));
+
+        const filesToBuild = new Set();
+
+        for (const file of changedSources) {
+            if (entryLayoutSet.has(file)) {
+                filesToBuild.add(file);
+            }
+
+            for (const dep of this.#getTransitiveDependents(file, importedBy)) {
+                if (entryLayoutSet.has(dep)) {
+                    filesToBuild.add(dep);
+                }
             }
         }
 
+        const changedFiles = [...filesToBuild];
+
         if (changedFiles.length) {
             this.#cache.viewsChanged = true;
-            await this.#runEsbuild(changedFiles, outDir, { meta, outbase: srcDir });
+            await this.#runEsbuild(changedFiles, outDir, { meta, outbase: srcDir, effectiveMap, clientPaths: clientPathSet });
             await this.#postProcessMeta(changedFiles, srcDir, outDir);
 
             for (const entry of changedFiles) {
@@ -344,7 +435,7 @@ class Builder {
 
         this.#stats[namespace === "user" ? "user" : "framework"] = entries.length;
 
-        return { entries, layouts, meta, srcDir, namespace, changedFiles };
+        return { entries, layouts, meta, srcDir, namespace, changedFiles, changedSources };
     }
 
     async #postProcessMeta(entries, srcDir, outDir) {
@@ -420,43 +511,122 @@ class Builder {
         await Promise.all(entries.map(processEntry));
     }
 
-    async #buildHydrationBundles(userBundle, frameworkBundle, changedViews = null) {
-        const hydrationFiles = await this.#hydrationBuilder.build(
-            userBundle,
-            frameworkBundle,
-            this.#manifest,
-            changedViews
-        );
+    async #buildClientComponents(userBundle, frameworkBundle, changedViews = null) {
+        const clientFiles = [];
 
-        if (!hydrationFiles.length) {
-            return;
+        for (const bundle of [userBundle, frameworkBundle]) {
+            if (!bundle?.meta) continue;
+
+            for (const [filePath, fileMeta] of bundle.meta.entries()) {
+                if (!fileMeta.isClient) continue;
+
+                const relative = path.relative(bundle.srcDir, filePath)
+                    .replace(/\.tsx$/, ".js")
+                    .replace(/\\/g, "/");
+
+                const chunkFile = "js/" + relative;
+                const outputPath = path.join(this.#paths.jsOutput, relative);
+                const needsRebuild = !changedViews || changedViews.has(filePath);
+
+                clientFiles.push({
+                    sourcePath: filePath,
+                    srcDir: bundle.srcDir,
+                    chunkId: relative.replace(/\.js$/, ""),
+                    chunkFile,
+                    outputPath,
+                    needsRebuild
+                });
+            }
         }
 
-        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
-        });
+        const toBuild = clientFiles.filter(c => c.needsRebuild || !fs.existsSync(c.outputPath));
+
+        if (toBuild.length) {
+            const srcDirs = new Set(toBuild.map(c => c.srcDir));
+
+            await Promise.all([...srcDirs].map(srcDir => {
+                const entries = toBuild.filter(c => c.srcDir === srcDir).map(c => c.sourcePath);
+
+                return this.#runEsbuild(entries, this.#paths.jsOutput, {
+                    platform: "browser",
+                    target: "es2020",
+                    outbase: srcDir,
+                    external: ["react", "react-dom", "react-dom/client", "react/jsx-runtime"],
+                    vendor: true,
+                    serverFunctions: true
+                });
+            }));
 
-        this.#stats.islands = hydrationFiles.length;
+            this.#stats.islands = toBuild.length;
+        }
+
+        return clientFiles;
+    }
+
+    #writeClientManifest(clientComponents) {
+        const manifest = {};
+
+        for (const { sourcePath, chunkId, chunkFile } of clientComponents) {
+            const fileUrl = "file:///" + sourcePath.replace(/\\/g, "/");
+
+            manifest[fileUrl] = {
+                id: chunkId,
+                chunks: [chunkId, chunkFile],
+                name: "*"
+            };
+        }
+
+        const manifestPath = path.join(Paths.build, "client-manifest.json");
+        fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+        fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+    }
+
+    #getTransitiveDependents(file, importedBy) {
+        const result = new Set();
+        const queue = [file];
+        let i = 0;
+
+        while (i < queue.length) {
+            const current = queue[i++];
+            const dependents = importedBy.get(current) || [];
+
+            for (const dep of dependents) {
+                if (!result.has(dep)) {
+                    result.add(dep);
+                    queue.push(dep);
+                }
+            }
+        }
+
+        return result;
     }
 
     async #buildCss() {
-        this.#stats.css = await this.#cssBuilder.build(this.#cache.viewsChanged);
+        this.#stats.css = await this.#cssBuilder.build(this.#cache.viewsChanged, this.#isDev);
     }
 
     async #runEsbuild(entries, outDir, options = {}) {
         if (!entries.length) return;
 
+        const isNode = (options.platform ?? "node") === "node";
+
         const plugins = [
             createCssStubPlugin(),
-            createMarkerPlugin(options, this.#isDev),
             createPathAliasPlugin()
         ];
 
+        // RSC plugin only for server builds — replaces "use client" with reference stubs.
+        // Browser builds need the actual component code.
+        if (isNode) {
+            // Prop filter must be registered BEFORE client reference so its onLoad
+            // handles "nitron-filtered" namespace before createClientReferencePlugin tries.
+            if (options.effectiveMap && options.clientPaths) {
+                plugins.push(createPropFilterPlugin(options.effectiveMap, options.clientPaths));
+            }
+
+            plugins.push(createClientReferencePlugin(this.#isDev));
+        }
+
         if (options.vendor) {
             plugins.push(createVendorGlobalsPlugin());
             plugins.push(createServerModuleBlockerPlugin());
@@ -466,8 +636,6 @@ class Builder {
             plugins.push(createServerFunctionsPlugin());
         }
 
-        const isNode = (options.platform ?? "node") === "node";
-
         const config = {
             entryPoints: entries,
             outdir: outDir,
@@ -499,7 +667,7 @@ class Builder {
         await esbuild.build(config);
     }
 
-    #addToManifest(entries, layouts, meta, baseDir, namespace) {
+    #addToManifest(entries, layouts, meta, baseDir, namespace, effectiveMap) {
         const layoutSet = new Set(layouts);
 
         for (const file of entries) {
@@ -531,11 +699,26 @@ class Builder {
                 cssSet.add(`/css/${path.basename(css)}`);
             }
 
-            this.#manifest[key] = {
+            const entry = {
                 css: [...cssSet],
                 layouts: layoutChain.map(l => l.name),
                 hydrationScript: null
             };
+
+            if (fileMeta?.isClient) {
+                const propUsage = effectiveMap.get(file) ?? null;
+                entry.propUsage = propUsage;
+
+                if (this.#isDev && propUsage === null) {
+                    const rel = path.relative(Paths.project, file).replace(/\\/g, "/");
+                    console.warn(`${COLORS.yellow}⚠ PropFilter: ${rel} — spread or dynamic prop access detected, all props will pass through${COLORS.reset}`);
+                }
+            }
+
+            // Collect translation keys from view + all transitive imports
+            entry.translationKeys = this.#collectTranslationKeys(file, meta);
+
+            this.#manifest[key] = entry;
         }
 
         for (const layout of layouts) {
@@ -559,15 +742,164 @@ class Builder {
         }
     }
 
+    /**
+     * Collects translation keys from a view file and all its transitive imports.
+     *
+     * Walks the import graph starting from `file`, collecting every static translation
+     * key found via build-time AST analysis (PropUsageAnalyzer).
+     *
+     * Returns null (= "send ALL translations") when any file in the graph uses dynamic
+     * keys that can't be statically determined — e.g. `t(variable)` instead of `t("key")`.
+     *
+     * @param {string} file - Entry file path (absolute).
+     * @param {Map} meta - File metadata from FileAnalyzer.
+     * @returns {string[]|null} Array of keys, or null if any file has dynamic keys.
+     */
+    #collectTranslationKeys(file, meta) {
+        const visited = new Set();
+        const allKeys = new Set();
+        let hasNull = false;
+
+        const walk = (filePath) => {
+            if (visited.has(filePath)) return;
+
+            visited.add(filePath);
+
+            const cached = this.#cache.propAnalysis.get(filePath);
+
+            if (!cached) {
+                // Non-JSX files (.ts, .js) don't have translation analysis — skip silently.
+                // JSX files without cache mean analysis failed — poison to null (send all).
+                if (!filePath.endsWith(".tsx") && !filePath.endsWith(".jsx")) {
+                    return;
+                }
+                hasNull = true;
+                return;
+            }
+
+            const keys = cached.translationKeys;
+
+            // null means "dynamic keys detected" — can't filter, must send all translations
+            if (keys === null) {
+                hasNull = true;
+                return;
+            }
+
+            if (keys) {
+                for (const k of keys) allKeys.add(k);
+            }
+
+            // Walk transitive imports — resolve relative paths to absolute before lookup
+            const fileMeta = meta.get(filePath);
+
+            if (fileMeta?.imports) {
+                for (const imp of fileMeta.imports) {
+                    const resolved = this.#analyzer.resolveImport(filePath, imp);
+                    walk(resolved);
+                }
+            }
+        };
+
+        walk(file);
+
+        if (hasNull) return null;
+        if (allKeys.size === 0) return [];
+
+        return [...allKeys];
+    }
+
+    /**
+     * Pre-scan phase: analyzes JSX prop forwarding and computes effective prop usage.
+     * This enables the prop filter plugin to strip unused data at server→client boundaries.
+     * @param {Map} meta - File metadata from FileAnalyzer.
+     * @returns {{effectiveMap: Map, clientPathSet: Set}}
+     */
+    #preScanPropUsage(meta) {
+        const propUsageMap = new Map();
+        const forwardMap = new Map();
+        const clientPathSet = new Set();
+        const cache = this.#cache.propAnalysis;
+
+        for (const [filePath, fileMeta] of meta.entries()) {
+            const isJsx = filePath.endsWith(".tsx") || filePath.endsWith(".jsx");
+
+            if (!fileMeta.isClient && !isJsx) continue;
+
+            if (fileMeta.isClient) clientPathSet.add(filePath);
+
+            let stat;
+
+            try { stat = fs.statSync(filePath); }
+            catch { continue; }
+
+            const cached = cache.get(filePath);
+
+            // Fast path: mtime unchanged → skip entirely
+            if (cached && cached.mtime === stat.mtimeMs) {
+                if (fileMeta.isClient) {
+                    propUsageMap.set(filePath, cached.propUsage);
+                    forwardMap.set(filePath, cached.forwarding);
+                }
+                continue;
+            }
+
+            // mtime changed — verify with content hash to avoid stale cache
+            const content = fs.readFileSync(filePath, "utf8");
+            const hash = crypto.createHash("md5").update(content).digest("hex");
+
+            if (cached && cached.hash === hash) {
+                const updatedCache = { ...cached, mtime: stat.mtimeMs };
+                cache.set(filePath, updatedCache);
+
+                if (fileMeta.isClient) {
+                    propUsageMap.set(filePath, cached.propUsage);
+                    forwardMap.set(filePath, cached.forwarding);
+                }
+                continue;
+            }
+
+            const { propUsage, forwarding, translationKeys } = PropUsageAnalyzer.analyzeAll(filePath);
+
+            cache.set(filePath, { mtime: stat.mtimeMs, hash, propUsage, forwarding, translationKeys });
+
+            if (fileMeta.isClient) {
+                propUsageMap.set(filePath, propUsage);
+                forwardMap.set(filePath, forwarding);
+            }
+        }
+
+        if (clientPathSet.size === 0) {
+            return { effectiveMap: new Map(), clientPathSet };
+        }
+
+        const effectiveMap = EffectivePropUsage.compute(propUsageMap, forwardMap, clientPathSet);
+
+        return { effectiveMap, clientPathSet };
+    }
+
     #writeManifest() {
         const manifestPath = path.join(Paths.build, "manifest.json");
+        const tmpPath = manifestPath + ".tmp";
+        const data = JSON.stringify(this.#manifest, null, 2);
+
         fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
-        fs.writeFileSync(manifestPath, JSON.stringify(this.#manifest, null, 2));
+        fs.writeFileSync(tmpPath, data);
+
+        try { fs.renameSync(tmpPath, manifestPath); }
+        catch {
+            fs.writeFileSync(manifestPath, data);
+        }
     }
 
     #writeJsxRuntime() {
-        fs.mkdirSync(path.dirname(this.#paths.jsxRuntime), { recursive: true });
-        fs.writeFileSync(this.#paths.jsxRuntime, JSX_RUNTIME);
+        const runtimePath = this.#paths.jsxRuntime;
+
+        if (fs.existsSync(runtimePath) && fs.readFileSync(runtimePath, "utf8") === JSX_RUNTIME) {
+            return;
+        }
+
+        fs.mkdirSync(path.dirname(runtimePath), { recursive: true });
+        fs.writeFileSync(runtimePath, JSX_RUNTIME);
     }
 
     #cleanOutputDirs() {