@broxium/compiler 1.3.3 → 1.5.0

package/README.md

@@ -123,6 +123,60 @@ Source files are written to a temporary directory under `os.tmpdir()` before com
 
 ---
 
+## `config.json` format
+
+Every component must include a `config.json` file alongside `App.tsx`. This file defines the props exposed in the website builder's property inspector panel.
+
+**The format is a flat object** — prop name as key, field definition as value. Do not use a `name`/`slug`/`props` wrapper.
+
+```json
+{
+  "title": {
+    "label": "Title",
+    "type": "text",
+    "default": "Hello World"
+  },
+  "count": {
+    "label": "Item Count",
+    "type": "number",
+    "default": 3
+  },
+  "theme": {
+    "label": "Theme",
+    "type": "select",
+    "options": ["light", "dark"],
+    "default": "light"
+  }
+}
+```
+
+### Supported field types
+
+| `type` | Builder input | Extra keys |
+|---|---|---|
+| `text` | Text input | — |
+| `textarea` | Multiline textarea | — |
+| `url` | URL input (validated) | — |
+| `number` | Number input | — |
+| `select` | Dropdown | `options: string[]` |
+| `color` | Color picker + hex | — |
+| `boolean` | Checkbox | — |
+| `range` | Slider | `min`, `max` |
+| `brodox-*` | Custom Brodox field | varies |
+
+### Optional field keys
+
+| Key | Type | Description |
+|---|---|---|
+| `label` | `string` | Display name in the inspector panel |
+| `type` | `string` | Input type (required) |
+| `default` | `any` | Initial value when component is first dropped |
+| `render` | `"client"` \| `"server"` | Badge shown in inspector (cosmetic only) |
+
+> **Common crash:** If `config.json` is not a flat object (e.g. has a top-level `name` or `props` array key), the builder will crash with `Cannot read properties of undefined (reading 'startsWith')` when the component is dragged onto the canvas.
+
+---
+
 ## `'use client'` and `'use server'` handling
 
 The two esbuild builds use custom plugins to handle React-style directives:
@@ -153,11 +207,44 @@ Server-only code never runs in the browser.
 
 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 |
+| Entry file starts with | `renderMode` | Server renders | Client hydrates | Use when |
+|---|---|---|---|---|
+| `'use client'` | `client` | No | Yes (full) | `useState`, `useEffect`, event handlers, browser APIs |
+| `'use server'` | `server` | Yes (full) | No | Display-only, no interactivity needed |
+| _(nothing)_ | `both` | Yes | Yes (islands only) | Static shell with `<Client>` islands for interactive parts |
+
+> **Note:** These directives are **not** the same as Next.js. `'use server'` here means "exclude from client bundle" — it does not create a server action.
+
+### Common mistake — missing `'use client'`
+
+Using `useState`, `useEffect`, or any hook at the top level of the entry file **without** `'use client'` causes the web engine to crash during SSR:
+
+```
+Cannot read properties of null (reading 'useState')
+```
+
+Fix: add `'use client'` as the very first line of `App.tsx`.
+
+```jsx
+'use client';
+
+import { useState } from 'react';
+
+export default function App() {
+  const [count, setCount] = useState(0);
+  // ...
+}
+```
+
+### Sub-file directives
+
+You can split a multi-file component by marking individual files:
+
+```
+App.tsx          ← no directive (both: SSR shell + client hydration)
+├── Counter.tsx  ← 'use client'  (stubbed on server, runs in browser)
+└── DataTable.tsx← 'use server'  (stubbed in browser, runs on server)
+```
 
 ---
 
@@ -238,14 +325,46 @@ When `BundleService` catches a compilation error, it blocks the component from b
 
 ---
 
