@withl5e/l5e 0.2.2 → 0.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withl5e/l5e",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "HTML-first SSR MPA framework with loaders, middleware, islands, actions, swap, SEO and cache controls.",
   "type": "module",
   "license": "MIT",
@@ -16,66 +16,82 @@
   "sideEffects": false,
   "exports": {
     ".": {
+      "development": "./src/core/index.ts",
       "types": "./src/core/index.ts",
       "default": "./dist/index.js"
     },
     "./jsx-runtime": {
+      "development": "./src/core/jsx-runtime.ts",
       "types": "./src/core/jsx-runtime.ts",
       "default": "./dist/jsx-runtime.js"
     },
     "./vite-plugin": {
+      "development": "./src/core/vite-plugin.ts",
       "types": "./src/core/vite-plugin.ts",
       "default": "./dist/vite-plugin.js"
     },
     "./server": {
+      "development": "./src/core/server.ts",
       "types": "./src/core/server.ts",
       "default": "./dist/server.js"
     },
     "./entry-server": {
+      "development": "./src/core/entry-server.ts",
       "types": "./src/core/entry-server.d.ts",
       "default": "./dist/entry-server.js"
     },
     "./middleware": {
+      "development": "./src/middleware/index.ts",
       "types": "./src/middleware/index.ts",
       "default": "./dist/middleware.js"
     },
     "./tooltip": {
+      "development": "./src/tooltip/index.ts",
       "types": "./src/tooltip/index.ts",
       "default": "./dist/tooltip.js"
     },
     "./jsx-types": {
+      "development": "./src/core/jsx-types.d.ts",
       "types": "./src/core/jsx-types.d.ts",
       "default": "./src/core/jsx-types.d.ts"
     },
     "./seo": {
+      "development": "./src/seo/index.ts",
       "types": "./src/seo/index.ts",
       "default": "./dist/seo.js"
     },
     "./swap": {
+      "development": "./src/swap/index.ts",
       "types": "./src/swap/index.ts",
       "default": "./dist/swap.js"
     },
     "./swap/server": {
+      "development": "./src/swap/server.ts",
       "types": "./src/swap/server.ts",
       "default": "./dist/swap/server.js"
     },
     "./action": {
+      "development": "./src/action/index.ts",
       "types": "./src/action/index.ts",
       "default": "./dist/action.js"
     },
     "./island": {
+      "development": "./src/island/index.ts",
       "types": "./src/island/index.ts",
       "default": "./dist/island.js"
     },
     "./island/client": {
+      "development": "./src/island/client.ts",
       "types": "./src/island/client.ts",
       "default": "./dist/island/client.js"
     },
     "./island/runtime": {
+      "development": "./src/island/runtime.ts",
       "types": "./src/island/runtime.ts",
       "default": "./dist/island/runtime.js"
     },
     "./router": {
+      "development": "./src/router/index.ts",
       "types": "./src/router/index.ts",
       "default": "./dist/router.js"
     }
@@ -83,11 +99,13 @@
   "dependencies": {
     "@floating-ui/dom": "1.7.4",
     "compression": "^1.7.4",
+    "cookie": "^1.1.1",
     "esbuild": "^0.24.2",
     "express": "^4.18.2",
     "path-to-regexp": "^8.4.2",
     "request-ip": "^3.3.0",
     "rollup": "^4.0.0",
+    "serialize-javascript": "^7.0.5",
     "sirv": "^2.0.3"
   },
   "peerDependencies": {
@@ -100,6 +118,7 @@
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "@types/request-ip": "0.0.41",
+    "@types/serialize-javascript": "^5.0.4",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "typescript": "^5.6.3",

package/src/core/entry-server.ts

@@ -1,4 +1,5 @@
 /// <reference path="./jsx-types.d.ts" />
+import serialize from 'serialize-javascript';
 import { MetadataRenderer } from '../seo/generateMetadata';
 import type { Metadata } from '../seo/types';
 import {
@@ -17,6 +18,7 @@ import {
   getHeadContent,
   getIslandEntries,
   getSchemas,
+  getSsrIslands,
   jsxFactory as h,
   Head,
   pushMetadata,
@@ -33,6 +35,69 @@ import routeHandler from 'virtual:l5e-route';
 import { globalLoader } from 'virtual:l5e-global-loader';
 // @ts-ignore - Virtual modules provided by Vite plugin
 export { loadMiddleware } from 'virtual:l5e-middleware';
+// @ts-ignore - Virtual modules provided by Vite plugin
+import { islandModules } from 'virtual:l5e-islands';
+
+/**
+ * Fill `ssr` island placeholders with server-rendered HTML.
+ *
+ * During the synchronous render pass, each `<ClientIsland ssr>` emits a unique
+ * token (as `<!--token-->` body + `data-island-ssr="token"`). Here — after the
+ * pass — we can `await import()` the actual React component and renderToString it,
+ * then string-replace the token. Only islands present on this page are imported.
+ *
+ * On failure we strip both the token and the `data-island-ssr` attribute so the
+ * client cleanly falls back to a client-only mount (no hydration mismatch).
+ */
+async function fillSsrIslands(htmlBody: string): Promise<string> {
+  const pending = getSsrIslands();
+  if (pending.length === 0) return htmlBody;
+
+  let renderToString: (el: any) => string;
+  let createElement: (type: any, props: any) => any;
+  try {
+    [{ renderToString }, { createElement }] = await Promise.all([
+      import('react-dom/server'),
+      import('react'),
+    ]);
+  } catch (err) {
+    console.error('[l5e-island] SSR requires react-dom/server + react:', err);
+    // Strip every pending token/attr → client-only fallback for all.
+    for (const island of pending) {
+      htmlBody = htmlBody
+        .replace(`<!--${island.token}-->`, '')
+        .replace(` data-island-ssr="${island.token}"`, '');
+    }
+    return htmlBody;
+  }
+
+  for (const island of pending) {
+    try {
+      const loader = islandModules['/' + island.src];
+      if (!loader) {
+        throw new Error(`island module not found in glob: /${island.src}`);
+      }
+      const mod: any = await loader();
+      const Component = mod[island.name] ?? mod.default;
+      if (!Component) {
+        throw new Error(`no export "${island.name}" or default in /${island.src}`);
+      }
+      const out = renderToString(createElement(Component, island.props));
+      // Replacer fn (not a string) so `$`-sequences in `out` (e.g. "$&", "$$")
+      // aren't interpreted as special replacement patterns.
+      htmlBody = htmlBody
+        .replace(`<!--${island.token}-->`, () => out)
+        .replace(`data-island-ssr="${island.token}"`, 'data-island-ssr="1"');
+    } catch (err) {
+      console.error(`[l5e-island] Failed to SSR island "${island.name}":`, err);
+      htmlBody = htmlBody
+        .replace(`<!--${island.token}-->`, '')
+        .replace(` data-island-ssr="${island.token}"`, '');
+    }
+  }
+
+  return htmlBody;
+}
 
 export interface RawResponse {
   body: string | Buffer;
@@ -323,7 +388,9 @@ export async function render(url: string, requestInfo: RequestInfo = {}): Promis
       // Auto-render schemas vào headRegistry
       const schemas = getSchemas();
       schemas.forEach((schema) => {
-        const schemaJson = JSON.stringify(schema);
+        // serialize-javascript escapes HTML-sensitive chars (<, >, &, U+2028/2029)
+        // so schema values cannot break out of the <script> block (XSS).
+        const schemaJson = serialize(schema, { isJSON: true });
         // Push schema vào headRegistry thông qua Head component
         // Head component chỉ push vào registry, không cần renderJsxToHtmlString
         Head({
@@ -336,7 +403,9 @@ export async function render(url: string, requestInfo: RequestInfo = {}): Promis
       });
 
       // Render component (có thể có Head components khác)
-      const htmlBody = renderJsxToHtmlString(h(Component, props));
+      let htmlBody = renderJsxToHtmlString(h(Component, props));
+      // Fill any opt-in `ssr` island placeholders with server-rendered React HTML.
+      htmlBody = await fillSsrIslands(htmlBody);
       const clientEntries = getClientJsEntries();
       const cssEntries = getCssEntries();
       const islandEntries = getIslandEntries();
@@ -379,13 +448,19 @@ export async function render(url: string, requestInfo: RequestInfo = {}): Promis
         return await renderErrorView(err);
       }
 
-      // For other errors, convert to ServiceUnavailableException
+      // For other (unexpected) errors, convert to ServiceUnavailableException.
+      // Intentional HttpExceptions above keep their developer-authored message;
+      // but an unexpected error's raw message/stack must not leak to the client
+      // in production (it can carry internals, secrets, etc.). Dev keeps detail.
       console.error(`Failed to render:`, err);
-      const serviceError = new ServiceUnavailableException(err.message || 'Internal Server Error', {
-        originalError: err.name,
-        stack: err.stack,
-        timestamp: new Date().toISOString(),
-      });
+      const isProduction = process.env.NODE_ENV === 'production';
+      const serviceError = isProduction
+        ? new ServiceUnavailableException('Internal Server Error')
+        : new ServiceUnavailableException(err.message || 'Internal Server Error', {
+            originalError: err.name,
+            stack: err.stack,
+            timestamp: new Date().toISOString(),
+          });
       return await renderErrorView(serviceError);
     }
   }, requestInfo);

package/src/core/index.ts

@@ -30,9 +30,7 @@ export { coreVite } from './vite-plugin';
 export {
   createContext,
   defineMiddleware,
-  isLocalsSerializable,
   sequence,
-  trySerializeLocals,
   type CreateContext,
   type MiddlewareContext,
   type MiddlewareHandler,

package/src/core/jsx-runtime.ts

@@ -65,10 +65,23 @@ interface IslandEntry {
   name: string; // "Counter" — export name
 }
 
+/**
+ * A pending server-side render request for an `ssr` island.
+ * Collected during the synchronous render pass and filled in afterwards by
+ * entry-server (which can `await import()` the component + call renderToString).
+ */
+interface SsrIslandEntry {
+  token: string; // unique placeholder token embedded in the HTML body
+  src: string; // "src/views/.../Counter.tsx" — manifest-compatible path (no leading slash)
+  name: string; // "Counter" — export name
+  props: Record<string, any>;
+}
+
 interface RenderContext {
   clientJsRegistry: Array<{ path: string; from: string }>;
   cssRegistry: Array<{ path: string; from: string }>;
   islandRegistry: IslandEntry[];
+  ssrIslands: SsrIslandEntry[];
   cacheTags: Set<string>;
   headRegistry: HeadEntry[]; // Thay vì JSXChild[]
   metadataStack: Metadata[]; // Stack để track metadata hierarchy
@@ -85,6 +98,7 @@ function createRequestContext(requestInfo: RequestInfo): RenderContext {
     clientJsRegistry: [],
     cssRegistry: [],
     islandRegistry: [],
+    ssrIslands: [],
     cacheTags: new Set(),
     headRegistry: [],
     metadataStack: [],
@@ -119,6 +133,25 @@ export function getIslandEntries(): IslandEntry[] {
   return context.islandRegistry.slice();
 }
 
+/**
+ * Register a pending SSR island render. Returns a unique placeholder token that
+ * the caller embeds (as raw HTML) in the island's body. entry-server replaces
+ * the token with the server-rendered component HTML after the sync render pass.
+ */
+export function registerSsrIsland(src: string, name: string, props: Record<string, any>): string {
+  const renderContext = renderStore.getStore();
+  if (!renderContext) return '';
+  const token = `__L5E_SSR_${renderContext.ssrIslands.length}__`;
+  renderContext.ssrIslands.push({ token, src, name, props });
+  return token;
+}
+
+export function getSsrIslands(): SsrIslandEntry[] {
+  const context = renderStore.getStore();
+  if (!context) return [];
+  return context.ssrIslands.slice();
+}
+
 export function useCss(path: string): string {
   if (typeof path === 'string' && path.length > 0) {
     const renderContext = renderStore.getStore();

package/src/core/render.ts

@@ -42,6 +42,39 @@ function classList(input: unknown): string {
   return '';
 }
 
+// Attribute-name validation, ported verbatim from React's react-dom
+// (DOMProperty.js `isAttributeNameSafe`). Untrusted spread props can carry
+// keys like `blah" onclick="x` or `></div><script>…`; if such a key were
+// written as `${key}="…"` it would inject new attributes / break out of the
+// tag. Names that don't match this grammar are dropped instead of emitted.
+const ATTRIBUTE_NAME_START_CHAR =
+  ':A-Z_a-z\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u02FF\\u0370-\\u037D\\u037F-\\u1FFF\\u200C-\\u200D\\u2070-\\u218F\\u2C00-\\u2FEF\\u3001-\\uD7FF\\uF900-\\uFDCF\\uFDF0-\\uFFFD';
+const ATTRIBUTE_NAME_CHAR =
+  ATTRIBUTE_NAME_START_CHAR + '\\-.0-9\\u00B7\\u0300-\\u036F\\u203F-\\u2040';
+const VALID_ATTRIBUTE_NAME_REGEX = new RegExp(
+  '^[' + ATTRIBUTE_NAME_START_CHAR + '][' + ATTRIBUTE_NAME_CHAR + ']*$',
+);
+const validatedAttributeNameCache: Record<string, boolean> = {};
+const illegalAttributeNameCache: Record<string, boolean> = {};
+
+export function isAttributeNameSafe(attributeName: string): boolean {
+  if (Object.prototype.hasOwnProperty.call(validatedAttributeNameCache, attributeName)) {
+    return true;
+  }
+  if (Object.prototype.hasOwnProperty.call(illegalAttributeNameCache, attributeName)) {
+    return false;
+  }
+  if (VALID_ATTRIBUTE_NAME_REGEX.test(attributeName)) {
+    validatedAttributeNameCache[attributeName] = true;
+    return true;
+  }
+  illegalAttributeNameCache[attributeName] = true;
+  if (process.env.NODE_ENV !== 'production') {
+    console.error('Invalid attribute name: `%s`', attributeName);
+  }
+  return false;
+}
+
 export function escapeProp(value: string): string {
   return value
     .replaceAll('&', '&amp;')
@@ -86,6 +119,9 @@ function renderAttributes(props?: Record<string, any>): string {
         key !== 'cacheTag',
     )
     .map(([key, value]) => {
+      // Drop attribute names that could break out of the tag (injection guard).
+      if (!isAttributeNameSafe(key)) return '';
+
       // HTML standard behavior with function execution support
       if (value === false || value === null || value === undefined) return '';
       if (value === true) return key;

package/src/core/request.ts

@@ -1,18 +1,19 @@
+import { parse as parseCookieHeader } from 'cookie';
 import type { Request } from 'express';
 
 export function parseCookies(cookieHeader?: string): Record<string, string> {
   if (!cookieHeader) return {};
 
-  return cookieHeader.split(';').reduce(
-    (cookies, cookie) => {
-      const [name, ...rest] = cookie.split('=');
-      if (name && rest.length > 0) {
-        cookies[name.trim()] = decodeURIComponent(rest.join('=').trim());
-      }
-      return cookies;
-    },
-    {} as Record<string, string>,
-  );
+  // `cookie.parse` decodes values safely (malformed %-sequences fall back to the
+  // raw value instead of throwing) and ignores prototype keys.
+  const parsed = parseCookieHeader(cookieHeader);
+  const cookies: Record<string, string> = {};
+  for (const [name, value] of Object.entries(parsed)) {
+    if (value !== undefined) {
+      cookies[name] = value;
+    }
+  }
+  return cookies;
 }
 
 export function createHeadersFromExpressRequest(req: Request): Headers {

package/src/core/server.ts

@@ -4,10 +4,12 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import requestIp from 'request-ip';
+import serialize from 'serialize-javascript';
 import type { ViteDevServer } from 'vite';
 import { createContext, type MiddlewareHandler, type RewritePayload } from '../middleware';
 import { bundleCss, bundleScripts, getBundledFile } from './bundler';
 import type { RenderResult, RequestInfo } from './entry-server';
+import { escapeProp } from './render';
 import { createHeadersFromExpressRequest, parseCookies } from './request';
 
 export interface ServerOptions {
@@ -27,15 +29,18 @@ export interface ServerContext {
 /**
  * Apply or replace lang attribute on <html> tag
  */
-function applyHtmlLang(template: string, lang: string): string {
+export function applyHtmlLang(template: string, lang: string): string {
+  // Escape so a loader-supplied lang (possibly derived from user input) cannot
+  // break out of the attribute / <html> tag (XSS). escapeProp handles ", <, >, &.
+  const safeLang = escapeProp(lang);
   return template.replace(/<html\b([^>]*)>/i, (match, attrs) => {
     // Check if lang already exists
     if (/\blang\s*=/i.test(attrs)) {
-      // Replace existing lang value
-      return match.replace(/lang\s*=\s*"[^"]*"/i, `lang="${lang}"`);
+      // Replace existing lang value (function replacer avoids $-pattern issues)
+      return match.replace(/lang\s*=\s*"[^"]*"/i, () => `lang="${safeLang}"`);
     } else {
       // Add lang attribute
-      return `<html lang="${lang}"${attrs}>`;
+      return `<html lang="${safeLang}"${attrs}>`;
     }
   });
 }
@@ -312,7 +317,7 @@ async function createPageResponse({
         }
       }
       if (Object.keys(islandMap).length > 0) {
-        islandRegistryScript = `<script>window.__L5E_ISLANDS__=${JSON.stringify(islandMap)}</script>`;
+        islandRegistryScript = `<script>window.__L5E_ISLANDS__=${serialize(islandMap)}</script>`;
       }
     }
 
@@ -341,7 +346,7 @@ async function createPageResponse({
       for (const island of islandEntries) {
         islandMap[island.key] = `/${island.src}`;
       }
-      islandRegistryScript = `<script>window.__L5E_ISLANDS__=${JSON.stringify(islandMap)}</script>`;
+      islandRegistryScript = `<script>window.__L5E_ISLANDS__=${serialize(islandMap)}</script>`;
     }
   }
 
@@ -463,7 +468,7 @@ export async function createServer(options: ServerOptions = {}): Promise<ServerC
           res.send(bundledFile.content);
         } catch (e: any) {
           console.error('[server] Error serving bundled file:', e);
-          res.status(500).end(e.message);
+          res.status(500).end('Internal server error');
         }
       },
     );
@@ -558,6 +563,14 @@ export async function createServer(options: ServerOptions = {}): Promise<ServerC
         return res.status(404).send('Action not found');
       }
 
+      // Enforce the action's declared HTTP method. Previously `app.all` accepted
+      // any method and `action.method` was ignored, so a state-changing POST
+      // action could be triggered via GET (e.g. <img src>) — a CSRF vector.
+      const allowedMethod = (action.method || 'GET').toUpperCase();
+      if (req.method.toUpperCase() !== allowedMethod) {
+        return res.status(405).set('Allow', allowedMethod).send('Method Not Allowed');
+      }
+
       // Build RequestInfo (same pattern as HTML handler)
       const fullUrl = `${req.protocol}://${req.get('host')}${req.originalUrl}`;
       const urlObject = new URL(fullUrl);
@@ -687,8 +700,9 @@ export async function createServer(options: ServerOptions = {}): Promise<ServerC
       await sendWebResponse(req, res, response);
     } catch (e: any) {
       vite?.ssrFixStacktrace?.(e);
-      console.log(e.stack);
-      res.status(500).end(e.stack);
+      console.error(e.stack);
+      // Never leak stack traces to the client in production (info disclosure).
+      res.status(500).end(isProduction ? 'Internal Server Error' : e.stack);
     }
   });
 

package/src/core/vite-plugin.ts

@@ -16,9 +16,19 @@ const VIRTUAL_L5E_ROUTE = 'virtual:l5e-route';
 const VIRTUAL_L5E_SSR_ENTRY = 'virtual:l5e-ssr-entry';
 const VIRTUAL_L5E_GLOBAL_LOADER = 'virtual:l5e-global-loader';
 const VIRTUAL_L5E_ISLAND_STRATEGIES = 'virtual:l5e-island-strategies';
+const VIRTUAL_L5E_ISLANDS = 'virtual:l5e-islands';
 const VIRTUAL_L5E_ACTIONS = 'virtual:l5e-actions';
 const VIRTUAL_L5E_MIDDLEWARE = 'virtual:l5e-middleware';
 
+/**
+ * Vite's built-in env vars on `import.meta.env`. These are statically replaced
+ * by Vite itself (DEV/PROD/SSR are booleans, MODE/BASE_URL strings), so the SSR
+ * `import.meta.env.* -> process.env.*` rewrite must skip them — otherwise it
+ * clobbers Vite defaults (e.g. `import.meta.env.DEV` would become the undefined
+ * `process.env.DEV`).
+ */
+const VITE_RESERVED_ENV = new Set(['MODE', 'BASE_URL', 'PROD', 'DEV', 'SSR', 'LEGACY']);
+
 /**
  * Recursively scan directory for .tsx and .ts files
  */
@@ -544,6 +554,9 @@ export function coreVite(): Plugin {
       if (id === VIRTUAL_L5E_ISLAND_STRATEGIES) {
         return '\0' + VIRTUAL_L5E_ISLAND_STRATEGIES;
       }
+      if (id === VIRTUAL_L5E_ISLANDS) {
+        return '\0' + VIRTUAL_L5E_ISLANDS;
+      }
       if (id === VIRTUAL_L5E_ACTIONS) {
         return '\0' + VIRTUAL_L5E_ACTIONS;
       }
@@ -671,6 +684,8 @@ export function coreVite(): Plugin {
         transformedCode = transformedCode.replace(
           /import\.meta\.env\.([a-zA-Z_][a-zA-Z0-9_]*)/g,
           (match, varName) => {
+            // Leave Vite's built-in env vars for Vite to handle.
+            if (VITE_RESERVED_ENV.has(varName)) return match;
             hasChanges = true;
             return `process.env.${varName}`;
           },
@@ -682,6 +697,8 @@ export function coreVite(): Plugin {
         transformedCode = transformedCode.replace(
           /import\.meta\.env\[(['"`])([^'"`]+)\1\]/g,
           (match, quote, varName) => {
+            // Leave Vite's built-in env vars for Vite to handle.
+            if (VITE_RESERVED_ENV.has(varName)) return match;
             hasChanges = true;
             return `process.env[${quote}${varName}${quote}]`;
           },
@@ -759,6 +776,14 @@ export async function loadMiddleware() {
 `;
       }
 
+      // Virtual module: l5e-islands
+      // Lazy glob of all React island components so the SSR entry can import a
+      // component by its __src path and renderToString() it. Non-eager → only
+      // islands actually present on a page (with ssr) get imported at runtime.
+      if (id === '\0' + VIRTUAL_L5E_ISLANDS) {
+        return `export const islandModules = import.meta.glob('/src/**/react/*.{tsx,jsx}');`;
+      }
+
       // Virtual module: l5e-island-strategies
       if (id === '\0' + VIRTUAL_L5E_ISLAND_STRATEGIES) {
         // Check if src/island-strategies.ts exists

package/src/island/ClientIsland.ts

@@ -1,4 +1,10 @@
-import { jsxFactory, registerIsland, type JSXChild, type JSXNode } from '../core/jsx-runtime';
+import {
+  jsxFactory,
+  registerIsland,
+  registerSsrIsland,
+  type JSXChild,
+  type JSXNode,
+} from '../core/jsx-runtime';
 
 /**
  * Derive component name from `from` path.
@@ -21,6 +27,13 @@ export interface ClientIslandProps {
   id?: string;
   children?: JSXChild | JSXChild[];
 
+  /**
+   * Opt-in: server-render the component into the placeholder and hydrate on the
+   * client (instead of the default client-only mount). Component must be
+   * SSR-safe (no top-level browser access) and props must be JSON-serializable.
+   */
+  ssr?: boolean;
+
   /** INTERNAL — injected by vite-plugin. Format: "[name]_[hash]" */
   __key?: string;
   /** INTERNAL — injected by vite-plugin. Manifest-compatible source path with extension */
@@ -36,6 +49,7 @@ export function ClientIsland(attrs: ClientIslandProps): JSXNode {
     class: className,
     id,
     children,
+    ssr,
     __key,
     __src,
   } = attrs;
@@ -44,6 +58,8 @@ export function ClientIsland(attrs: ClientIslandProps): JSXNode {
 
   // Register island in render context (like useClientJs)
   // server.ts will use this to generate per-page window.__L5E_ISLANDS__
+  // (needed for BOTH client-only mount AND ssr hydration — the client still
+  // loads the component chunk via this registry).
   if (__key && __src) {
     registerIsland(__key, __src, componentName);
   }
@@ -59,6 +75,25 @@ export function ClientIsland(attrs: ClientIslandProps): JSXNode {
     dataAttrs['data-island-opts'] = mountOpts;
   }
 
+  // SSR opt-in: register a pending server render and embed a unique token as the
+  // placeholder body. entry-server replaces the token with renderToString() output
+  // after the synchronous render pass, then normalizes data-island-ssr to "1".
+  // The attribute value holds the token so the post-pass can target this exact
+  // island (and strip the attribute on render failure → clean client-only fallback).
+  if (ssr && __src) {
+    const token = registerSsrIsland(__src, componentName, props);
+    if (token) {
+      return jsxFactory('div', {
+        ...dataAttrs,
+        'data-island-ssr': token,
+        ...(id ? { id } : {}),
+        class: className ? `l5e-island ${className}` : 'l5e-island',
+        // Raw token comment as body; replaced with SSR HTML in entry-server.
+        setHtml: `<!--${token}-->`,
+      });
+    }
+  }
+
   return jsxFactory(
     'div',
     {

package/src/island/runtime.ts

@@ -77,6 +77,7 @@ function discoverIslands(): IslandMeta[] {
     props: JSON.parse(el.getAttribute('data-island-props') || '{}'),
     mount: el.getAttribute('data-island-mount') || 'load',
     mountOpts: el.getAttribute('data-island-opts') || undefined,
+    ssr: el.hasAttribute('data-island-ssr'),
   }));
 }
 
@@ -97,7 +98,7 @@ function createMountFn(island: IslandMeta): () => Promise<void> {
     }
 
     try {
-      const [{ createRoot }, { createElement }, mod] = await Promise.all([
+      const [reactDomClient, { createElement }, mod] = await Promise.all([
         import('react-dom/client'),
         import('react'),
         import(/* @vite-ignore */ url),
@@ -109,8 +110,14 @@ function createMountFn(island: IslandMeta): () => Promise<void> {
         return;
       }
 
-      const root = createRoot(island.element);
-      root.render(createElement(Component, island.props));
+      if (island.ssr) {
+        // Server already rendered this component into the element → hydrate it.
+        reactDomClient.hydrateRoot(island.element, createElement(Component, island.props));
+      } else {
+        // Client-only mount (default): fresh render into an empty placeholder.
+        const root = reactDomClient.createRoot(island.element);
+        root.render(createElement(Component, island.props));
+      }
     } catch (error) {
       console.error(`[l5e-island] Failed to mount "${island.registryKey}":`, error);
     }

package/src/island/types.ts

@@ -19,6 +19,7 @@ export interface IslandMeta {
   props: Record<string, any>;
   mount: string; // Strategy name
   mountOpts?: string; // Options passed to strategy function
+  ssr?: boolean; // Server-rendered → hydrate instead of fresh client mount
 }
 
 export interface IslandEntry {