@opentf/web 0.6.0 → 0.8.0

package/server/api.js

@@ -0,0 +1,208 @@
+// File-based API routes for the OTF Web runtime — the API backend (ARCHITECTURE
+// §6, SPEC §11). An endpoint is a `route.{js,ts}` file — the API analogue of a
+// page's `page.{jsx,tsx}` — so the folder is the URL (`app/api/users/[id]/route.ts`
+// → `/api/users/:id`), exactly like pages. Handlers are *plain server modules*
+// (not JSX/DOM-compiled): each exports named functions per HTTP method that take a
+// standard `Request` and return a standard `Response`, portable across Bun / Node /
+// Cloudflare Workers (SPEC §11.1). A folder may hold a `page.*` or a `route.*`, not
+// both — the toolchain errors on the conflict (like Next.js's App Router).
+//
+// This module is runtime-agnostic: `createApiHandler` turns a discovered route
+// map into a single `(request) => Response | null` function. `null` means "no
+// API route matched" so the caller (dev/serve/adapter) can fall through to SSR
+// or a 404. Matching reuses the `[param]` / `[...rest]` convention and regex
+// approach of the page router (runtime/router.js `matchRoute`) so behavior is
+// identical across pages and API and across every deployment target.
+
+const METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
+
+/**
+ * Strip the app-directory prefix from a route/middleware file path. When the
+ * caller knows the app dir (the CLI always does), the exact prefix is removed —
+ * unambiguous even for an `app/app/...` folder. Without it, fall back to the last
+ * complete `/app` path segment; the lookahead keeps folders that merely *start*
+ * with "app" (`/appointments`, `/apps`) intact.
+ */
+function stripAppDir(filePath, appDir) {
+  if (appDir) {
+    const base = appDir.replace(/\/+$/, "");
+    if (filePath.startsWith(base + "/")) return filePath.slice(base.length);
+  }
+  return filePath.replace(/^.*\/app(?=\/)/, "");
+}
+
+/**
+ * Derive the API route path from a `.../app/<...>/route.{js,ts}` file path — the
+ * folder is the URL, mirroring `routeFromPath` in the page router.
+ * `app/api/status/route.js` → `/api/status`, `app/api/users/[id]/route.ts` →
+ * `/api/users/[id]`, `app/route.js` → `/`. Pass `appDir` (the absolute app
+ * directory) when known so the prefix is stripped exactly.
+ */
+export function apiRouteFromPath(filePath, appDir) {
+  const r = stripAppDir(filePath, appDir).replace(/\/route\.(jsx?|tsx?)$/, "");
+  return r === "" ? "/" : r;
+}
+
+/** The folder route a `_middleware.{js,ts}` file governs: `app/api/_middleware.js`
+ *  → `/api` (applies to `/api` and everything nested under it). */
+export function middlewareScopeFromPath(filePath, appDir) {
+  const r = stripAppDir(filePath, appDir).replace(/\/_middleware\.(jsx?|tsx?)$/, "");
+  return r === "" ? "/" : r;
+}
+
+/** Compile a route path with `[param]` / `[...rest]` segments to a matcher regex.
+ *  Named groups become route params; literal parts are regex-escaped (a `v1.0`
+ *  folder must not match `v1X0`); the optional trailing slash is tolerated. */
+function compilePattern(route) {
+  const src = route
+    .split(/(\[\.\.\.[^\]]+\]|\[[^\]]+\])/)
+    .map((part) => {
+      if (part.startsWith("[...")) return `(?<${part.slice(4, -1)}>.+)`;
+      if (part.startsWith("[")) return `(?<${part.slice(1, -1)}>[^/]+)`;
+      return part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    })
+    .join("");
+  return new RegExp(`^${src}/?$`);
+}
+
+// Percent-decode a matched param segment; malformed input stays raw rather than throwing.
+const decodeParam = (s) => {
+  try {
+    return decodeURIComponent(s);
+  } catch {
+    return s;
+  }
+};
+
+const normalize = (p) => (p || "/").replace(/(.)\/+$/, "$1");
+
+/** The `Allow` header value for a handler module: the methods it exports, plus the
+ *  auto-provided HEAD (when GET exists) and OPTIONS. */
+function allowedMethods(mod) {
+  const set = new Set(METHODS.filter((m) => typeof mod[m] === "function"));
+  if (set.has("GET")) set.add("HEAD");
+  set.add("OPTIONS");
+  return [...set].join(", ");
+}
+
+/**
+ * Build the API request handler from a discovered route + middleware map.
+ *
+ * @param {Record<string, object>} routeModules  `{ [absFilePath]: moduleNamespace }`
+ *        — each module exports method handlers (`GET`, `POST`, …).
+ * @param {Record<string, object>} middlewareModules  `{ [absFilePath]: moduleNamespace }`
+ *        for `_middleware.{js,ts}` files; the middleware is the default export.
+ * @param {{ appDir?: string }} [options]  `appDir` — the absolute app directory the
+ *        module keys live under, for exact route derivation (the CLI passes it).
+ * @returns {(request: Request) => Promise<Response | null>}
+ */
+export function createApiHandler(routeModules = {}, middlewareModules = {}, { appDir } = {}) {
+  const routes = [];
+  for (const file in routeModules) {
+    const route = apiRouteFromPath(file, appDir);
+    routes.push({ route, pattern: compilePattern(route), module: routeModules[file], dynamic: route.includes("[") });
+  }
+  // Static routes before dynamic, longer (more specific) before shorter, so the
+  // most specific match wins deterministically regardless of discovery order.
+  routes.sort((a, b) => a.dynamic - b.dynamic || b.route.length - a.route.length);
+
+  const middleware = [];
+  for (const file in middlewareModules) {
+    const mod = middlewareModules[file];
+    const fn = mod.default ?? mod.middleware;
+    if (typeof fn === "function") middleware.push({ scope: middlewareScopeFromPath(file, appDir), fn });
+  }
+  // Outermost (shortest scope) runs first, so `/api/_middleware` wraps `/api/users/_middleware`.
+  middleware.sort((a, b) => a.scope.length - b.scope.length);
+
+  return async function handle(request) {
+    const url = new URL(request.url);
+    const pathname = normalize(url.pathname);
+
+    let matched = null;
+    let params = {};
+    for (const r of routes) {
+      const m = pathname.match(r.pattern);
+      if (!m) continue;
+      matched = r;
+      params = { ...(m.groups || {}) };
+      // Params reach handlers percent-decoded (`/users/John%20Doe` → "John Doe");
+      // catch-all segments are split first so an encoded `%2F` never adds a segment.
+      for (const k in params) {
+        params[k] = r.route.includes(`[...${k}]`)
+          ? params[k].split("/").map(decodeParam)
+          : decodeParam(params[k]);
+      }
+      break;
+    }
+    if (!matched) return null; // no API route — fall through to SSR / 404
+
+    // Shared per-request context. `locals` is the channel middleware uses to pass
+    // data (auth user, validated body) down to the handler.
+    const context = {
+      params,
+      query: Object.fromEntries(url.searchParams),
+      url,
+      locals: {},
+    };
+
+    const dispatch = async (req) => {
+      const mod = matched.module;
+      const method = req.method.toUpperCase();
+      const fn = mod[method];
+      if (typeof fn === "function") return fn(req, context);
+      // Auto HEAD from GET (drop the body); auto OPTIONS; else 405.
+      if (method === "HEAD" && typeof mod.GET === "function") {
+        const got = await mod.GET(req, context);
+        // GET may lean on the plain-value → JSON convenience; HEAD must then carry
+        // the same status/headers that GET response would have had.
+        const res = got instanceof Response ? got : Response.json(got);
+        return new Response(null, { status: res.status, headers: res.headers });
+      }
+      if (method === "OPTIONS") return new Response(null, { status: 204, headers: { Allow: allowedMethods(mod) } });
+      return new Response(null, { status: 405, headers: { Allow: allowedMethods(mod) } });
+    };
+
+    // Compose the applicable middleware chain around dispatch (outermost first).
+    // The root scope ("/", from an `app/_middleware.*`) governs every route.
+    const chain = middleware.filter(
+      (mw) => mw.scope === "/" || pathname === mw.scope || pathname.startsWith(mw.scope + "/"),
+    );
+    let next = dispatch;
+    for (let i = chain.length - 1; i >= 0; i--) {
+      const { fn } = chain[i];
+      const downstream = next;
+      next = (req) => fn(req, context, () => downstream(req));
+    }
+
+    try {
+      const res = await next(request);
+      if (res instanceof Response) return res;
+      if (res === undefined) {
+        throw new Error(`API handler for ${request.method} ${pathname} returned no Response`);
+      }
+      return Response.json(res); // lenient: a plain value becomes a JSON response
+    } catch (e) {
+      if (e instanceof Response) return e; // handlers/middleware may throw a Response
+      console.error(`✗ API ${request.method} ${pathname}:`, e?.stack ?? e);
+      return Response.json({ error: "Internal Server Error" }, { status: 500 });
+    }
+  };
+}
+
+/**
+ * Wrap an API handler (`(request) => Response | null`) into a total Fetch handler
+ * that always returns a `Response` — a `null` (no route matched) becomes the
+ * optional `fallback(request)` or a 404. Fetch-native runtimes (Bun, Cloudflare
+ * Workers, Deno) can export it directly:
+ *
+ *   import { apiHandler } from "./dist/server/api.js";
+ *   export default { fetch: createFetchHandler(apiHandler) };
+ */
+export function createFetchHandler(handler, { fallback } = {}) {
+  return async (request) => {
+    const res = await handler(request);
+    if (res) return res;
+    return fallback ? fallback(request) : new Response("Not Found", { status: 404 });
+  };
+}

