@broxium/compiler 1.0.0 → 1.2.0

package/README.md

@@ -0,0 +1,251 @@
+# @broxium/compiler
+
+The Brodox component compiler. Takes a developer's component source files (TSX/JSX) and compiles them into two versioned ESM bundles — one for server-side rendering and one for browser hydration.
+
+This is an internal package used by the Brodox platform. Developers building components do **not** use this directly; it is called automatically when a component version is approved in the Brodox dashboard.
+
+## Installation
+
+```bash
+npm install @broxium/compiler
+```
+
+Node.js 20+ is required.
+
+---
+
+## What it does
+
+When a component version is approved, `BrodoxCompiler.compile()` is called with the component's source files. It produces two output files in `LIVE_COMPONENTS_PATH`:
+
+| Output file | Purpose | Format |
+|---|---|---|
+| `{slug}-v{version}.server.esm.js` | Loaded by the web engine via Node.js `import()` for SSR | Pure ESM, Node 20 target, readable (not minified) |
+| `{slug}-v{version}.client.esm.js` | Served to the browser for island hydration | Pure ESM, ES2020 / Chrome 90 / Firefox 88 / Safari 14, minified |
+
+Both bundles treat `react`, `react-dom`, `react/jsx-runtime`, and `@broxium/runtime` as **externals** — they are never bundled in. The web engine's import map and the browser's `@broxium/runtime` static file provide these at runtime.
+
+---
+
+## Usage
+
+```ts
+import { BrodoxCompiler } from '@broxium/compiler'
+
+const compiler = new BrodoxCompiler()
+
+const result = await compiler.compile({
+  componentId: 42,
+  slug: 'hero-banner',
+  version: '1.0.4',
+  files: [
+    {
+      path: 'App.tsx',
+      content: `
+        import { BrodoxImage } from '@broxium/runtime'
+        export default function HeroBanner({ title, image }) {
+          return (
+            <section>
+              <h1>{title}</h1>
+              <BrodoxImage src={image} alt={title} width={1280} />
+            </section>
+          )
+        }
+      `,
+    },
+  ],
+  outputDir: '/brodox-developer-drive/web-components/live-bundles',
+})
+
+console.log(result.serverJsName)  // "hero-banner-v1.0.4.server.esm.js"
+console.log(result.clientJsName)  // "hero-banner-v1.0.4.client.esm.js"
+console.log(result.serverJsPath)  // "/brodox-developer-drive/.../hero-banner-v1.0.4.server.esm.js"
+console.log(result.compiledAt)    // Date object
+```
+
+---
+
+## API
+
+### `new BrodoxCompiler()`
+
+Creates a new compiler instance. The instance is stateless and safe to reuse across multiple calls — the Brodox platform creates a single instance per process.
+
+### `compiler.compile(input): Promise<CompileOutput>`
+
+Compiles a component's source files into server and client ESM bundles.
+
+#### `CompileInput`
+
+```ts
+interface CompileInput {
+  componentId: number           // DB row ID — not used in output naming, reserved for future use
+  slug: string                  // Component slug, e.g. "hero-banner"
+  version: string               // Semver string, e.g. "1.0.4"
+  files: Array<{
+    path: string                // Relative path within the component, e.g. "App.tsx" or "utils/format.ts"
+    content: string             // Full source text
+  }>
+  outputDir: string             // Absolute path where output files are written
+}
+```
+
+#### `CompileOutput`
+
+```ts
+interface CompileOutput {
+  serverJsPath: string          // Absolute path to the server bundle
+  clientJsPath: string          // Absolute path to the client bundle
+  serverJsName: string          // Filename only: "{slug}-v{version}.server.esm.js"
+  clientJsName: string          // Filename only: "{slug}-v{version}.client.esm.js"
+  compiledAt: Date              // Timestamp of compilation
+}
+```
+
+#### Entry point resolution
+
+The compiler looks for the entry file by checking the `files` array in this priority order:
+
+```
+App.tsx → App.jsx → App.ts → App.js →
+index.tsx → index.jsx → index.ts → index.js
+```
+
+If none of these are found, the compiler throws:
+
+```
+Error: No entry file found in component files for {slug}
+```
+
+#### Temporary directory
+
+Source files are written to a temporary directory under `os.tmpdir()` before compilation. The directory is automatically cleaned up after compilation completes (or fails with an error that is re-thrown).
+
+---
+
+## `'use client'` and `'use server'` handling
+
+The two esbuild builds use custom plugins to handle React-style directives:
+
+### Server bundle — `clientStubPlugin`
+
+Any file whose first non-whitespace characters are `'use client'` or `"use client"` is replaced with a stub:
+
+```js
+import React from 'react'
+export default function ClientStub() { return null }
+export function getServerData() { return {} }
+```
+
+This means client-only sub-components silently render nothing on the server, which is correct — their interactive version will be rendered entirely by the browser.
+
+### Client bundle — `serverStubPlugin`
+
+Any file whose first non-whitespace characters are `'use server'` or `"use server"` is replaced with:
+
+```js
+export default function ServerStub() { return null }
+```
+
+Server-only code never runs in the browser.
+
+### Entry file directive
+
+The directive on the **entry file** (`App.tsx`) determines the `renderMode` stored in the Page Manifest:
+
+| Entry file starts with | `renderMode` | Server renders | Client hydrates |
+|---|---|---|---|
+| `'use client'` | `client` | No | Yes |
+| `'use server'` | `server` | Yes | No |
+| _(nothing)_ | `both` | Yes | Yes |
+
+---
+
+## External dependencies
+
+The following packages are always treated as external in both bundles:
+
+| Package | Why external |
+|---|---|
+| `react` | Provided by the web engine's import map / browser global |
+| `react-dom` | Same |
+| `react/jsx-runtime` | Same |
+| `react/jsx-dev-runtime` | Same |
+| `@broxium/runtime` | Provided by `/static/broxium-runtime.js` on the web engine |
+
+Any other import in the component source will be bundled in. This means third-party libraries like `date-fns`, `zod`, or `clsx` are embedded in the output files. Dependencies must be whitelisted in the Brodox platform's allowed-package list before they can be used in a component.
+
+---
+
+## Output file naming
+
+Output files follow a deterministic naming convention:
+
+```
+{slug}-v{version}.server.esm.js
+{slug}-v{version}.client.esm.js
+```
+
+Examples:
+
+| Slug | Version | Server file | Client file |
+|---|---|---|---|
+| `hero-banner` | `1.0.4` | `hero-banner-v1.0.4.server.esm.js` | `hero-banner-v1.0.4.client.esm.js` |
+| `product-grid` | `2.1.0` | `product-grid-v2.1.0.server.esm.js` | `product-grid-v2.1.0.client.esm.js` |
+
+Because the version is embedded in the filename, approving a new version always produces new files. The old files remain on disk for rollback purposes and are never overwritten.
+
+---
+
+## Integration with BundleService
+
+In the Brodox platform, `BrodoxCompiler` is called from `BundleService` in `sub-app-brodox-site-engine-app`. `BundleService` reads all source files from the component's `file_path` directory on disk and passes them to the compiler:
+
+```ts
+// BundleService.ts (simplified)
+import { BrodoxCompiler } from '@broxium/compiler'
+
+const compiler = new BrodoxCompiler()
+
+async function compileBothBundles(folderPath, slug, version) {
+  const files = await readComponentFiles(folderPath)  // reads all .tsx/.jsx/.ts/.js/.css/.json
+  const result = await compiler.compile({
+    componentId: 0,
+    slug,
+    version,
+    files,
+    outputDir: process.env.LIVE_COMPONENTS_PATH,
+  })
+  return result
+}
+```
+
+---
+
+## Error handling
+
+The compiler throws on any of the following conditions:
+
+| Condition | Error message |
+|---|---|
+| No entry file found | `No entry file found in component files for {slug}` |
+| esbuild server build fails | esbuild error message (TypeScript error, import not found, etc.) |
+| esbuild client build fails | esbuild error message |
+
+Errors from the server build are thrown before the client build is attempted. The temporary directory is cleaned up even when an error is thrown.
+
+When `BundleService` catches a compilation error, it blocks the component from being approved and returns the error message to the reviewer.
+
+---
+
+## Package info
+
+| | |
+|---|---|
+| Package | `@broxium/compiler` |
+| Version | `1.0.0` |
+| Formats | ESM (`dist/index.mjs`), CJS (`dist/index.js`) |
+| Types | `dist/index.d.ts` |
+| Runtime dependency | `esbuild ^0.25` |
+| Node.js requirement | 20+ |
+| Side effects | Writes files to `outputDir`, creates/removes temp directory |