+## `runtimeServerStubPlugin` — @broxium/runtime server stubs
+
+During server bundle compilation, all `@broxium/runtime` imports are replaced
+by inline server-safe stubs so the server bundle has zero external dependencies.
+
+Key stub behaviours:
+
+| Export | Server stub renders |
+|---|---|
+| `BrodoxLink` | `<a data-brodox-link href={href}>` — the `data-brodox-link` attribute is required for the shell's click interceptor |
+| `BrodoxImage` | `<img src="/api/image?...">` with srcset, or raw `src` if `direct={true}` |
+| `Client` | Empty placeholder div + sibling `<script type="application/json">` with props |
+| `Server` | Transparent passthrough (Fragment) |
+| `useRouter`, `useParams` | Static no-ops (return empty objects) |
+| `BrodoxHead`, `BrodoxFont` | null |
+
+**Important:** If you compile a component and the rendered `<a>` tags do not
+have `data-brodox-link`, the shell will not intercept clicks on those links and
+the browser will do a full page reload. This was fixed in v1.3.2 — ensure all
+projects use `@broxium/compiler@^1.3.2` or later. Existing pre-1.3.2 server
+bundles must be patched manually or recompiled.
+
+---
+
 ## Package info
 
 | | |
 |---|---|
 | Package | `@broxium/compiler` |
-| Version | `1.0.0` |
+| Version | `1.3.3` |
 | 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 |
+
+## Changelog
+
+| Version | Change |
+|---|---|
+| 1.3.3 | `BrodoxImage` stub: added `direct` prop support |
+| 1.3.2 | `BrodoxLink` stub: added `data-brodox-link` attribute |
+| 1.3.1 | Initial public release |

package/dist/index.d.mts