package/server/index.d.ts

@@ -0,0 +1,92 @@
+// Types for the `@opentf/web/server` entry. The API-routes surface is fully typed
+// (./api); the SSG string-builders and render helpers — authored in JS and mostly
+// consumed by generated entry code — are declared with permissive signatures.
+
+export * from "./api.js";
+
+// ── Render / route API (render.js) ─────────────────────────────────────────────
+export interface RenderResult {
+  html: string;
+  metadata: Record<string, unknown>;
+  hydration: unknown;
+  status?: number;
+}
+export function renderRoute(
+  pathname: string,
+  params?: Record<string, unknown> | null,
+  search?: string,
+  options?: { data?: unknown },
+): Promise<RenderResult | null>;
+export function renderToString(pathname: string, search?: string): Promise<string>;
+export function collectRoutePaths(): Promise<string[]>;
+
+// ── <head> / metadata (head.js) ─────────────────────────────────────────────────
+export function resolveMetadata(args?: {
+  route?: string;
+  entry?: unknown;
+  params?: Record<string, unknown>;
+  query?: Record<string, unknown>;
+}): Promise<Record<string, unknown>>;
+export function renderHead(meta?: Record<string, unknown>, opts?: { path?: string; baseUrl?: string }): string;
+export function localeAlternateLinks(
+  routePath: string,
+  cfg?: { locales?: string[]; defaultLocale?: string },
+  localize?: (path: string, locale: string) => string,
+): Array<Record<string, string>>;
+
+// ── Route loaders (loader.js) ───────────────────────────────────────────────────
+import type { RouteParams } from "./api.js";
+
+/** The context a route loader receives (docs/DATA.md). `request` is the live
+ *  Request under serve/dev and undefined at SSG prerender; `locals` is reserved. */
+export interface LoaderContext {
+  params: RouteParams;
+  query: Record<string, string>;
+  request?: Request;
+  locale: string | null;
+  locals: Record<string, unknown>;
+}
+
+/** A route loader — the default (or named `loader`) export of a `loader.{js,ts}`
+ *  file. Returns the page's JSON-serializable data. */
+export type Loader = (context: LoaderContext) => unknown | Promise<unknown>;
+
+export interface LoaderMatch {
+  route: string;
+  params: RouteParams;
+  locale: string | null;
+}
+
+export interface LoaderRegistry {
+  routes: string[];
+  match(pathname: string): LoaderMatch | null;
+  load(m: LoaderMatch, ctx?: { request?: Request; query?: Record<string, string> }): Promise<unknown>;
+  loadSerialized(
+    m: LoaderMatch,
+    ctx?: { request?: Request; query?: Record<string, string> },
+  ): Promise<{ data: unknown; json: string }>;
+  handle(request: Request): Promise<Response | null>;
+}
+
+export function createLoaderRegistry(
+  loaderModules?: Record<string, { default?: Loader; loader?: Loader }>,
+  options?: { appDir?: string; i18n?: { locales?: string[]; defaultLocale?: string } },
+): LoaderRegistry;
+export function loaderRouteFromPath(filePath: string, appDir?: string): string;
+/** Throw "this page does not exist" from inside a loader (404 semantics). */
+export function notFound(message?: string): never;
+export function isNotFound(e: unknown): boolean;
+export function serializeRouteData(value: unknown): string;
+
+// ── SSG string-builder helpers (ssg-runtime.js) ─────────────────────────────────
+export function defineSSG(tag: string, render: (...args: any[]) => string): void;
+export function beginHydrationCollect(): void;
+export function endHydrationCollect(): unknown;
+export function escapeHtml(s: unknown): string;
+export function escapeAttr(s: unknown): string;
+export function clsx(value: unknown): string;
+export function styleString(value: unknown): string;
+export function attr(name: string, value: unknown): string;
+export function ssgText(v: unknown): string;
+export function ssgList<T>(arr: T[], fn: (item: T, index: number) => string): string;
+export function ssgComponent(tag: string, props?: Record<string, unknown>, children?: unknown): string;

