@nitronjs/framework 0.2.27 → 0.3.0

package/lib/Build/jsxRuntime.js

@@ -1,16 +1,16 @@
 /**
  * Custom JSX Runtime for NitronJS
- * 
+ *
  * Handles React 19's strict key prop requirements and provides
- * island architecture support for client components.
+ * server-side context helpers (csrf, request).
  */
+import { pluralize, replaceParams } from "../Translation/pluralize.js";
+
 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', 'key', 'ref']);
 
 // Filter React 19 key warnings from third-party libraries
 if (typeof console !== 'undefined' && console.error) {
@@ -19,7 +19,7 @@ if (typeof console !== 'undefined' && console.error) {
         const msg = args[0];
         if (typeof msg === 'string' && (
             msg.includes('A props object containing a "key" prop is being spread into JSX') ||
-            msg.includes('\`key\` is not a prop')
+            msg.includes('\\\`key\\\` is not a prop')
         )) {
             return;
         }
@@ -31,6 +31,9 @@ function getContext() {
     return globalThis[CTX]?.getStore?.();
 }
 
+${pluralize.toString()}
+${replaceParams.toString()}
+
 globalThis.csrf = () => getContext()?.csrf || '';
 
 globalThis.request = () => {
@@ -38,153 +41,26 @@ globalThis.request = () => {
     return ctx?.request || { path: '', method: 'GET', query: {}, params: {}, headers: {}, cookies: {}, ip: '', isAjax: false, session: null, auth: null };
 };
 
-const DepthContext = React.createContext(false);
-const componentCache = new WeakMap();
-
-// Sanitizes props for client-side hydration (removes functions, symbols, circular refs)
-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 });
-}
-
-// Deep Proxy that tracks which prop paths are accessed during SSR
-// Pre-wraps all nested objects so React's Object.freeze won't break Proxy invariants
-function trackProps(obj) {
-    const accessed = new Set();
-    const cache = new WeakMap();
-
-    function wrap(source, prefix) {
-        if (source === null || typeof source !== 'object') return source;
-        if (cache.has(source)) return cache.get(source);
-
-        const isArr = Array.isArray(source);
-        const copy = isArr ? [] : {};
-
-        for (const key of Object.keys(source)) {
-            const val = source[key];
-
-            if (val !== null && typeof val === 'object' && typeof val !== 'function') {
-                copy[key] = wrap(val, prefix ? prefix + '.' + key : key);
-            }
-            else {
-                copy[key] = val;
-            }
-        }
-
-        const proxy = new Proxy(copy, {
-            get(t, prop, receiver) {
-                if (typeof prop === 'symbol') return Reflect.get(t, prop, receiver);
-
-                const val = Reflect.get(t, prop, receiver);
-                if (typeof val === 'function') return val;
-
-                if (val !== undefined) {
-                    const currentPath = prefix ? prefix + '.' + String(prop) : String(prop);
-                    accessed.add(currentPath);
-                }
-
-                return val;
-            }
-        });
-
-        cache.set(source, proxy);
-        return proxy;
-    }
-
-    return { proxy: wrap(obj, ''), accessed };
-}
-
-function resolveExists(obj, path) {
-    const parts = path.split('.');
-    let current = obj;
-    for (let i = 0; i < parts.length; i++) {
-        if (current == null || typeof current !== 'object') return false;
-        current = current[parts[i]];
-    }
-    return current !== undefined;
-}
-
-// Creates an island wrapper for client components (hydrated independently)
-function createIsland(Component, name) {
-    function IslandBoundary(props) {
-        if (React.useContext(DepthContext)) {
-            return OriginalJsx.jsx(Component, props);
-        }
-
-        const id = React.useId();
-        const tracker = trackProps(props);
-
-        if (Component.__propHints) {
-            for (const hint of Component.__propHints) {
-                if (resolveExists(props, hint)) {
-                    tracker.accessed.add(hint);
-                }
+globalThis.__ = (key, params) => {
+    const ctx = getContext();
+    const translations = ctx?.translations
+        || (typeof window !== 'undefined' ? window.__NITRON_TRANSLATIONS__ : null);
+
+    if (translations) {
+        let value = translations[key];
+        if (value !== undefined) {
+            value = String(value);
+            if (params && typeof params === 'object'
+                && params.count !== undefined && value.includes('|')) {
+                value = pluralize(value, params.count);
             }
+            return replaceParams(value, params);
         }
-
-        const ctx = getContext();
-        if (ctx) {
-            ctx.props = ctx.props || {};
-            ctx.trackers = ctx.trackers || {};
-            ctx.props[id] = props;
-            ctx.trackers[id] = tracker.accessed;
-        }
-
-        return OriginalJsx.jsx('div', {
-            'data-cid': id,
-            'data-island': name,
-            children: wrapWithDepth(OriginalJsx.jsx(Component, tracker.proxy))
-        });
+        return key;
     }
-
-    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);
-}
+    return globalThis.__nitron_lang_get?.(key, params) ?? key;
+};
+globalThis.lang = globalThis.__;
 
 // Extracts key from props without triggering React 19's getter warning
 function extractKey(props, key) {
@@ -207,17 +83,11 @@ function extractKey(props, key) {
 
 export function jsx(type, props, key) {
     const [cleanProps, finalKey] = extractKey(props, key);
-    if (typeof type === 'function' && type[MARK]) {
-        return OriginalJsx.jsx(getWrappedComponent(type), cleanProps, finalKey);
-    }
     return OriginalJsx.jsx(type, cleanProps, finalKey);
 }
 
 export function jsxs(type, props, key) {
     const [cleanProps, finalKey] = extractKey(props, key);
-    if (typeof type === 'function' && type[MARK]) {
-        return OriginalJsx.jsx(getWrappedComponent(type), cleanProps, finalKey);
-    }
     return OriginalJsx.jsxs(type, cleanProps, finalKey);
 }
 

package/lib/Build/plugins.js

@@ -4,9 +4,21 @@ import { parse } from "@babel/parser";
 import traverse from "@babel/traverse";
 import Paths from "../Core/Paths.js";
 import COLORS from "./colors.js";
+import { resolveComponentPath } from "./propUtils.js";
 
 const _traverse = traverse.default;
 
+/**
+ * Checks if a source file has a "use client" directive at the top.
+ * Allows leading single-line (//) and multi-line comments before the directive.
+ * @param {string} source - File source code.
+ * @returns {boolean}
+ */
+function hasUseClientDirective(source) {
+    const stripped = source.slice(0, 500).replace(/^\s*(\/\/[^\n]*\n|\/\*[\s\S]*?\*\/\s*)*/g, "");
+    return /^\s*["']use client["']/.test(stripped.slice(0, 50));
+}
+
 /**
  * Creates an esbuild plugin for path alias resolution.
  * Supports @/, @css/, @views/, @models/, @controllers/, @middlewares/ aliases.
@@ -24,14 +36,13 @@ export function createPathAliasPlugin() {
         "@controllers/": path.join(root, "app/Controllers"), // Controllers
         "@middlewares/": path.join(root, "app/Middlewares"), // Middlewares
     };
-    
+
+    const sortedPrefixes = Object.keys(aliases).sort((a, b) => b.length - a.length);
+
     return {
         name: "path-alias",
         setup: (build) => {
-            // Handle all @ prefixed imports
             build.onResolve({ filter: /^@[a-z]*\// }, async (args) => {
-                // Find matching alias (longest match first)
-                const sortedPrefixes = Object.keys(aliases).sort((a, b) => b.length - a.length);
                 
                 for (const prefix of sortedPrefixes) {
                     if (args.path.startsWith(prefix)) {
@@ -86,7 +97,7 @@ export function createOriginalJsxPlugin() {
 
 /**
  * Creates an esbuild plugin that maps React packages to window globals.
- * Used for client bundles to share React instance across islands.
+ * Used for client bundles to share React instance across client components.
  * @returns {import("esbuild").Plugin}
  */
 export function createVendorGlobalsPlugin() {
@@ -218,71 +229,12 @@ export function createCssStubPlugin() {
 }
 
 /**
- * Creates an esbuild plugin that marks client components with a symbol.
- * Used for Islands Architecture to identify hydration boundaries.
- * @param {import("esbuild").BuildOptions} options - Build options.
- * @param {boolean} isDev - Whether in development mode.
- * @returns {import("esbuild").Plugin}
- */
-export function createMarkerPlugin(options, 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 = 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`;
-                }
-
-                const hints = extractPropHints(ast, exports.map(e => e.name));
-                if (hints.length > 0) {
-                    for (const exp of exports) {
-                        additionalCode += `try { ${exp.name}.__propHints = ${JSON.stringify(hints)}; } catch {}\n`;
-                    }
-                }
-
-                return { contents: source + additionalCode, loader: "tsx" };
-            });
-        }
-    };
-}
-
-/**
- * Finds all exported functions/components in an AST.
+ * Finds all exported functions/components in an AST with source positions.
+ * Used by the RSC client reference plugin to inject annotations inline.
  * @param {import("@babel/parser").ParseResult} ast - Parsed AST.
- * @returns {Array<{name: string}>} Array of export names.
+ * @returns {Array<{name: string, isDefault: boolean, end: number}>}
  */
-function findExports(ast) {
+function findExportsWithPositions(ast) {
     const exports = [];
 
     _traverse(ast, {
@@ -294,31 +246,33 @@ function findExports(ast) {
                 name = decl.name;
             } else if (decl.type === "FunctionDeclaration" && decl.id?.name) {
                 name = decl.id.name;
-            } else if (decl.type === "CallExpression" && 
+            } else if (decl.type === "CallExpression" &&
                 ["memo", "forwardRef", "lazy"].includes(decl.callee?.name)) {
                 name = decl.arguments[0]?.name || "__default__";
             }
 
-            exports.push({ name });
+            exports.push({ name, isDefault: true, end: p.node.end });
         },
 
         ExportNamedDeclaration: (p) => {
             for (const spec of p.node.specifiers || []) {
                 if (spec.type === "ExportSpecifier") {
                     exports.push({
-                        name: spec.exported.name === "default" ? spec.local.name : spec.exported.name
+                        name: spec.exported.name === "default" ? spec.local.name : spec.exported.name,
+                        isDefault: spec.exported.name === "default",
+                        end: p.node.end
                     });
                 }
             }
 
             const decl = p.node.declaration;
             if (decl?.type === "FunctionDeclaration" && decl.id?.name) {
-                exports.push({ name: decl.id.name });
+                exports.push({ name: decl.id.name, isDefault: false, end: p.node.end });
             }
             if (decl?.type === "VariableDeclaration") {
                 for (const d of decl.declarations) {
                     if (d.id.type === "Identifier" && d.init?.type === "ArrowFunctionExpression") {
-                        exports.push({ name: d.id.name });
+                        exports.push({ name: d.id.name, isDefault: false, end: p.node.end });
                     }
                 }
             }
@@ -329,98 +283,210 @@ function findExports(ast) {
 }
 
 /**
- * Extracts prop access hints from a "use client" component's AST.
- * Finds all property access patterns on destructured props, including
- * those inside event handlers and other non-SSR code paths.
- * @param {import("@babel/parser").ParseResult} ast - Parsed AST.
- * @param {string[]} exportNames - Names of exported components.
- * @returns {string[]} Array of prop access paths.
+ * Creates an esbuild plugin that annotates "use client" components with
+ * Flight client reference metadata in the server build.
+ *
+ * Unlike a full replacement approach, this KEEPS the original component code
+ * intact and appends $$typeof / $$id / $$async properties to each export.
+ *
+ * This allows both renderers to share the same build output:
+ * - react-dom/server ignores these properties → renders real HTML (SEO)
+ * - Flight renderer sees $$typeof CLIENT_REFERENCE → serializes as import ref
+ *
+ * Only active in the server build — client builds are unaffected.
+ *
+ * @param {boolean} isDev
+ * @returns {import("esbuild").Plugin}
  */
-function extractPropHints(ast, exportNames) {
-    const paramMap = new Map();
+/**
+ * Creates an esbuild plugin that wraps "use client" components with prop filtering
+ * at server→client boundaries. Only active in the server build.
+ *
+ * When a server component imports a client component, the plugin intercepts the import
+ * and generates a virtual wrapper module that:
+ * 1. Imports the original component (with $$typeof annotation)
+ * 2. Filters props based on effective prop usage analysis
+ * 3. Returns createElement with the original component + filtered props
+ *
+ * The wrapper has no $$typeof → React treats it as a server component → calls it.
+ * Inside, it creates an element with the real $$typeof component → Flight serializes correctly.
+ *
+ * @param {Map<string, object|null>} effectiveMap - Effective prop usage per client component path.
+ * @param {Set<string>} clientPaths - All client component absolute paths.
+ * @param {boolean} isDev
+ * @returns {import("esbuild").Plugin}
+ */
+export function createPropFilterPlugin(effectiveMap, clientPaths) {
+    return {
+        name: "prop-filter",
+        setup: (build) => {
+            build.onResolve({ filter: /^\./ }, (args) => {
+                if (args.namespace === "nitron-filtered") return null;
 
-    _traverse(ast, {
-        FunctionDeclaration(p) {
-            if (exportNames.includes(p.node.id?.name)) {
-                extractObjectParams(p.node.params[0], paramMap);
-            }
-        },
-        VariableDeclarator(p) {
-            if (exportNames.includes(p.node.id?.name)) {
-                const init = p.node.init;
-                if (init?.type === "ArrowFunctionExpression" || init?.type === "FunctionExpression") {
-                    extractObjectParams(init.params[0], paramMap);
-                }
-            }
-        }
-    });
+                const resolvedPath = resolveComponentPath(args.path, args.resolveDir);
+                if (!resolvedPath || !clientPaths.has(resolvedPath)) return null;
 
-    if (paramMap.size === 0) return [];
+                if (clientPaths.has(args.importer)) return null;
 
-    const hints = new Set();
+                const propUsage = effectiveMap.get(resolvedPath);
 
-    _traverse(ast, {
-        MemberExpression(p) {
-            collectPropHint(p, paramMap, hints);
-        },
-        OptionalMemberExpression(p) {
-            collectPropHint(p, paramMap, hints);
-        }
-    });
+                // Skip if no effective prop usage (null = unanalyzable, empty = no props)
+                if (!propUsage || typeof propUsage !== "object" || Object.keys(propUsage).length === 0) {
+                    return null;
+                }
 
-    return [...hints].sort();
-}
+                return {
+                    path: resolvedPath,
+                    namespace: "nitron-filtered",
+                    pluginData: { propUsage }
+                };
+            });
 
-function extractObjectParams(param, map) {
-    if (!param || param.type !== "ObjectPattern") return;
+            build.onLoad({ filter: /.*/, namespace: "nitron-filtered" }, (args) => {
+                const propUsage = args.pluginData?.propUsage;
+                const importPath = args.path.replace(/\\/g, "/");
+
+                if (!propUsage || typeof propUsage !== "object" || Object.keys(propUsage).length === 0) {
+                    // No prop usage or unanalyzable — import original directly (no filtering)
+                    return {
+                        contents: `export { default } from "${importPath}";\nexport * from "${importPath}";`,
+                        loader: "js",
+                        resolveDir: path.dirname(args.path)
+                    };
+                }
 
-    for (const prop of param.properties) {
-        if (prop.type === "ObjectProperty") {
-            const propName = prop.key.name || prop.key.value;
-            const localName = prop.value.type === "Identifier"
-                ? prop.value.name
-                : prop.value.type === "AssignmentPattern" && prop.value.left?.type === "Identifier"
-                    ? prop.value.left.name
-                    : null;
+                // Wrapper uses default import — skip wrapping for named-export-only files.
+                // Phase 2 will add per-export wrapper support for these.
+                const source = fs.readFileSync(args.path, "utf8");
+                const hasDefaultExport = /^export\s+default\b/m.test(source);
+
+                if (!hasDefaultExport) {
+                    return {
+                        contents: `export * from "${importPath}";`,
+                        loader: "js",
+                        resolveDir: path.dirname(args.path)
+                    };
+                }
 
-            if (propName && localName) {
-                map.set(localName, propName);
-            }
+                const contents = generateFilterWrapper(args.path, propUsage);
+
+                return {
+                    contents,
+                    loader: "js",
+                    resolveDir: path.dirname(args.path)
+                };
+            });
         }
-        else if (prop.type === "RestElement" && prop.argument?.type === "Identifier") {
-            map.set(prop.argument.name, prop.argument.name);
+    };
+}
+
+/**
+ * Generates a virtual wrapper module that filters props before passing to the real component.
+ * @param {string} componentPath - Absolute path to the client component.
+ * @param {object} propUsage - Effective prop usage tree.
+ * @returns {string}
+ */
+function generateFilterWrapper(componentPath, propUsage) {
+    const importPath = componentPath.replace(/\\/g, "/");
+    const usageJson = JSON.stringify(propUsage);
+
+    return `
+import { createElement } from "react";
+import __Impl from "${importPath}";
+export * from "${importPath}";
+
+const __usage = ${usageJson};
+
+function __prune(data, usage) {
+    if (usage === true) return data;
+    if (data == null || typeof data !== "object") return data;
+    if (Array.isArray(data)) {
+        if (usage["[]"]) {
+            return data.map(function(item) { return __prune(item, usage["[]"]); });
         }
     }
+    var result = {};
+    for (var key of Object.keys(usage)) {
+        var val = data[key];
+        if (val === undefined) continue;
+        result[key] = typeof usage[key] === "object" ? __prune(val, usage[key]) : val;
+    }
+    return result;
 }
 
-function collectPropHint(path, paramMap, hints) {
-    const parent = path.parent;
-
-    if ((parent.type === "MemberExpression" || parent.type === "OptionalMemberExpression") && parent.object === path.node) {
-        return;
+export default function __PropFilterWrapper(props) {
+    var filtered = {};
+    for (var key of Object.keys(props)) {
+        if (key === "children" || key === "key" || key === "ref") {
+            filtered[key] = props[key];
+            continue;
+        }
+        var u = __usage[key];
+        if (u === undefined) continue;
+        filtered[key] = typeof u === "object" ? __prune(props[key], u) : props[key];
     }
+    return createElement(__Impl, filtered);
+}
+`;
+}
 
-    const chain = [];
-    let current = path.node;
+export function createClientReferencePlugin(isDev) {
+    return {
+        name: "rsc-client-reference",
+        setup: (build) => {
+            build.onLoad({ filter: /\.tsx$/ }, async (args) => {
+                const source = await fs.promises.readFile(args.path, "utf8");
 
-    while (current.type === "MemberExpression" || current.type === "OptionalMemberExpression") {
-        if (current.computed) return;
-        if (current.property?.type !== "Identifier") return;
-        chain.unshift(current.property.name);
-        current = current.object;
-    }
+                if (!hasUseClientDirective(source)) {
+                    return null;
+                }
 
-    if (current.type !== "Identifier") return;
+                let ast;
+                try {
+                    ast = parse(source, {
+                        sourceType: "module",
+                        plugins: ["typescript", "jsx"]
+                    });
+                }
+                catch {
+                    if (isDev) {
+                        console.warn(`${COLORS.yellow}⚠ RSC Parse: ${args.path}${COLORS.reset}`);
+                    }
+                    return null;
+                }
 
-    const rootProp = paramMap.get(current.name);
-    if (!rootProp) return;
+                const exports = findExportsWithPositions(ast);
+                if (!exports.length) {
+                    return null;
+                }
 
-    if (parent.type === "CallExpression" && parent.callee === path.node && chain.length > 0) {
-        chain.pop();
-    }
+                const fileUrl = "file:///" + args.path.replace(/\\/g, "/");
+                const symbolCode = `Symbol.for("react.client.reference")`;
 
-    const fullPath = chain.length > 0 ? rootProp + "." + chain.join(".") : rootProp;
-    hints.add(fullPath);
-}
+                // Insert annotations right after each export declaration (not at file end).
+                // esbuild drops code after the final export block for entry points,
+                // so annotations must be interleaved with declarations.
+                const sorted = [...exports].sort((a, b) => b.end - a.end);
+                let modified = source;
+
+                for (const exp of sorted) {
+                    if (exp.name === "__default__") continue;
 
-export { findExports, extractPropHints };
+                    const exportName = exp.isDefault ? "default" : exp.name;
+
+                    // Only annotate functions — skip context objects, constants, types.
+                    // typeof guard prevents overwriting React's own $$typeof on contexts.
+                    let annotation = `\nif (typeof ${exp.name} === "function") { try { Object.defineProperties(${exp.name}, {\n`;
+                    annotation += `    $$typeof: { value: ${symbolCode} },\n`;
+                    annotation += `    $$id: { value: "${fileUrl}#${exportName}" },\n`;
+                    annotation += `    $$async: { value: false }\n`;
+                    annotation += `}); } catch {} }\n`;
+
+                    modified = modified.slice(0, exp.end) + annotation + modified.slice(exp.end);
+                }
+
+                return { contents: modified, loader: "tsx" };
+            });
+        }
+    };
+}