@@ -13,8 +13,12 @@ interface CompileInput {
 interface CompileOutput {
     serverJsPath: string;
     clientJsPath: string;
+    /** Compiled CSS bundle path, or null if no CSS files were imported. */
+    cssPath: string | null;
     serverJsName: string;
     clientJsName: string;
+    /** CSS bundle filename, or null if no CSS files were imported. */
+    cssName: string | null;
     compiledAt: Date;
 }
 

package/dist/index.d.ts

@@ -13,8 +13,12 @@ interface CompileInput {
 interface CompileOutput {
     serverJsPath: string;
     clientJsPath: string;
+    /** Compiled CSS bundle path, or null if no CSS files were imported. */
+    cssPath: string | null;
     serverJsName: string;
     clientJsName: string;
+    /** CSS bundle filename, or null if no CSS files were imported. */
+    cssName: string | null;
     compiledAt: Date;
 }
 

package/dist/index.js

@@ -154,9 +154,29 @@ export function useRouter() {
 
 export function useParams() { return {}; }
 
-export function BrodoxHead() { return null; }
+export function BrodoxHead({ title, description }) {
+  if (title && typeof globalThis.__brodoxCollectHead === 'function')
+    globalThis.__brodoxCollectHead({ type: 'title', props: { content: title } });
+  if (description && typeof globalThis.__brodoxCollectHead === 'function')
+    globalThis.__brodoxCollectHead({ type: 'meta', props: { name: 'description', content: description } });
+  return null;
+}
 
-export function BrodoxFont() { return null; }
+export function BrodoxFont({ href, family, weights, display }) {
+  weights = weights || [400, 700];
+  display = display || 'swap';
+  var url = href;
+  if (!url && family) {
+    url = 'https://fonts.googleapis.com/css2?family='
+      + encodeURIComponent(family) + ':wght@' + weights.join(';') + '&display=' + display;
+  }
+  if (url && typeof globalThis.__brodoxCollectHead === 'function') {
+    globalThis.__brodoxCollectHead({ type: 'link', props: { rel: 'preconnect', href: 'https://fonts.googleapis.com' } });
+    globalThis.__brodoxCollectHead({ type: 'link', props: { rel: 'preconnect', href: 'https://fonts.gstatic.com', crossOrigin: 'anonymous' } });
+    globalThis.__brodoxCollectHead({ type: 'link', props: { rel: 'stylesheet', href: url } });
+  }
+  return null;
+}
 
 export function BrodoxRouter({ children }) {
   return createElement(Fragment, null, children);
@@ -170,7 +190,7 @@ export function BrodoxRouter({ children }) {
  * The IslandHydrator walks the live DOM and mounts the component from the
  * parent bundle's __registry__ after page load.
  */
-export function Client({ children }) {
+export function Client({ children, hydration = 'load' }) {
   var id = __nextIslandId();
   var child = Children.only(children);
   var compType = child.type;
@@ -185,13 +205,13 @@ export function Client({ children }) {
   return createElement(Fragment, null,
     createElement('div', {
       'data-brodox-island': id,
-      'data-hydration': 'load',
+      'data-hydration': hydration,
       'data-client-js': '',
       'data-component-slug': '',
       'data-version': '',
       'data-component': name,
     }),
-    createElement('script', {
+    hydration === 'none' ? null : createElement('script', {
       type: 'application/json',
       'data-brodox-props': id,
       dangerouslySetInnerHTML: { __html: safeProps },
@@ -303,7 +323,9 @@ var BrodoxCompiler = class {
       outfile: serverJsPath,
       minify: false,
       sourcemap: false,
-      define: { "process.env.NODE_ENV": '"production"' }
+      define: { "process.env.NODE_ENV": '"production"' },
+      loader: { ".css": "text" }
+      // CSS imports return empty string in server bundle
     });
     const clientComponents = [];
     for (const file of input.files) {
@@ -341,14 +363,47 @@ ${registryEntries}
       minify: true,
       sourcemap: false,
       define: { "process.env.NODE_ENV": '"production"' },
-      banner: { js: 'import React from "react";' }
+      banner: { js: 'import React from "react";' },
+      loader: { ".css": "text" }
+      // CSS imports return the CSS string (injected via BrodoxHead or style tag)
     });
+    const hasCss = input.files.some((f) => /\.css$/.test(f.path));
+    const cssName = hasCss ? `${safeName}.css` : null;
+    const cssPath = hasCss ? import_node_path3.default.join(input.outputDir, cssName) : null;
+    if (hasCss && cssPath) {
+      try {
+        await esbuild.build({
+          entryPoints: [entryPoint],
+          bundle: true,
+          format: "esm",
+          platform: "browser",
+          jsx: "automatic",
+          external: CLIENT_EXTERNALS,
+          plugins: [serverStubPlugin()],
+          outfile: cssPath.replace(/\.css$/, ".css.tmp.js"),
+          // esbuild needs a JS outfile
+          minify: true,
+          sourcemap: false,
+          define: { "process.env.NODE_ENV": '"production"' },
+          loader: { ".css": "css" }
+        });
+        const defaultCssOut = cssPath.replace(/\.css$/, ".css.tmp.css");
+        try {
+          await import_promises3.default.rename(defaultCssOut, cssPath);
+        } catch {
+        }
+        await import_promises3.default.rm(cssPath.replace(/\.css$/, ".css.tmp.js"), { force: true });
+      } catch {
+      }
+    }
     await import_promises3.default.rm(tmpDir, { recursive: true, force: true });
     return {
       serverJsPath,
       clientJsPath,
+      cssPath,
       serverJsName,
       clientJsName,
+      cssName,
       compiledAt: /* @__PURE__ */ new Date()
     };
   }

package/dist/index.mjs

@@ -125,9 +125,29 @@ export function useRouter() {
 
 export function useParams() { return {}; }
 
-export function BrodoxHead() { return null; }
+export function BrodoxHead({ title, description }) {
+  if (title && typeof globalThis.__brodoxCollectHead === 'function')
+    globalThis.__brodoxCollectHead({ type: 'title', props: { content: title } });
+  if (description && typeof globalThis.__brodoxCollectHead === 'function')
+    globalThis.__brodoxCollectHead({ type: 'meta', props: { name: 'description', content: description } });
+  return null;
+}
 
-export function BrodoxFont() { return null; }
+export function BrodoxFont({ href, family, weights, display }) {
+  weights = weights || [400, 700];
+  display = display || 'swap';
+  var url = href;
+  if (!url && family) {
+    url = 'https://fonts.googleapis.com/css2?family='
+      + encodeURIComponent(family) + ':wght@' + weights.join(';') + '&display=' + display;
+  }
+  if (url && typeof globalThis.__brodoxCollectHead === 'function') {
+    globalThis.__brodoxCollectHead({ type: 'link', props: { rel: 'preconnect', href: 'https://fonts.googleapis.com' } });
+    globalThis.__brodoxCollectHead({ type: 'link', props: { rel: 'preconnect', href: 'https://fonts.gstatic.com', crossOrigin: 'anonymous' } });
+    globalThis.__brodoxCollectHead({ type: 'link', props: { rel: 'stylesheet', href: url } });
+  }
+  return null;
+}
 
 export function BrodoxRouter({ children }) {
   return createElement(Fragment, null, children);
@@ -141,7 +161,7 @@ export function BrodoxRouter({ children }) {
  * The IslandHydrator walks the live DOM and mounts the component from the
  * parent bundle's __registry__ after page load.
  */
-export function Client({ children }) {
+export function Client({ children, hydration = 'load' }) {
   var id = __nextIslandId();
   var child = Children.only(children);
   var compType = child.type;
@@ -156,13 +176,13 @@ export function Client({ children }) {
   return createElement(Fragment, null,
     createElement('div', {
       'data-brodox-island': id,
-      'data-hydration': 'load',
+      'data-hydration': hydration,
       'data-client-js': '',
       'data-component-slug': '',
       'data-version': '',
       'data-component': name,
     }),
-    createElement('script', {
+    hydration === 'none' ? null : createElement('script', {
       type: 'application/json',
       'data-brodox-props': id,
       dangerouslySetInnerHTML: { __html: safeProps },
@@ -274,7 +294,9 @@ var BrodoxCompiler = class {
       outfile: serverJsPath,
       minify: false,
       sourcemap: false,
-      define: { "process.env.NODE_ENV": '"production"' }
+      define: { "process.env.NODE_ENV": '"production"' },
+      loader: { ".css": "text" }
+      // CSS imports return empty string in server bundle
     });
     const clientComponents = [];
     for (const file of input.files) {
@@ -312,14 +334,47 @@ ${registryEntries}
       minify: true,
       sourcemap: false,
       define: { "process.env.NODE_ENV": '"production"' },
-      banner: { js: 'import React from "react";' }
+      banner: { js: 'import React from "react";' },
+      loader: { ".css": "text" }
+      // CSS imports return the CSS string (injected via BrodoxHead or style tag)
     });
+    const hasCss = input.files.some((f) => /\.css$/.test(f.path));
+    const cssName = hasCss ? `${safeName}.css` : null;
+    const cssPath = hasCss ? path3.join(input.outputDir, cssName) : null;
+    if (hasCss && cssPath) {
+      try {
+        await esbuild.build({
+          entryPoints: [entryPoint],
+          bundle: true,
+          format: "esm",
+          platform: "browser",
+          jsx: "automatic",
+          external: CLIENT_EXTERNALS,
+          plugins: [serverStubPlugin()],
+          outfile: cssPath.replace(/\.css$/, ".css.tmp.js"),
+          // esbuild needs a JS outfile
+          minify: true,
+          sourcemap: false,
+          define: { "process.env.NODE_ENV": '"production"' },
+          loader: { ".css": "css" }
+        });
+        const defaultCssOut = cssPath.replace(/\.css$/, ".css.tmp.css");
+        try {
+          await fs3.rename(defaultCssOut, cssPath);
+        } catch {
+        }
+        await fs3.rm(cssPath.replace(/\.css$/, ".css.tmp.js"), { force: true });
+      } catch {
+      }
+    }
     await fs3.rm(tmpDir, { recursive: true, force: true });
     return {
       serverJsPath,
       clientJsPath,
+      cssPath,
       serverJsName,
       clientJsName,
+      cssName,
       compiledAt: /* @__PURE__ */ new Date()
     };
   }

package/package.json

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