package/server/index.js

@@ -5,4 +5,6 @@
 export * from "./ssg-runtime.js";
 export * from "./head.js";
 export * from "./render.js";
+export * from "./api.js";
+export * from "./loader.js";
 import "./builtins.js";

package/server/loader.js

@@ -0,0 +1,199 @@
+// Route loaders — the server half of data fetching (docs/DATA.md, SPEC §8). A
+// loader is a `loader.{js,ts}` file sibling to a `page.*` (the data analogue of
+// a `route.*` API endpoint): a *plain server module* whose default export (or
+// named `loader` export, the Phase B compiler convention) returns the page's
+// JSON-serializable data:
+//
+//   export default async function loader({ params, query, request, locale, locals }) {
+//     return db.todos.list();
+//   }
+//
+// `createLoaderRegistry` turns a discovered `{ absFilePath: namespace }` map into
+// a matcher + runner shared by every consumer: SSG prerender (build time, no
+// `request`), the SSR server (per request), the dev server, and the
+// `<path>/__data.json` HTTP endpoint SPA navigation fetches from (`handle`).
+//
+// Matching duplicates the `[param]` / `[...rest]` compile/decode approach of the
+// API handler (api.js) — like api.js itself mirrors the page router — so params
+// behave identically across pages, endpoints, and loaders.
+
+import { DATA_FILE } from "../runtime/route-data.js";
+
+/** See `stripAppDir` in api.js — exact-prefix strip with a `/app` segment fallback. */
+function stripAppDir(filePath, appDir) {
+  if (appDir) {
+    const base = appDir.replace(/\/+$/, "");
+    if (filePath.startsWith(base + "/")) return filePath.slice(base.length);
+  }
+  return filePath.replace(/^.*\/app(?=\/)/, "");
+}
+
+/** The page route a `.../app/<...>/loader.{js,ts}` file feeds (folder = URL):
+ *  `app/todos/loader.js` → `/todos`, `app/loader.js` → `/`. */
+export function loaderRouteFromPath(filePath, appDir) {
+  const r = stripAppDir(filePath, appDir).replace(/\/loader\.(js|ts)$/, "");
+  return r === "" ? "/" : r;
+}
+
+/** Compile a route with `[param]` / `[...rest]` segments to a matcher regex (see api.js). */
+function compilePattern(route) {
+  const src = route
+    .split(/(\[\.\.\.[^\]]+\]|\[[^\]]+\])/)
+    .map((part) => {
+      if (part.startsWith("[...")) return `(?<${part.slice(4, -1)}>.+)`;
+      if (part.startsWith("[")) return `(?<${part.slice(1, -1)}>[^/]+)`;
+      return part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    })
+    .join("");
+  return new RegExp(`^${src}/?$`);
+}
+
+const decodeParam = (s) => {
+  try {
+    return decodeURIComponent(s);
+  } catch {
+    return s;
+  }
+};
+
+const normalize = (p) => (p || "/").replace(/(.)\/+$/, "$1");
+
+/**
+ * Signal "this page does not exist for these params" from inside a loader — the
+ * SSR server responds 404 (rendering the 404 page), the data endpoint returns a
+ * 404 the client maps to `undefined`, and SSG records the path as failed.
+ */
+export function notFound(message = "Not Found") {
+  const e = new Error(message);
+  e.name = "NotFoundError";
+  // A marker property, not a class: the loader bundle and the server bundle are
+  // separate module graphs (each bundles its own copy of this file), so an
+  // `instanceof` check would fail across the boundary.
+  e.otfwNotFound = true;
+  throw e;
+}
+
+/** Was `e` thrown by {@link notFound}? (Property check — see the note there.) */
+export function isNotFound(e) {
+  return e?.otfwNotFound === true;
+}
+
+/**
+ * Serialize loader data for embedding: the inline `#__otfw_data` script and the
+ * static `__data.json` file must carry identical bytes. `<` is escaped so the
+ * payload can never close the inline `<script>` (same rule as the island-props
+ * collector in ssg-runtime.js). `undefined` (no data) serializes to `""` — the
+ * toolchain skips injection entirely.
+ */
+export function serializeRouteData(value) {
+  const json = JSON.stringify(value);
+  return json === undefined ? "" : json.replace(/</g, "\\u003c");
+}
+
+/**
+ * Build the loader registry from a discovered `{ absFilePath: namespace }` map.
+ *
+ * @param {Record<string, object>} loaderModules  each module's default (or `loader`)
+ *        export is the loader function.
+ * @param {{ appDir?: string, i18n?: { locales?: string[], defaultLocale?: string } }} [options]
+ *        `appDir` pins exact route derivation; `i18n` lets `match` strip a leading
+ *        non-default locale prefix (`/fr/todos` matches the `/todos` loader with
+ *        `locale: "fr"` in the context).
+ * @returns {{ routes: string[],
+ *             match: (pathname: string) => object | null,
+ *             load: (m: object, ctx?: object) => Promise<unknown>,
+ *             loadSerialized: (m: object, ctx?: object) => Promise<{ data: unknown, json: string }>,
+ *             handle: (request: Request) => Promise<Response | null> }}
+ */
+export function createLoaderRegistry(loaderModules = {}, { appDir, i18n } = {}) {
+  const entries = [];
+  for (const file in loaderModules) {
+    const ns = loaderModules[file];
+    const fn = ns.default ?? ns.loader;
+    if (typeof fn !== "function") continue; // a loader file without a loader export is inert
+    const route = loaderRouteFromPath(file, appDir);
+    entries.push({ route, pattern: compilePattern(route), fn, dynamic: route.includes("[") });
+  }
+  // Static before dynamic, longer before shorter — most specific wins (see api.js).
+  entries.sort((a, b) => a.dynamic - b.dynamic || b.route.length - a.route.length);
+
+  const i18nOn = !!(i18n && Array.isArray(i18n.locales) && i18n.locales.length);
+  const defaultLocale = i18nOn ? (i18n.defaultLocale ?? i18n.locales[0]) : null;
+  const nonDefault = i18nOn ? new Set(i18n.locales.filter((l) => l !== defaultLocale)) : null;
+
+  /** Match a *page* pathname (no `__data.json` suffix) → `{ route, params, locale }` or null. */
+  function match(pathname) {
+    let path = normalize(pathname);
+    let locale = defaultLocale;
+    if (nonDefault) {
+      const m = path.match(/^\/([^/]+)(\/.*|)$/);
+      if (m && nonDefault.has(m[1])) {
+        locale = m[1];
+        path = m[2] || "/";
+      }
+    }
+    for (const e of entries) {
+      const m = path.match(e.pattern);
+      if (!m) continue;
+      const params = { ...(m.groups || {}) };
+      for (const k in params) {
+        params[k] = e.route.includes(`[...${k}]`)
+          ? params[k].split("/").map(decodeParam)
+          : decodeParam(params[k]);
+      }
+      return { route: e.route, params, locale, fn: e.fn };
+    }
+    return null;
+  }
+
+  /** Run a matched loader. `request` is the live Request under serve/dev and
+   *  `undefined` at SSG prerender; `locals` is reserved (middleware is future work). */
+  async function load(m, { request, query = {} } = {}) {
+    return m.fn({ params: m.params, query, request, locale: m.locale, locals: {} });
+  }
+
+  /** {@link load}, plus the serialized form — escaping lives in one place. */
+  async function loadSerialized(m, ctx) {
+    const data = await load(m, ctx);
+    return { data, json: serializeRouteData(data) };
+  }
+
+  /**
+   * The `<path>/__data.json` HTTP endpoint (docs/DATA.md): a `Response` for any
+   * data URL — including 404 on a miss, so the reserved suffix never falls
+   * through to SSR — or `null` for every other path.
+   */
+  async function handle(request) {
+    const url = new URL(request.url);
+    const pathname = normalize(url.pathname);
+    let pagePath = null;
+    if (pathname === `/${DATA_FILE}`) pagePath = "/";
+    else if (pathname.endsWith(`/${DATA_FILE}`)) {
+      pagePath = pathname.slice(0, -(DATA_FILE.length + 1)) || "/";
+    }
+    if (pagePath === null) return null;
+
+    const method = request.method.toUpperCase();
+    if (method !== "GET" && method !== "HEAD") {
+      return new Response(null, { status: 405, headers: { Allow: "GET, HEAD" } });
+    }
+    const headers = { "content-type": "application/json", "cache-control": "no-store" };
+    const m = match(pagePath);
+    if (!m) return new Response("null", { status: 404, headers });
+    try {
+      const { json } = await loadSerialized(m, {
+        request,
+        query: Object.fromEntries(url.searchParams),
+      });
+      // `json || "null"` — an undefined loader result still yields valid JSON
+      // (the client maps a 404 to undefined; a 200 must parse).
+      return new Response(method === "HEAD" ? null : json || "null", { status: 200, headers });
+    } catch (e) {
+      if (isNotFound(e)) return new Response("null", { status: 404, headers });
+      console.error(`✗ loader ${pagePath}:`, e?.stack ?? e);
+      return Response.json({ error: "Internal Server Error" }, { status: 500 });
+    }
+  }
+
+  return { routes: entries.map((e) => e.route), match, load, loadSerialized, handle };
+}