package/dist/index.d.mts

@@ -7,6 +7,8 @@ interface CompileInput {
         content: string;
     }>;
     outputDir: string;
+    /** Extra node_modules directories esbuild uses to resolve React for the server bundle. */
+    nodePaths?: string[];
 }
 interface CompileOutput {
     serverJsPath: string;

package/dist/index.d.ts

@@ -7,6 +7,8 @@ interface CompileInput {
         content: string;
     }>;
     outputDir: string;
+    /** Extra node_modules directories esbuild uses to resolve React for the server bundle. */
+    nodePaths?: string[];
 }
 interface CompileOutput {
     serverJsPath: string;

package/dist/index.js

@@ -37,24 +37,37 @@ module.exports = __toCommonJS(index_exports);
 // src/compiler.ts
 var esbuild = __toESM(require("esbuild"));
 var import_promises3 = __toESM(require("fs/promises"));
-var import_node_path = __toESM(require("path"));
+var import_node_path3 = __toESM(require("path"));
 var import_node_os = __toESM(require("os"));
 var import_node_crypto = require("crypto");
 
 // src/plugins/clientStubPlugin.ts
 var import_promises = __toESM(require("fs/promises"));
+var import_node_path = __toESM(require("path"));
+function isClientFile(content, filePath) {
+  const trimmed = content.trimStart();
+  if (trimmed.startsWith("'use client'") || trimmed.startsWith('"use client"')) return true;
+  return /\.client\.[jt]sx?$/.test(filePath);
+}
+function extractName(content, filePath) {
+  const m = content.match(/export\s+default\s+function\s+(\w+)/) ?? content.match(/(?:^|\n)function\s+(\w+)/) ?? content.match(/(?:^|\n)const\s+(\w+)\s*=/);
+  const base = import_node_path.default.basename(filePath, import_node_path.default.extname(filePath)).replace(/\.client$/, "");
+  return m?.[1] ?? base;
+}
 function clientStubPlugin() {
   return {
     name: "brodox-client-stub",
     setup(build2) {
       build2.onLoad({ filter: /\.(tsx?|jsx?)$/ }, async (args) => {
         const content = await import_promises.default.readFile(args.path, "utf8");
-        const trimmed = content.trimStart();
-        if (trimmed.startsWith("'use client'") || trimmed.startsWith('"use client"')) {
+        if (isClientFile(content, args.path)) {
+          const name = extractName(content, args.path);
           return {
             contents: `
               import React from 'react'
-              export default function ClientStub() { return null }
+              function ${name}() { return null }
+              ${name}.displayName = "${name}"
+              export default ${name}
               export function getServerData() { return {} }
             `,
             loader: "jsx"
@@ -85,6 +98,114 @@ function serverStubPlugin() {
   };
 }
 
+// src/plugins/runtimeServerStubPlugin.ts
+var import_node_path2 = __toESM(require("path"));
+function runtimeServerStubPlugin(nodePaths = []) {
+  const resolveDir = nodePaths.length > 0 ? import_node_path2.default.dirname(nodePaths[0]) : process.cwd();
+  return {
+    name: "brodox-runtime-server-stub",
+    setup(build2) {
+      build2.onResolve({ filter: /^@broxium\/runtime$/ }, () => ({
+        path: "@broxium/runtime",
+        namespace: "brodox-runtime-server-stub"
+      }));
+      build2.onLoad({ filter: /.*/, namespace: "brodox-runtime-server-stub" }, () => ({
+        loader: "js",
+        resolveDir,
+        contents: `
+import { createElement, Fragment, Children } from 'react';
+var __islandSeq = 0;
+function __nextIslandId() { return 'bi-' + (++__islandSeq) + '-' + Math.random().toString(36).slice(2,7); }
+
+export function BrodoxImage({ src, alt, width, height, fill, className, style, priority, quality = 75, sizes }) {
+  const maxW = width || 1920;
+  const widths = [320, 640, 768, 1024, 1280, 1920].filter(w => w <= maxW);
+  if (!widths.length) widths.push(maxW);
+  const q = Math.min(100, Math.max(1, quality));
+  const enc = encodeURIComponent(src);
+  const optimisedSrc = '/api/image?src=' + enc + '&w=' + maxW + '&q=' + q + '&fmt=webp';
+  const srcSet = widths.map(w => '/api/image?src=' + enc + '&w=' + w + '&q=' + q + '&fmt=webp ' + w + 'w').join(', ');
+  const imgStyle = fill
+    ? Object.assign({ position: 'absolute', inset: 0, width: '100%', height: '100%', objectFit: 'cover' }, style || {})
+    : (style || {});
+  return createElement('img', {
+    src: optimisedSrc, srcSet, sizes, alt: alt || '',
+    width: fill ? undefined : width, height: fill ? undefined : height,
+    loading: priority ? 'eager' : 'lazy', decoding: 'async',
+    className, style: imgStyle,
+  });
+}
+
+export function BrodoxLink({ href, children, className, style }) {
+  return createElement('a', { href, className, style }, children);
+}
+
+export function useRouter() {
+  return { pathname: '/', params: {}, navigate: function(){}, back: function(){}, forward: function(){}, prefetch: function(){} };
+}
+
+export function useParams() { return {}; }
+
+export function BrodoxHead() { return null; }
+
+export function BrodoxFont() { return null; }
+
+export function BrodoxRouter({ children }) {
+  return createElement(Fragment, null, children);
+}
+
+/**
+ * <Client> \u2014 island boundary marker.
+ *
+ * During SSR emits an empty placeholder div plus a sibling
+ * <script type="application/json"> carrying the child's props.
+ * The IslandHydrator walks the live DOM and mounts the component from the
+ * parent bundle's __registry__ after page load.
+ */
+export function Client({ children }) {
+  var id = __nextIslandId();
+  var child = Children.only(children);
+  var compType = child.type;
+  var name = typeof compType !== 'string' && compType
+    ? (compType.displayName || compType.name || 'Unknown')
+    : 'Unknown';
+  var props = child.props || {};
+  var safeProps = JSON.stringify(props)
+    .replace(/</g, '\\u003c')
+    .replace(/>/g, '\\u003e')
+    .replace(/&/g, '\\u0026');
+  return createElement(Fragment, null,
+    createElement('div', {
+      'data-brodox-island': id,
+      'data-hydration': 'load',
+      'data-client-js': '',
+      'data-component-slug': '',
+      'data-version': '',
+      'data-component': name,
+    }),
+    createElement('script', {
+      type: 'application/json',
+      'data-brodox-props': id,
+      dangerouslySetInnerHTML: { __html: safeProps },
+    })
+  );
+}
+
+/**
+ * <Server> \u2014 semantic server-only wrapper. Transparent passthrough.
+ */
+export function Server({ children }) {
+  return createElement(Fragment, null, children);
+}
+
+/** @deprecated Use <Client> instead. */
+export var ClientRender = Client;
+`
+      }));
+    }
+  };
+}
+
 // src/compiler.ts
 var ENTRY_PRIORITY = [
   "App.tsx",
@@ -96,25 +217,53 @@ var ENTRY_PRIORITY = [
   "index.ts",
   "index.js"
 ];
-var external = [
+function isClientFile2(content, filePath) {
+  const trimmed = content.trimStart();
+  if (trimmed.startsWith("'use client'") || trimmed.startsWith('"use client"')) return true;
+  return /\.client\.[jt]sx?$/.test(filePath);
+}
+function extractClientComponentName(content, filePath) {
+  const m = content.match(/export\s+default\s+function\s+(\w+)/) ?? content.match(/export\s+default\s+(\w+)\s*[;({]/) ?? content.match(/(?:^|\n)function\s+(\w+)/);
+  const base = import_node_path3.default.basename(filePath, import_node_path3.default.extname(filePath)).replace(/\.client$/, "");
+  return m?.[1] ?? base;
+}
+var CLIENT_EXTERNALS = [
   "react",
   "react-dom",
   "react/jsx-runtime",
   "react/jsx-dev-runtime",
   "@broxium/runtime"
 ];
+function findReactNodeModules() {
+  const fsSync = require("fs");
+  try {
+    const reactPkg = require.resolve("react/package.json");
+    return [import_node_path3.default.dirname(import_node_path3.default.dirname(reactPkg))];
+  } catch {
+  }
+  let dir = process.cwd();
+  for (let i = 0; i < 10; i++) {
+    const nm = import_node_path3.default.join(dir, "node_modules");
+    const reactPkg = import_node_path3.default.join(nm, "react", "package.json");
+    if (fsSync.existsSync(reactPkg)) return [nm];
+    const parent = import_node_path3.default.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return [];
+}
 var BrodoxCompiler = class {
   async compile(input) {
-    const tmpDir = import_node_path.default.join(import_node_os.default.tmpdir(), `brodox-compile-${input.slug}-${(0, import_node_crypto.randomUUID)()}`);
+    const tmpDir = import_node_path3.default.join(import_node_os.default.tmpdir(), `brodox-compile-${input.slug}-${(0, import_node_crypto.randomUUID)()}`);
     await import_promises3.default.mkdir(tmpDir, { recursive: true });
     for (const file of input.files) {
-      const filePath = import_node_path.default.join(tmpDir, file.path);
-      await import_promises3.default.mkdir(import_node_path.default.dirname(filePath), { recursive: true });
+      const filePath = import_node_path3.default.join(tmpDir, file.path);
+      await import_promises3.default.mkdir(import_node_path3.default.dirname(filePath), { recursive: true });
       await import_promises3.default.writeFile(filePath, file.content, "utf8");
     }
     let entryPoint = null;
     for (const candidate of ENTRY_PRIORITY) {
-      const full = import_node_path.default.join(tmpDir, candidate);
+      const full = import_node_path3.default.join(tmpDir, candidate);
       try {
         await import_promises3.default.access(full);
         entryPoint = full;
@@ -128,34 +277,63 @@ var BrodoxCompiler = class {
     const safeName = `${input.slug}-v${input.version}`;
     const serverJsName = `${safeName}.server.esm.js`;
     const clientJsName = `${safeName}.client.esm.js`;
-    const serverJsPath = import_node_path.default.join(input.outputDir, serverJsName);
-    const clientJsPath = import_node_path.default.join(input.outputDir, clientJsName);
+    const serverJsPath = import_node_path3.default.join(input.outputDir, serverJsName);
+    const clientJsPath = import_node_path3.default.join(input.outputDir, clientJsName);
     await import_promises3.default.mkdir(input.outputDir, { recursive: true });
+    const serverNodePaths = [...input.nodePaths ?? [], ...findReactNodeModules()];
     await esbuild.build({
       entryPoints: [entryPoint],
       bundle: true,
       format: "esm",
       platform: "node",
       target: "node20",
-      external,
-      plugins: [clientStubPlugin()],
+      jsx: "automatic",
+      nodePaths: serverNodePaths,
+      external: [],
+      // no externals — fully self-contained
+      plugins: [clientStubPlugin(), runtimeServerStubPlugin(serverNodePaths)],
       outfile: serverJsPath,
       minify: false,
       sourcemap: false,
       define: { "process.env.NODE_ENV": '"production"' }
     });
+    const clientComponents = [];
+    for (const file of input.files) {
+      if (isClientFile2(file.content, file.path)) {
+        const name = extractClientComponentName(file.content, file.path);
+        clientComponents.push({ name, filePath: file.path });
+      }
+    }
+    let clientEntryPoint = entryPoint;
+    if (clientComponents.length > 0) {
+      const entryRelative = import_node_path3.default.relative(tmpDir, entryPoint).replace(/\\/g, "/");
+      const importLines = clientComponents.map((c, i) => `import __reg${i}__ from './${c.filePath.replace(/\\/g, "/")}';`).join("\n");
+      const registryEntries = clientComponents.map((c, i) => `  '${c.name}': __reg${i}__`).join(",\n");
+      const registryWrapper = [
+        `export { default } from './${entryRelative}';`,
+        importLines,
+        `export const __registry__ = {
+${registryEntries}
+};`
+      ].join("\n");
+      const registryEntryPath = import_node_path3.default.join(tmpDir, "__brodox_registry__.jsx");
+      await import_promises3.default.writeFile(registryEntryPath, registryWrapper, "utf8");
+      clientEntryPoint = registryEntryPath;
+    }
     await esbuild.build({
-      entryPoints: [entryPoint],
+      entryPoints: [clientEntryPoint],
       bundle: true,
       format: "esm",
       platform: "browser",
       target: ["es2020", "chrome90", "firefox88", "safari14"],
-      external,
+      jsx: "automatic",
+      external: CLIENT_EXTERNALS,
       plugins: [serverStubPlugin()],
       outfile: clientJsPath,
       minify: true,
       sourcemap: false,
-      define: { "process.env.NODE_ENV": '"production"' }
+      define: { "process.env.NODE_ENV": '"production"' },
+      banner: { js: 'import React from "react";' }
     });
     await import_promises3.default.rm(tmpDir, { recursive: true, force: true });
     return {

package/dist/index.mjs

@@ -1,24 +1,44 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
 // src/compiler.ts
 import * as esbuild from "esbuild";
 import fs3 from "fs/promises";
-import path from "path";
+import path3 from "path";
 import os from "os";
 import { randomUUID } from "crypto";
 
 // src/plugins/clientStubPlugin.ts
 import fs from "fs/promises";
+import path from "path";
+function isClientFile(content, filePath) {
+  const trimmed = content.trimStart();
+  if (trimmed.startsWith("'use client'") || trimmed.startsWith('"use client"')) return true;
+  return /\.client\.[jt]sx?$/.test(filePath);
+}
+function extractName(content, filePath) {
+  const m = content.match(/export\s+default\s+function\s+(\w+)/) ?? content.match(/(?:^|\n)function\s+(\w+)/) ?? content.match(/(?:^|\n)const\s+(\w+)\s*=/);
+  const base = path.basename(filePath, path.extname(filePath)).replace(/\.client$/, "");
+  return m?.[1] ?? base;
+}
 function clientStubPlugin() {
   return {
     name: "brodox-client-stub",
     setup(build2) {
       build2.onLoad({ filter: /\.(tsx?|jsx?)$/ }, async (args) => {
         const content = await fs.readFile(args.path, "utf8");
-        const trimmed = content.trimStart();
-        if (trimmed.startsWith("'use client'") || trimmed.startsWith('"use client"')) {
+        if (isClientFile(content, args.path)) {
+          const name = extractName(content, args.path);
           return {
             contents: `
               import React from 'react'
-              export default function ClientStub() { return null }
+              function ${name}() { return null }
+              ${name}.displayName = "${name}"
+              export default ${name}
               export function getServerData() { return {} }
             `,
             loader: "jsx"
@@ -49,6 +69,114 @@ function serverStubPlugin() {
   };
 }
 
+// src/plugins/runtimeServerStubPlugin.ts
+import path2 from "path";
+function runtimeServerStubPlugin(nodePaths = []) {
+  const resolveDir = nodePaths.length > 0 ? path2.dirname(nodePaths[0]) : process.cwd();
+  return {
+    name: "brodox-runtime-server-stub",
+    setup(build2) {
+      build2.onResolve({ filter: /^@broxium\/runtime$/ }, () => ({
+        path: "@broxium/runtime",
+        namespace: "brodox-runtime-server-stub"
+      }));
+      build2.onLoad({ filter: /.*/, namespace: "brodox-runtime-server-stub" }, () => ({
+        loader: "js",
+        resolveDir,
+        contents: `
+import { createElement, Fragment, Children } from 'react';
+var __islandSeq = 0;
+function __nextIslandId() { return 'bi-' + (++__islandSeq) + '-' + Math.random().toString(36).slice(2,7); }
+
+export function BrodoxImage({ src, alt, width, height, fill, className, style, priority, quality = 75, sizes }) {
+  const maxW = width || 1920;
+  const widths = [320, 640, 768, 1024, 1280, 1920].filter(w => w <= maxW);
+  if (!widths.length) widths.push(maxW);
+  const q = Math.min(100, Math.max(1, quality));
+  const enc = encodeURIComponent(src);
+  const optimisedSrc = '/api/image?src=' + enc + '&w=' + maxW + '&q=' + q + '&fmt=webp';
+  const srcSet = widths.map(w => '/api/image?src=' + enc + '&w=' + w + '&q=' + q + '&fmt=webp ' + w + 'w').join(', ');
+  const imgStyle = fill
+    ? Object.assign({ position: 'absolute', inset: 0, width: '100%', height: '100%', objectFit: 'cover' }, style || {})
+    : (style || {});
+  return createElement('img', {
+    src: optimisedSrc, srcSet, sizes, alt: alt || '',
+    width: fill ? undefined : width, height: fill ? undefined : height,
+    loading: priority ? 'eager' : 'lazy', decoding: 'async',
+    className, style: imgStyle,
+  });
+}
+
+export function BrodoxLink({ href, children, className, style }) {
+  return createElement('a', { href, className, style }, children);
+}
+
+export function useRouter() {
+  return { pathname: '/', params: {}, navigate: function(){}, back: function(){}, forward: function(){}, prefetch: function(){} };
+}
+
+export function useParams() { return {}; }
+
+export function BrodoxHead() { return null; }
+
+export function BrodoxFont() { return null; }
+
+export function BrodoxRouter({ children }) {
+  return createElement(Fragment, null, children);
+}
+
+/**
+ * <Client> \u2014 island boundary marker.
+ *
+ * During SSR emits an empty placeholder div plus a sibling
+ * <script type="application/json"> carrying the child's props.
+ * The IslandHydrator walks the live DOM and mounts the component from the
+ * parent bundle's __registry__ after page load.
+ */
+export function Client({ children }) {
+  var id = __nextIslandId();
+  var child = Children.only(children);
+  var compType = child.type;
+  var name = typeof compType !== 'string' && compType
+    ? (compType.displayName || compType.name || 'Unknown')
+    : 'Unknown';
+  var props = child.props || {};
+  var safeProps = JSON.stringify(props)
+    .replace(/</g, '\\u003c')
+    .replace(/>/g, '\\u003e')
+    .replace(/&/g, '\\u0026');
+  return createElement(Fragment, null,
+    createElement('div', {
+      'data-brodox-island': id,
+      'data-hydration': 'load',
+      'data-client-js': '',
+      'data-component-slug': '',
+      'data-version': '',
+      'data-component': name,
+    }),
+    createElement('script', {
+      type: 'application/json',
+      'data-brodox-props': id,
+      dangerouslySetInnerHTML: { __html: safeProps },
+    })
+  );
+}
+
+/**
+ * <Server> \u2014 semantic server-only wrapper. Transparent passthrough.
+ */
+export function Server({ children }) {
+  return createElement(Fragment, null, children);
+}
+
+/** @deprecated Use <Client> instead. */
+export var ClientRender = Client;
+`
+      }));
+    }
+  };
+}
+
 // src/compiler.ts
 var ENTRY_PRIORITY = [
   "App.tsx",
@@ -60,25 +188,53 @@ var ENTRY_PRIORITY = [
   "index.ts",
   "index.js"
 ];
-var external = [
+function isClientFile2(content, filePath) {
+  const trimmed = content.trimStart();
+  if (trimmed.startsWith("'use client'") || trimmed.startsWith('"use client"')) return true;
+  return /\.client\.[jt]sx?$/.test(filePath);
+}
+function extractClientComponentName(content, filePath) {
+  const m = content.match(/export\s+default\s+function\s+(\w+)/) ?? content.match(/export\s+default\s+(\w+)\s*[;({]/) ?? content.match(/(?:^|\n)function\s+(\w+)/);
+  const base = path3.basename(filePath, path3.extname(filePath)).replace(/\.client$/, "");
+  return m?.[1] ?? base;
+}
+var CLIENT_EXTERNALS = [
   "react",
   "react-dom",
   "react/jsx-runtime",
   "react/jsx-dev-runtime",
   "@broxium/runtime"
 ];
+function findReactNodeModules() {
+  const fsSync = __require("fs");
+  try {
+    const reactPkg = __require.resolve("react/package.json");
+    return [path3.dirname(path3.dirname(reactPkg))];
+  } catch {
+  }
+  let dir = process.cwd();
+  for (let i = 0; i < 10; i++) {
+    const nm = path3.join(dir, "node_modules");
+    const reactPkg = path3.join(nm, "react", "package.json");
+    if (fsSync.existsSync(reactPkg)) return [nm];
+    const parent = path3.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return [];
+}
 var BrodoxCompiler = class {
   async compile(input) {
-    const tmpDir = path.join(os.tmpdir(), `brodox-compile-${input.slug}-${randomUUID()}`);
+    const tmpDir = path3.join(os.tmpdir(), `brodox-compile-${input.slug}-${randomUUID()}`);
     await fs3.mkdir(tmpDir, { recursive: true });
     for (const file of input.files) {
-      const filePath = path.join(tmpDir, file.path);
-      await fs3.mkdir(path.dirname(filePath), { recursive: true });
+      const filePath = path3.join(tmpDir, file.path);
+      await fs3.mkdir(path3.dirname(filePath), { recursive: true });
       await fs3.writeFile(filePath, file.content, "utf8");
     }
     let entryPoint = null;
     for (const candidate of ENTRY_PRIORITY) {
-      const full = path.join(tmpDir, candidate);
+      const full = path3.join(tmpDir, candidate);
       try {
         await fs3.access(full);
         entryPoint = full;
@@ -92,34 +248,63 @@ var BrodoxCompiler = class {
     const safeName = `${input.slug}-v${input.version}`;
     const serverJsName = `${safeName}.server.esm.js`;
     const clientJsName = `${safeName}.client.esm.js`;
-    const serverJsPath = path.join(input.outputDir, serverJsName);
-    const clientJsPath = path.join(input.outputDir, clientJsName);
+    const serverJsPath = path3.join(input.outputDir, serverJsName);
+    const clientJsPath = path3.join(input.outputDir, clientJsName);
     await fs3.mkdir(input.outputDir, { recursive: true });
+    const serverNodePaths = [...input.nodePaths ?? [], ...findReactNodeModules()];
     await esbuild.build({
       entryPoints: [entryPoint],
       bundle: true,
       format: "esm",
       platform: "node",
       target: "node20",
-      external,
-      plugins: [clientStubPlugin()],
+      jsx: "automatic",
+      nodePaths: serverNodePaths,
+      external: [],
+      // no externals — fully self-contained
+      plugins: [clientStubPlugin(), runtimeServerStubPlugin(serverNodePaths)],
       outfile: serverJsPath,
       minify: false,
       sourcemap: false,
       define: { "process.env.NODE_ENV": '"production"' }
     });
+    const clientComponents = [];
+    for (const file of input.files) {
+      if (isClientFile2(file.content, file.path)) {
+        const name = extractClientComponentName(file.content, file.path);
+        clientComponents.push({ name, filePath: file.path });
+      }
+    }
+    let clientEntryPoint = entryPoint;
+    if (clientComponents.length > 0) {
+      const entryRelative = path3.relative(tmpDir, entryPoint).replace(/\\/g, "/");
+      const importLines = clientComponents.map((c, i) => `import __reg${i}__ from './${c.filePath.replace(/\\/g, "/")}';`).join("\n");
+      const registryEntries = clientComponents.map((c, i) => `  '${c.name}': __reg${i}__`).join(",\n");
+      const registryWrapper = [
+        `export { default } from './${entryRelative}';`,
+        importLines,
+        `export const __registry__ = {
+${registryEntries}
+};`
+      ].join("\n");
+      const registryEntryPath = path3.join(tmpDir, "__brodox_registry__.jsx");
+      await fs3.writeFile(registryEntryPath, registryWrapper, "utf8");
+      clientEntryPoint = registryEntryPath;
+    }
     await esbuild.build({
-      entryPoints: [entryPoint],
+      entryPoints: [clientEntryPoint],
       bundle: true,
       format: "esm",
       platform: "browser",
       target: ["es2020", "chrome90", "firefox88", "safari14"],
-      external,
+      jsx: "automatic",
+      external: CLIENT_EXTERNALS,
       plugins: [serverStubPlugin()],
       outfile: clientJsPath,
       minify: true,
       sourcemap: false,
-      define: { "process.env.NODE_ENV": '"production"' }
+      define: { "process.env.NODE_ENV": '"production"' },
+      banner: { js: 'import React from "react";' }
     });
     await fs3.rm(tmpDir, { recursive: true, force: true });
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@broxium/compiler",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Brodox component compiler — TSX to ESM server + client bundles",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/compiler.ts

@@ -5,6 +5,7 @@ import os from 'node:os'
 import { randomUUID } from 'node:crypto'
 import { clientStubPlugin } from './plugins/clientStubPlugin'
 import { serverStubPlugin } from './plugins/serverStubPlugin'
+import { runtimeServerStubPlugin } from './plugins/runtimeServerStubPlugin'
 import type { CompileInput, CompileOutput } from './types'
 
 const ENTRY_PRIORITY = [
@@ -12,7 +13,33 @@ const ENTRY_PRIORITY = [
   'index.tsx', 'index.jsx', 'index.ts', 'index.js',
 ]
 
-const external = [
+/**
+ * Detect client component files by directive OR naming convention.
+ * *.client.(jsx|tsx) is the preferred convention — no 'use client' needed.
+ */
+function isClientFile(content: string, filePath: string): boolean {
+  const trimmed = content.trimStart()
+  if (trimmed.startsWith("'use client'") || trimmed.startsWith('"use client"')) return true
+  return /\.client\.[jt]sx?$/.test(filePath)
+}
+
+/**
+ * Extract the default export function name from a client component file.
+ * Used to build the __registry__ export in the client bundle, keyed by the
+ * same name that clientStubPlugin sets as displayName in the server build.
+ * Strips .client from the basename fallback so "Navbar.client" → "Navbar".
+ */
+function extractClientComponentName(content: string, filePath: string): string {
+  const m = content.match(/export\s+default\s+function\s+(\w+)/)
+    ?? content.match(/export\s+default\s+(\w+)\s*[;({]/)
+    ?? content.match(/(?:^|\n)function\s+(\w+)/)
+  const base = path.basename(filePath, path.extname(filePath)).replace(/\.client$/, '')
+  return m?.[1] ?? base
+}
+
+// ── Client build externals ─────────────────────────────────────────────────
+// These are provided by the web-engine's import map in the browser.
+const CLIENT_EXTERNALS = [
   'react',
   'react-dom',
   'react/jsx-runtime',
@@ -20,6 +47,36 @@ const external = [
   '@broxium/runtime',
 ]
 
+// ── Server build: find React's node_modules directory ─────────────────────
+// The server bundle must be self-contained (no bare module resolution from
+// live-bundles/). We bundle React directly via esbuild's nodePaths so it
+// can resolve 'react' during compilation. The bundled React is embedded
+// in the output — no external resolution at runtime.
+function findReactNodeModules(): string[] {
+  const fsSync = require('fs') as typeof import('fs')
+
+  // 1. Try require.resolve from the current module (works in most CJS contexts)
+  try {
+    const reactPkg = require.resolve('react/package.json')
+    return [path.dirname(path.dirname(reactPkg))]
+  } catch {}
+
+  // 2. Walk up the directory tree from process.cwd() looking for node_modules/react.
+  //    When running inside brodox-core, react is installed there even if the
+  //    current working directory is a sub-app that doesn't list react as a dep.
+  let dir = process.cwd()
+  for (let i = 0; i < 10; i++) {
+    const nm = path.join(dir, 'node_modules')
+    const reactPkg = path.join(nm, 'react', 'package.json')
+    if (fsSync.existsSync(reactPkg)) return [nm]
+    const parent = path.dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+
+  return []
+}
+
 export class BrodoxCompiler {
   async compile(input: CompileInput): Promise<CompileOutput> {
     const tmpDir = path.join(os.tmpdir(), `brodox-compile-${input.slug}-${randomUUID()}`)
@@ -52,32 +109,85 @@ export class BrodoxCompiler {
 
     await fs.mkdir(input.outputDir, { recursive: true })
 
+    // ── Server bundle ──────────────────────────────────────────────────────
+    // Self-contained: React is bundled in via nodePaths so the bundle loads
+    // from any directory without a node_modules beside it.
+    // nodePaths = caller-provided paths (from CompileInput) + auto-detected.
+    //
+    // @broxium/runtime → replaced by inline server stubs.
+    // 'use client' files → stubbed to null (render nothing server-side).
+    const serverNodePaths = [...(input.nodePaths ?? []), ...findReactNodeModules()]
+
     await esbuild.build({
       entryPoints: [entryPoint],
-      bundle: true,
-      format: 'esm',
+      bundle:   true,
+      format:   'esm',
       platform: 'node',
-      target: 'node20',
-      external,
-      plugins: [clientStubPlugin()],
-      outfile: serverJsPath,
-      minify: false,
+      target:   'node20',
+      jsx:      'automatic',
+      nodePaths: serverNodePaths,
+      external: [],    // no externals — fully self-contained
+      plugins:  [clientStubPlugin(), runtimeServerStubPlugin(serverNodePaths)],
+      outfile:  serverJsPath,
+      minify:   false,
       sourcemap: false,
-      define: { 'process.env.NODE_ENV': '"production"' },
+      define:   { 'process.env.NODE_ENV': '"production"' },
     })
 
+    // ── Client bundle ──────────────────────────────────────────────────────
+    // React and @broxium/runtime are external — provided by the web-engine's
+    // import map (/static/react.js, /static/broxium-runtime.js).
+    // 'use server' files are stubbed to null — they never run in the browser.
+    //
+    // If the component has any "use client" files, we generate a registry
+    // wrapper entry that re-exports `default` plus a `__registry__` map.
+    // The IslandHydrator uses __registry__ to mount sub-islands created by
+    // <ClientRender> inside server-only parent components.
+    //
+    // banner: always inject `import React from 'react'` so components that
+    // call React.createElement() directly (without JSX syntax) work correctly.
+    const clientComponents: Array<{ name: string; filePath: string }> = []
+    for (const file of input.files) {
+      if (isClientFile(file.content, file.path)) {
+        const name = extractClientComponentName(file.content, file.path)
+        clientComponents.push({ name, filePath: file.path })
+      }
+    }
+
+    let clientEntryPoint = entryPoint
+    if (clientComponents.length > 0) {
+      const entryRelative = path.relative(tmpDir, entryPoint).replace(/\\/g, '/')
+      const importLines = clientComponents
+        .map((c, i) => `import __reg${i}__ from './${c.filePath.replace(/\\/g, '/')}';`)
+        .join('\n')
+      const registryEntries = clientComponents
+        .map((c, i) => `  '${c.name}': __reg${i}__`)
+        .join(',\n')
+      const registryWrapper = [
+        `export { default } from './${entryRelative}';`,
+        importLines,
+        `export const __registry__ = {\n${registryEntries}\n};`,
+      ].join('\n')
+
+      const registryEntryPath = path.join(tmpDir, '__brodox_registry__.jsx')
+      await fs.writeFile(registryEntryPath, registryWrapper, 'utf8')
+      clientEntryPoint = registryEntryPath
+    }
+
     await esbuild.build({
-      entryPoints: [entryPoint],
-      bundle: true,
-      format: 'esm',
+      entryPoints: [clientEntryPoint],
+      bundle:   true,
+      format:   'esm',
       platform: 'browser',
-      target: ['es2020', 'chrome90', 'firefox88', 'safari14'],
-      external,
-      plugins: [serverStubPlugin()],
-      outfile: clientJsPath,
-      minify: true,
+      target:   ['es2020', 'chrome90', 'firefox88', 'safari14'],
+      jsx:      'automatic',
+      external: CLIENT_EXTERNALS,
+      plugins:  [serverStubPlugin()],
+      outfile:  clientJsPath,
+      minify:   true,
       sourcemap: false,
-      define: { 'process.env.NODE_ENV': '"production"' },
+      define:   { 'process.env.NODE_ENV': '"production"' },
+      banner:   { js: 'import React from "react";' },
     })
 
     await fs.rm(tmpDir, { recursive: true, force: true })

package/src/plugins/clientStubPlugin.ts

@@ -1,5 +1,29 @@
 import type { Plugin } from 'esbuild'
 import fs from 'node:fs/promises'
+import path from 'node:path'
+
+/**
+ * Detect client components by either:
+ *   1. 'use client' / "use client" directive at the top of the file (legacy)
+ *   2. *.client.(jsx|tsx|js|ts) filename convention (preferred — no directive needed)
+ *
+ * The naming convention lets developers avoid directives entirely and rely on
+ * <Client> / <Server> wrappers from @broxium/runtime for intent.
+ */
+function isClientFile(content: string, filePath: string): boolean {
+  const trimmed = content.trimStart()
+  if (trimmed.startsWith("'use client'") || trimmed.startsWith('"use client"')) return true
+  return /\.client\.[jt]sx?$/.test(filePath)
+}
+
+function extractName(content: string, filePath: string): string {
+  const m = content.match(/export\s+default\s+function\s+(\w+)/)
+    ?? content.match(/(?:^|\n)function\s+(\w+)/)
+    ?? content.match(/(?:^|\n)const\s+(\w+)\s*=/)
+  // Strip .client from basename fallback so "Navbar.client" → "Navbar"
+  const base = path.basename(filePath, path.extname(filePath)).replace(/\.client$/, '')
+  return m?.[1] ?? base
+}
 
 export function clientStubPlugin(): Plugin {
   return {
@@ -7,12 +31,14 @@ export function clientStubPlugin(): Plugin {
     setup(build) {
       build.onLoad({ filter: /\.(tsx?|jsx?)$/ }, async (args) => {
         const content = await fs.readFile(args.path, 'utf8')
-        const trimmed = content.trimStart()
-        if (trimmed.startsWith("'use client'") || trimmed.startsWith('"use client"')) {
+        if (isClientFile(content, args.path)) {
+          const name = extractName(content, args.path)
           return {
             contents: `
               import React from 'react'
-              export default function ClientStub() { return null }
+              function ${name}() { return null }
+              ${name}.displayName = "${name}"
+              export default ${name}
               export function getServerData() { return {} }
             `,
             loader: 'jsx',

package/src/plugins/runtimeServerStubPlugin.ts

@@ -0,0 +1,136 @@
+import type { Plugin } from 'esbuild'
+import path from 'node:path'
+
+/**
+ * Replaces @broxium/runtime imports in the server bundle with server-safe
+ * inline implementations. This keeps the server bundle self-contained —
+ * no external module resolution needed from live-bundles/.
+ *
+ * BrodoxImage  → <img> pointing to /api/image (WebP, srcset, lazy)
+ * BrodoxLink   → <a href>
+ * Hooks        → server-side no-ops / static defaults
+ * Client       → island placeholder div + sibling props script
+ * Server       → transparent passthrough (semantic marker only)
+ * ClientRender → alias for Client (deprecated)
+ *
+ * WHY nodePaths is required
+ * ─────────────────────────
+ * esbuild virtual modules (custom namespace) default to resolveDir="" which
+ * disables ALL bare-specifier resolution inside them. The stub content imports
+ * from 'react', so we derive a resolveDir from the caller-supplied nodePaths:
+ * the parent directory of the first node_modules entry that contains react is
+ * used as resolveDir so that esbuild can walk up and find node_modules/react.
+ */
+export function runtimeServerStubPlugin(nodePaths: string[] = []): Plugin {
+  // Each nodePaths entry is a node_modules directory, e.g.
+  //   /path/to/brodox-web-engine/node_modules
+  // resolveDir must be the PARENT so node module resolution walks into it:
+  //   /path/to/brodox-web-engine
+  const resolveDir = nodePaths.length > 0
+    ? path.dirname(nodePaths[0])
+    : process.cwd()
+
+  return {
+    name: 'brodox-runtime-server-stub',
+    setup(build) {
+      build.onResolve({ filter: /^@broxium\/runtime$/ }, () => ({
+        path: '@broxium/runtime',
+        namespace: 'brodox-runtime-server-stub',
+      }))
+
+      build.onLoad({ filter: /.*/, namespace: 'brodox-runtime-server-stub' }, () => ({
+        loader: 'js',
+        resolveDir,
+        contents: `
+import { createElement, Fragment, Children } from 'react';
+var __islandSeq = 0;
+function __nextIslandId() { return 'bi-' + (++__islandSeq) + '-' + Math.random().toString(36).slice(2,7); }
+
+export function BrodoxImage({ src, alt, width, height, fill, className, style, priority, quality = 75, sizes }) {
+  const maxW = width || 1920;
+  const widths = [320, 640, 768, 1024, 1280, 1920].filter(w => w <= maxW);
+  if (!widths.length) widths.push(maxW);
+  const q = Math.min(100, Math.max(1, quality));
+  const enc = encodeURIComponent(src);
+  const optimisedSrc = '/api/image?src=' + enc + '&w=' + maxW + '&q=' + q + '&fmt=webp';
+  const srcSet = widths.map(w => '/api/image?src=' + enc + '&w=' + w + '&q=' + q + '&fmt=webp ' + w + 'w').join(', ');
+  const imgStyle = fill
+    ? Object.assign({ position: 'absolute', inset: 0, width: '100%', height: '100%', objectFit: 'cover' }, style || {})
+    : (style || {});
+  return createElement('img', {
+    src: optimisedSrc, srcSet, sizes, alt: alt || '',
+    width: fill ? undefined : width, height: fill ? undefined : height,
+    loading: priority ? 'eager' : 'lazy', decoding: 'async',
+    className, style: imgStyle,
+  });
+}
+
+export function BrodoxLink({ href, children, className, style }) {
+  return createElement('a', { href, className, style }, children);
+}
+
+export function useRouter() {
+  return { pathname: '/', params: {}, navigate: function(){}, back: function(){}, forward: function(){}, prefetch: function(){} };
+}
+
+export function useParams() { return {}; }
+
+export function BrodoxHead() { return null; }
+
+export function BrodoxFont() { return null; }
+
+export function BrodoxRouter({ children }) {
+  return createElement(Fragment, null, children);
+}
+
+/**
+ * <Client> — island boundary marker.
+ *
+ * During SSR emits an empty placeholder div plus a sibling
+ * <script type="application/json"> carrying the child's props.
+ * The IslandHydrator walks the live DOM and mounts the component from the
+ * parent bundle's __registry__ after page load.
+ */
+export function Client({ children }) {
+  var id = __nextIslandId();
+  var child = Children.only(children);
+  var compType = child.type;
+  var name = typeof compType !== 'string' && compType
+    ? (compType.displayName || compType.name || 'Unknown')
+    : 'Unknown';
+  var props = child.props || {};
+  var safeProps = JSON.stringify(props)
+    .replace(/</g, '\\u003c')
+    .replace(/>/g, '\\u003e')
+    .replace(/&/g, '\\u0026');
+  return createElement(Fragment, null,
+    createElement('div', {
+      'data-brodox-island': id,
+      'data-hydration': 'load',
+      'data-client-js': '',
+      'data-component-slug': '',
+      'data-version': '',
+      'data-component': name,
+    }),
+    createElement('script', {
+      type: 'application/json',
+      'data-brodox-props': id,
+      dangerouslySetInnerHTML: { __html: safeProps },
+    })
+  );
+}
+
+/**
+ * <Server> — semantic server-only wrapper. Transparent passthrough.
+ */
+export function Server({ children }) {
+  return createElement(Fragment, null, children);
+}
+
+/** @deprecated Use <Client> instead. */
+export var ClientRender = Client;
+`,
+      }))
+    },
+  }
+}

package/src/types.ts

@@ -7,6 +7,8 @@ export interface CompileInput {
     content: string
   }>
   outputDir: string
+  /** Extra node_modules directories esbuild uses to resolve React for the server bundle. */
+  nodePaths?: string[]
 }
 
 export interface CompileOutput {