@nitronjs/framework 0.2.26 → 0.3.0

package/lib/View/Client/spa.js

@@ -1,20 +1,40 @@
+/**
+ * SPA Client — Client-side navigation using RSC (React Server Components).
+ *
+ * Intercepts local <a> clicks and browser back/forward events,
+ * fetches a fresh RSC Flight payload from /__nitron/rsc, and lets
+ * React reconcile the DOM without a full page reload.
+ *
+ * Wire format from /__nitron/rsc:
+ *   "<flightLength>\n<flightPayload><jsonMetadata>"
+ *   - First line: byte length of the Flight payload
+ *   - Then the Flight payload itself (React serialization format)
+ *   - Then a JSON object with { meta, css, translations }
+ */
 (function() {
     "use strict";
 
-    var ENDPOINT = "/__nitron/navigate";
+    var RSC_ENDPOINT = "/__nitron/rsc";
+
+    // URLs that should never be intercepted by SPA navigation
     var SKIP = /^(\/storage|\/api|\/__|#|javascript:|mailto:|tel:)/;
-    var layouts = [];
+
     var navigating = false;
 
-    // Route helper function for client-side
+    // --- Client-side route() helper ---
+
+    // Mirrors the server-side route() global — resolves named routes to URL paths.
+    // Route definitions are injected by the server into window.__NITRON_RUNTIME__.routes.
     globalThis.route = function(name, params) {
         var runtime = window.__NITRON_RUNTIME__;
+
         if (!runtime || !runtime.routes) {
             console.error("Route runtime not initialized");
             return "";
         }
 
         var pattern = runtime.routes[name];
+
         if (!pattern) {
             console.error('Route "' + name + '" not found');
             return "";
@@ -28,89 +48,140 @@
         });
     };
 
+    // --- Link Interception ---
+
     function init() {
-        var rt = window.__NITRON_RUNTIME__;
-        if (rt && rt.layouts) layouts = rt.layouts;
+        // Capture phase (true) so we intercept before any stopPropagation
         document.addEventListener("click", onClick, true);
         window.addEventListener("popstate", onPopState);
     }
 
+    // Intercepts <a> clicks — if the link is local, navigates via RSC instead of full reload
     function onClick(e) {
         if (navigating) return;
         var link = e.target.closest("a");
+
         if (!link) return;
+
         var href = link.getAttribute("href");
+
         if (!href || link.target === "_blank" || link.download) return;
         if (e.ctrlKey || e.metaKey || e.shiftKey || e.altKey) return;
         if (!isLocal(href)) return;
+
         e.preventDefault();
         navigate(href, true);
     }
 
+    // Browser back/forward — re-fetch RSC payload for the new URL
     function onPopState() {
         navigate(location.pathname + location.search, false);
     }
 
+    // Returns true if the href points to the same origin and is not in the SKIP list
     function isLocal(href) {
         if (!href || SKIP.test(href)) return false;
+
+        // Absolute URLs — check if same origin
         if (/^https?:\/\/|^\/\//.test(href)) {
             try { return new URL(href, location.origin).origin === location.origin; }
             catch (e) { return false; }
         }
+
         return true;
     }
 
+    // --- RSC Wire Format Parser ---
+
+    // Parses the length-prefixed response from /__nitron/rsc.
+    // Format: "<length>\n<flight payload><json metadata>"
+    // Returns { payload, meta, css, translations } or null on malformed input.
+    function parseLengthPrefixed(text) {
+        var nl = text.indexOf("\n");
+        if (nl === -1) return null;
+
+        var len = parseInt(text.substring(0, nl), 10);
+        if (isNaN(len) || len < 0) return null;
+
+        var flight = text.substring(nl + 1, nl + 1 + len);
+        var jsonStr = text.substring(nl + 1 + len);
+        var data;
+
+        try { data = JSON.parse(jsonStr); }
+        catch (e) { return null; }
+
+        return {
+            payload: flight,
+            meta: data.meta || null,
+            css: data.css || null,
+            translations: data.translations || null
+        };
+    }
+
+    // --- SPA Navigation ---
+
+    // Core navigation: fetches RSC payload and lets React reconcile.
+    // Falls back to full page load on error or timeout (10s).
     function navigate(url, push) {
         if (navigating) return;
+
+        var rsc = window.__NITRON_RSC__;
+
+        // RSC root not available (e.g. initial page was server-rendered without hydration)
+        if (!rsc || !rsc.root) {
+            location.href = url;
+            return;
+        }
+
         navigating = true;
 
+        // Abort + fallback after 10 seconds to prevent hanging navigations
         var ctrl = typeof AbortController !== "undefined" ? new AbortController() : null;
         var timer = setTimeout(function() { if (ctrl) ctrl.abort(); fallback(); }, 10000);
 
-        fetch(ENDPOINT + "?url=" + encodeURIComponent(url), {
+        fetch(RSC_ENDPOINT + "?url=" + encodeURIComponent(url), {
             headers: { "X-Nitron-SPA": "1" },
             credentials: "same-origin",
             signal: ctrl ? ctrl.signal : undefined
         })
         .then(function(r) {
             clearTimeout(timer);
+
             if (!r.ok) throw new Error("HTTP " + r.status);
-            return r.json();
+
+            return r.text().then(function(text) {
+                return parseLengthPrefixed(text);
+            });
         })
         .then(function(d) {
-            if (d.error) { fallback(); return; }
-            if (d.redirect) {
-                navigating = false;
-                isLocal(d.redirect) ? navigate(d.redirect, push) : (location.href = d.redirect);
-                return;
-            }
-
-            if (!layouts.length || !arrEq(layouts, d.layouts || [])) {
-                fallback();
-                return;
-            }
+            if (!d || !d.payload) { fallback(); return; }
 
-            updateSlot(d.html);
-            layouts = d.layouts || [];
-            if (window.__NITRON_RUNTIME__) window.__NITRON_RUNTIME__.layouts = layouts;
+            // Merge translations BEFORE rsc.navigate — persistent components (layouts) keep their keys
+            if (d.translations) {
+                var prev = window.__NITRON_TRANSLATIONS__;
 
-            if (d.hydrationScript) {
-                if (d.runtime) Object.assign(window.__NITRON_RUNTIME__ || {}, d.runtime);
-                if (d.props) window.__NITRON_PROPS__ = d.props;
-                loadScript("/storage" + d.hydrationScript + "?t=" + Date.now(), true);
+                window.__NITRON_TRANSLATIONS__ = prev
+                    ? Object.assign({}, prev, d.translations)
+                    : d.translations;
             }
 
+            // Use RSC consumer to render new payload via React reconciliation
+            rsc.navigate(d.payload);
+
             if (push) history.pushState({ nitron: 1 }, "", url);
-            if (d.meta) {
-                if (d.meta.title) document.title = d.meta.title;
-                setMeta("description", d.meta.description);
-            }
+
+            if (d.meta && d.meta.title) document.title = d.meta.title;
+            setMeta("description", d.meta ? d.meta.description : null);
+
+            // Load new CSS stylesheets if needed
+            if (d.css) loadNewCss(d.css);
 
             scrollTo(0, 0);
             dispatchEvent(new CustomEvent("nitron:navigate", { detail: { url: url } }));
             navigating = false;
         })
         .catch(function() {
+            // RSC fetch failed or aborted — full page load as last resort
             clearTimeout(timer);
             fallback();
         });
@@ -121,34 +192,32 @@
         }
     }
 
-    function arrEq(a, b) {
-        if (!a || !b || a.length !== b.length) return false;
-        for (var i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
-        return true;
-    }
+    // --- CSS & Meta Helpers ---
 
-    function updateSlot(html) {
-        var slot = document.querySelector("[data-nitron-slot='page']");
-        if (!slot) {
-            location.reload();
-            return;
-        }
-        var tmp = document.createElement("div");
-        tmp.innerHTML = html;
-        var inner = tmp.querySelector("[data-nitron-slot='page']");
-        slot.innerHTML = inner ? inner.innerHTML : html;
-    }
+    // Loads CSS files that the new page needs but the current page doesn't have
+    function loadNewCss(cssFiles) {
+        var existing = new Set();
+
+        document.querySelectorAll('link[rel="stylesheet"]').forEach(function(link) {
+            existing.add(link.getAttribute("href"));
+        });
 
-    function loadScript(src, isModule) {
-        var s = document.createElement("script");
-        if (isModule) s.type = "module";
-        s.src = src;
-        document.body.appendChild(s);
+        for (var i = 0; i < cssFiles.length; i++) {
+            if (!existing.has(cssFiles[i])) {
+                var link = document.createElement("link");
+                link.rel = "stylesheet";
+                link.href = cssFiles[i];
+                document.head.appendChild(link);
+            }
+        }
     }
 
+    // Creates or updates a <meta> tag (e.g. description)
     function setMeta(name, val) {
         if (!val) return;
+
         var m = document.querySelector('meta[name="' + name + '"]');
+
         if (m) m.content = val;
         else {
             m = document.createElement("meta");
@@ -158,6 +227,8 @@
         }
     }
 
+    // --- Initialize ---
+
     document.readyState === "loading"
         ? document.addEventListener("DOMContentLoaded", init)
         : init();

package/lib/View/ClientManifest.js

@@ -0,0 +1,60 @@
+import { existsSync, readFileSync, statSync } from "fs";
+import path from "path";
+import Paths from "../Core/Paths.js";
+import Environment from "../Core/Environment.js";
+
+const MANIFEST_PATH = path.join(Paths.build, "client-manifest.json");
+
+/**
+ * Maps "use client" components to their browser-side chunk locations.
+ * Build writes client-manifest.json, this class loads it at render time.
+ *
+ * The Flight renderer looks up client components in this manifest to know
+ * which JS file the browser should load for each client component reference.
+ *
+ * Format (what react-server-dom-webpack expects):
+ * {
+ *     "file:///abs/path/to/SearchBar.tsx": {
+ *         id:     "SearchBar",
+ *         chunks: ["SearchBar", "js/Components/SearchBar.js"],
+ *         name:   "*"
+ *     }
+ * }
+ */
+class ClientManifest {
+    static #entries = null;
+    static #mtime = null;
+
+    /**
+     * Get the manifest object for FlightRenderer.
+     * Loads from client-manifest.json with mtime-based cache busting in dev.
+     *
+     * @returns {object}
+     */
+    static get() {
+        if (Environment.isDev && this.#entries) {
+            try {
+                const mtime = statSync(MANIFEST_PATH).mtimeMs;
+
+                if (mtime !== this.#mtime) {
+                    this.#entries = null;
+                }
+            }
+            catch {}
+        }
+
+        if (!this.#entries) {
+            if (!existsSync(MANIFEST_PATH)) {
+                return {};
+            }
+
+            this.#entries = JSON.parse(readFileSync(MANIFEST_PATH, "utf8"));
+            this.#mtime = statSync(MANIFEST_PATH).mtimeMs;
+        }
+
+        return this.#entries;
+    }
+
+}
+
+export default ClientManifest;

package/lib/View/FlightRenderer.js

@@ -0,0 +1,100 @@
+import { createRequire } from "module";
+import path from "path";
+import { PassThrough } from "stream";
+import React from "react";
+import Environment from "../Core/Environment.js";
+
+const require = createRequire(import.meta.url);
+
+// The Flight renderer expects React's server internals (H = hooks dispatcher,
+// A = async dispatcher). Normal React only exports __CLIENT_INTERNALS_..., so we
+// provide __SERVER_INTERNALS_... as a separate object. Both dispatchers are set by
+// their respective renderers before rendering, so parallel execution is safe:
+//   - react-dom/server uses __CLIENT_INTERNALS_... → no conflict
+//   - Flight renderer uses __SERVER_INTERNALS_... → no conflict
+if (!React.__SERVER_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE) {
+    React.__SERVER_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE = { H: null, A: null };
+}
+
+// Load production Flight renderer via absolute path (bypasses package.json exports).
+const serverNodePath = require.resolve("react-server-dom-webpack/server.node");
+const prodPath = path.join(path.dirname(serverNodePath), "cjs/react-server-dom-webpack-server.node.production.js");
+
+const { renderToPipeableStream } = require(prodPath);
+
+/**
+ * Produces RSC Flight payloads from React element trees.
+ * Flight payload = serialized React element tree that the browser React can reconcile.
+ *
+ * Server components become inline data, client components become import references.
+ * The browser React reads the payload and builds its virtual DOM from it,
+ * enabling surgical DOM updates via reconciliation.
+ */
+class FlightRenderer {
+    /**
+     * Render a React element tree to an RSC Flight payload string.
+     *
+     * @param {React.ReactElement} element  - The full component tree (page + layouts)
+     * @param {object} clientManifest       - Maps client component IDs to chunk info
+     * @param {object} [options]            - Optional: onError callback
+     * @returns {Promise<string>}           - The complete Flight payload
+     */
+    static render(element, clientManifest, options = {}) {
+        return new Promise((resolve, reject) => {
+            const chunks = [];
+            const stream = new PassThrough();
+            let done = false;
+            let renderError = null;
+
+            const finish = (result) => {
+                if (done) return;
+                done = true;
+                clearTimeout(timer);
+
+                if (renderError) {
+                    reject(renderError);
+                }
+                else {
+                    resolve(result);
+                }
+            };
+
+            const timeout = Environment.isDev ? 10000 : 3000;
+            const timer = setTimeout(() => {
+                const error = new Error("RSC render timeout - component took too long");
+                error.statusCode = 500;
+                renderError = error;
+                stream.destroy();
+                finish(null);
+            }, timeout);
+
+            stream.on("data", chunk => chunks.push(chunk));
+            stream.on("end", () => finish(Buffer.concat(chunks).toString("utf-8")));
+            stream.on("error", (error) => {
+                renderError = error;
+                finish(null);
+            });
+
+            try {
+                const { pipe } = renderToPipeableStream(element, clientManifest, {
+                    onError: (error) => {
+                        if (options.onError) {
+                            options.onError(error);
+                        }
+                        renderError = error;
+                        finish(null);
+                    }
+                });
+
+                pipe(stream);
+            }
+            catch (error) {
+                renderError = error;
+                finish(null);
+            }
+        });
+    }
+
+}
+
+export default FlightRenderer;

package/lib/View/Layout.js

@@ -86,9 +86,6 @@ class Layout {
         return LAYOUT_NAMES.has(basename);
     }
 
-    static clearCache() {
-        this.#cache.clear();
-    }
 }
 
 export default Layout;

package/lib/View/PropFilter.js

@@ -0,0 +1,81 @@
+/**
+ * Runtime prop filtering for Flight payload security.
+ * Strips unused data from props before Flight serialization
+ * based on build-time AST analysis of component prop usage.
+ */
+
+/** Props that always pass through without filtering. */
+const BYPASS_PROPS = new Set(["children", "key", "ref"]);
+
+
+class PropFilter {
+    /**
+     * Filter props before Flight serialization.
+     *
+     * @param {object} params    - Raw props from the controller.
+     * @param {object|null} propUsage - Usage tree from build manifest (null = passthrough).
+     * @returns {object} Filtered props safe for client delivery.
+     */
+    static apply(params, propUsage) {
+        if (!params || typeof params !== "object") return params;
+        if (!propUsage || typeof propUsage !== "object") return params;
+
+        return pruneByUsage(params, propUsage);
+    }
+}
+
+
+/**
+ * Prunes an object to only include properties matching the usage tree.
+ *
+ * Usage tree format:
+ *   - true         → pass the value as-is
+ *   - { sub: ... } → pass only matching sub-properties
+ *   - absent key   → strip entirely
+ *
+ * @param {*} data         - Data to prune.
+ * @param {object|true} usage - Usage tree node.
+ * @returns {*} Pruned data.
+ */
+function pruneByUsage(data, usage) {
+    if (usage === true) return data;
+
+    if (data === null || data === undefined) return data;
+    if (typeof data !== "object") return data;
+
+    if (Array.isArray(data)) {
+        if (usage["[]"]) {
+            return data.map(item => pruneByUsage(item, usage["[]"]));
+        }
+        // No element iteration in usage — fall through to object pruning
+        // to preserve scalar properties (e.g. length) without leaking elements.
+    }
+
+    const result = Object.create(null);
+
+    for (const key of Object.keys(usage)) {
+        if (key === "__proto__" || key === "constructor" || key === "prototype") continue;
+        if (!(key in data)) continue;
+
+        const subUsage = usage[key];
+        const value = data[key];
+
+        if (subUsage === true) {
+            result[key] = value;
+        }
+        else if (subUsage && typeof subUsage === "object") {
+            result[key] = pruneByUsage(value, subUsage);
+        }
+    }
+
+    // Bypass props always pass through even if not in usage tree
+    for (const bp of BYPASS_PROPS) {
+        if (bp in data && !(bp in result)) {
+            result[bp] = data[bp];
+        }
+    }
+
+    return result;
+}
+
+export default PropFilter;