package/server/render.js

@@ -15,27 +15,35 @@ import {
   setRouteState,
 } from "../runtime/router.js";
 import { resolveMetadata } from "./head.js";
+import { beginHydrationCollect, endHydrationCollect } from "./ssg-runtime.js";
 
 /**
- * Render `pathname` to `{ html, metadata, status }`: the markup for inside `#app`,
- * the resolved SEO metadata (for the `<head>`), and an HTTP `status` (200 when the
- * path matched a real route, 404 when it fell back to the registered 404 page — the
- * SSR server uses it; SSG ignores it). `params` (from `getStaticPaths`) override the
- * matched route's params for dynamic routes. Returns `null` if there's no match and
- * no 404 page.
+ * Render `pathname` to `{ html, metadata, status, hydration }`: the markup for inside
+ * `#app`, the resolved SEO metadata (for the `<head>`), an HTTP `status` (200 when the
+ * path matched a real route, 404 when it fell back to the registered 404 page — the SSR
+ * server uses it; SSG ignores it), and `hydration` — the JSON island-props payload the
+ * toolchain embeds so the client resumes from rich data (`""` when nothing needs it).
+ * `params` (from `getStaticPaths`) override the matched route's params for dynamic
+ * routes. `options.data` is the route's loader result (run by the caller — serve /
+ * prerender own the loader bundle) and is exposed to the page as `router.data`.
+ * Returns `null` if there's no match and no 404 page.
  */
-export async function renderRoute(pathname, params = null, search = "") {
+export async function renderRoute(pathname, params = null, search = "", { data } = {}) {
   const real = matchRoute(pathname);
   const match =
     real || (routes.notFound ? { entry: routes.notFound, params: {}, route: null } : null);
   if (!match) return null;
   if (params) match.params = params;
 
-  // Let a page reading `router.params`/`pathname`/`query` resolve to this route.
-  setRouteState({ pathname, search, params: match.params });
+  // Let a page reading `router.params`/`pathname`/`query`/`data` resolve to this route.
+  setRouteState({ pathname, search, params: match.params, data });
 
   const query = Object.fromEntries(new URLSearchParams(search));
   const props = { params: match.params, query };
+
+  // Collect each island's rich props while the tree renders (ssgComponent records them
+  // and stamps `data-h` ids), then serialize the payload for the shell.
+  beginHydrationCollect();
   let html = (await resolveFactory(match.entry))(props);
 
   // Wrap with layouts, most-specific inward to root outermost.
@@ -44,6 +52,7 @@ export async function renderRoute(pathname, params = null, search = "") {
     const layout = await resolveFactory(chain[i]);
     html = layout({ ...props, children: html });
   }
+  const hydration = endHydrationCollect();
 
   const metadata = await resolveMetadata({
     route: match.route,
@@ -51,7 +60,7 @@ export async function renderRoute(pathname, params = null, search = "") {
     params: match.params,
     query,
   });
-  return { html, metadata, status: real ? 200 : 404 };
+  return { html, metadata, status: real ? 200 : 404, hydration };
 }
 
 /** Back-compat / convenience: render just the `#app` markup for `pathname`. */

package/server/ssg-runtime.js

@@ -20,6 +20,53 @@ export function defineSSG(tag, render) {
   registry[tag] = render;
 }
 
+// ── hydration props collector (compiler-driven data hydration) ────────────────
+// The lossy path is passing rich props through string attributes. Instead, each
+// server-rendered island gets a `data-h` id and its JSON-safe props are recorded into a
+// single payload the shell embeds as `<script type="application/json">`. At upgrade the
+// client component initializes its prop *signals* from those real JS values (objects,
+// arrays, numbers) — not from `getAttribute` — so islands resume with correct data, with
+// no flash and no dependence on a parent walk re-applying props. `renderRoute` brackets a
+// render with `beginHydrationCollect()` / `endHydrationCollect()`.
+let _collect = null;
+
+/** Start collecting per-island hydration props for one render. */
+export function beginHydrationCollect() {
+  _collect = [];
+}
+
+/**
+ * Finish collecting and return the payload as a JSON string ("" when nothing needs
+ * hydration). `<` is escaped so a prop value can never break out of the surrounding
+ * `<script>` (a `</script>` / `<!--` injection).
+ */
+export function endHydrationCollect() {
+  const data = _collect;
+  _collect = null;
+  if (!data || data.length === 0) return "";
+  return JSON.stringify(data).replace(/</g, "\\u003c");
+}
+
+/**
+ * Record an island's JSON-safe props, returning its hydration id — or `null` when not
+ * collecting, or when nothing serializes. A JSON round-trip drops functions (event
+ * callbacks are client-only — applied by the parent walk, invisible so no flash),
+ * `undefined`, and anything cyclic/DOM/signal-shaped, so only plain data crosses.
+ */
+function collectHydrationProps(props) {
+  if (!_collect || props == null || typeof props !== "object") return null;
+  let safe;
+  try {
+    safe = JSON.parse(JSON.stringify(props));
+  } catch {
+    return null; // cyclic / non-serializable → client falls back to attributes/defaults
+  }
+  if (!safe || typeof safe !== "object" || Object.keys(safe).length === 0) return null;
+  const id = _collect.length;
+  _collect.push(safe);
+  return id;
+}
+
 /** Escape text content for HTML. */
 export function escapeHtml(s) {
   return String(s).replace(/[&<>]/g, (c) => (c === "&" ? "&amp;" : c === "<" ? "&lt;" : "&gt;"));
@@ -104,9 +151,13 @@ export function ssgComponent(tag, props, children) {
     inner = ""; // fail soft (client renders/handles it)
   }
   // Stamp the stable styling hook on the host (mirrors CSR's `classList.add`) so
-  // tag-hashed components are still styleable by a readable class name.
+  // tag-hashed components are still styleable by a readable class name, plus the
+  // hydration id (`data-h`) keying this island's rich props in the payload (if any).
   const cls = render && render.hostClass;
-  return cls ? `<${tag} class="${cls}">${inner}</${tag}>` : `<${tag}>${inner}</${tag}>`;
+  const id = collectHydrationProps(props);
+  let attrs = cls ? ` class="${cls}"` : "";
+  if (id != null) attrs += ` data-h="${id}"`;
+  return `<${tag}${attrs}>${inner}</${tag}>`;
 }
 
 export { VOID };