alabjs 0.1.0 → 0.2.0

package/dist/ssr/ppr.js

@@ -0,0 +1,132 @@
+/**
+ * Alab PPR — build-time static shell pre-renderer and runtime shell reader.
+ *
+ * ## Build-time
+ * `preRenderPPRShell()` renders a page with `PPRShellProvider` so that every
+ * `<Dynamic>` emits a `data-ppr-hole` placeholder instead of its children.
+ * The resulting HTML is saved to `.alabjs/ppr-cache/<slug>.html`.
+ *
+ * ## Runtime
+ * `getPPRShell()` reads the pre-rendered HTML for a given route path, or
+ * returns `null` if the file doesn't exist (triggers SSR fallback).
+ */
+import { createElement, Suspense } from "react";
+import { renderToPipeableStream } from "react-dom/server";
+import { Writable } from "node:stream";
+import { writeFileSync, mkdirSync, existsSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { PPRShellProvider } from "../components/Dynamic.js";
+import { htmlShellBefore, htmlShellAfter } from "./html.js";
+// ─── Constants ────────────────────────────────────────────────────────────────
+/** Relative path (from cwd) where pre-rendered shells are written. */
+export const PPR_CACHE_SUBDIR = ".alabjs/ppr-cache";
+// ─── Filename helpers ─────────────────────────────────────────────────────────
+/**
+ * Convert a route path to a safe filesystem filename (no leading slash, no
+ * dynamic segment brackets, slashes replaced with `__`).
+ *
+ * @example
+ * routeToFilename("/")                  → "index"
+ * routeToFilename("/posts")             → "posts"
+ * routeToFilename("/posts/[id]")        → "posts___id_"
+ * routeToFilename("/a/[b]/c/[d]")       → "a___b___c___d_"
+ */
+export function routeToFilename(routePath) {
+    const slug = routePath
+        .replace(/^\//, "") // strip leading /
+        .replace(/\[([^\]]+)\]/g, "__$1_") // [param] → __param_
+        .replace(/\//g, "__"); // / → __
+    return (slug || "index") + ".html";
+}
+/**
+ * Pre-render the static HTML shell for a PPR page and persist it to disk.
+ *
+ * The render uses `PPRShellProvider` so every `<Dynamic>` in the tree emits
+ * a `data-ppr-hole` placeholder — children (per-request logic) are omitted.
+ *
+ * Called from `alab build` after the Vite bundle step completes.
+ */
+export async function preRenderPPRShell({ Page, layouts, shellOpts, pprCacheDir, routePath, }) {
+    // Build the element tree: layouts wrapping Page, all inside PPRShellProvider.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let pageEl = createElement(Page, { params: {}, searchParams: {} });
+    // Suspense wrapper guards against any accidental top-level suspension.
+    pageEl = createElement(Suspense, { fallback: null }, pageEl);
+    for (let i = layouts.length - 1; i >= 0; i--) {
+        const Layout = layouts[i];
+        if (Layout)
+            pageEl = createElement(Layout, {}, pageEl);
+    }
+    // PPRShellProvider switches Dynamic into placeholder mode.
+    // Pass children via props to satisfy strict TS prop checking.
+    const tree = createElement(PPRShellProvider, { children: pageEl });
+    // Wait for the full render (allReady) — we need a complete snapshot, not a
+    // partially streamed response, because the file is served as-is from disk.
+    const reactHtml = await new Promise((resolve, reject) => {
+        let result = "";
+        const sink = new Writable({
+            write(chunk, _enc, cb) { result += chunk.toString(); cb(); },
+            final(cb) { resolve(result); cb(); },
+        });
+        const { pipe } = renderToPipeableStream(tree, {
+            onAllReady() { pipe(sink); },
+            onError(err) { reject(err instanceof Error ? err : new Error(String(err))); },
+        });
+    });
+    const before = htmlShellBefore({ ...shellOpts, headExtra: "" });
+    const after = htmlShellAfter({});
+    const fullHtml = `${before}${reactHtml}${after}`;
+    mkdirSync(pprCacheDir, { recursive: true });
+    writeFileSync(join(pprCacheDir, routeToFilename(routePath)), fullHtml, "utf8");
+}
+// ─── Runtime ──────────────────────────────────────────────────────────────────
+/**
+ * Return the pre-rendered static HTML shell for `routePath`, or `null` if the
+ * cache file doesn't exist.
+ *
+ * Callers should fall back to normal SSR when `null` is returned.
+ */
+export function getPPRShell(routePath, pprCacheDir) {
+    const filePath = join(pprCacheDir, routeToFilename(routePath));
+    try {
+        return existsSync(filePath) ? readFileSync(filePath, "utf8") : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Inject a `<meta name="alabjs-build-id">` tag into a pre-rendered PPR shell.
+ *
+ * The shell is pre-built and therefore doesn't include the per-build ID. We
+ * splice it in at serve time so skew protection still works for PPR pages.
+ */
+export function injectBuildIdIntoPPRShell(html, buildId) {
+    const tag = `<meta name="alabjs-build-id" content="${buildId.replace(/"/g, "&quot;")}" />`;
+    // Insert after <head> if present; otherwise prepend to <html>.
+    const headClose = html.indexOf("</head>");
+    if (headClose !== -1) {
+        return html.slice(0, headClose) + `  ${tag}\n` + html.slice(headClose);
+    }
+    return tag + html;
+}
+// ─── Layout discovery (prod) ──────────────────────────────────────────────────
+/**
+ * Find layout file paths for a given page route file, ordered
+ * outermost → innermost. Mirrors the logic in `app.ts` but scoped to the
+ * build-time dist directory.
+ */
+export function findBuildLayoutFiles(routeFile, distDir) {
+    const pageDir = dirname(routeFile);
+    const parts = pageDir.split("/");
+    const layouts = [];
+    for (let i = 1; i <= parts.length; i++) {
+        const dir = parts.slice(0, i).join("/");
+        const candidate = `${dir}/layout.tsx`;
+        if (existsSync(join(distDir, "server", candidate))) {
+            layouts.push(candidate);
+        }
+    }
+    return layouts;
+}
+//# sourceMappingURL=ppr.js.map

package/dist/ssr/ppr.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ppr.js","sourceRoot":"","sources":["../../src/ssr/ppr.ts"],"names":[],"mappings":"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"}

package/dist/ssr/render.d.ts

@@ -27,6 +27,8 @@ export interface RenderOptions {
     headExtra?: string;
     /** CSP nonce (optional). */
     nonce?: string;
+    /** Build ID for skew protection (see html.ts). */
+    buildId?: string;
 }
 /**
  * Render a page component to a streaming HTTP response using React 19's

package/dist/ssr/render.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/ssr/render.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,OAAO,CAAC;AAG1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD,MAAM,WAAW,aAAa;IAC5B,gCAAgC;IAChC,IAAI,EAAE,aAAa,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,CAAC,CAAC;IAC9F,yEAAyE;IAEzE,OAAO,CAAC,EAAE,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC;IAC/B,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,2BAA2B;IAC3B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,mFAAmF;IACnF,SAAS,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,6CAA6C;IAC7C,GAAG,EAAE,OAAO,CAAC;IACb,gFAAgF;IAChF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4BAA4B;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,aAAa,GAAG,IAAI,CA2F/E;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,aAAa,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAAC,EAC7F,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACnC,OAAO,CAAC,MAAM,CAAC,CAGjB"}
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/ssr/render.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,OAAO,CAAC;AAG1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD,MAAM,WAAW,aAAa;IAC5B,gCAAgC;IAChC,IAAI,EAAE,aAAa,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,CAAC,CAAC;IAC9F,yEAAyE;IAEzE,OAAO,CAAC,EAAE,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC;IAC/B,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,2BAA2B;IAC3B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,mFAAmF;IACnF,SAAS,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,6CAA6C;IAC7C,GAAG,EAAE,OAAO,CAAC;IACb,gFAAgF;IAChF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4BAA4B;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,aAAa,GAAG,IAAI,CA6F/E;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,aAAa,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAAC,EAC7F,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACnC,OAAO,CAAC,MAAM,CAAC,CAGjB"}

package/dist/ssr/render.js

@@ -9,7 +9,7 @@ import { htmlShellBefore, htmlShellAfter } from "./html.js";
  * the closing fragment is appended when the stream finishes.
  */
 export function renderToResponse(res, opts) {
-    const { Page, layouts = [], params, searchParams, metadata = {}, routeFile, layoutsJson, loadingFile, ssr, headExtra, nonce, } = opts;
+    const { Page, layouts = [], params, searchParams, metadata = {}, routeFile, layoutsJson, loadingFile, ssr, headExtra, nonce, buildId, } = opts;
     const shellOpts = {
         metadata,
         paramsJson: JSON.stringify(params),
@@ -20,6 +20,7 @@ export function renderToResponse(res, opts) {
         ssr,
         headExtra,
         nonce,
+        buildId,
     };
     const before = htmlShellBefore(shellOpts);
     const after = htmlShellAfter({ nonce });

package/dist/ssr/render.js.map

@@ -1 +1 @@
-{"version":3,"file":"render.js","sourceRoot":"","sources":["../../src/ssr/render.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../../src/ssr/render.ts"],"names":[],"mappings":"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"}

package/dist/types/index.d.ts

@@ -113,5 +113,24 @@ export type GenerateMetadata<Path extends string = string> = (props: {
     readonly params: RouteParams<Path>;
     readonly searchParams: Readonly<Record<string, string | readonly string[]>>;
 }) => Promise<PageMetadata> | PageMetadata;
-export {};
+/**
+ * Export `cdnCache` from a page to let any CDN or shared proxy cache it at
+ * the edge — no Vercel required.
+ *
+ * @example
+ * // app/posts/[id]/page.tsx
+ * import type { CdnCache } from "alabjs";
+ *
+ * export const cdnCache: CdnCache = {
+ *   maxAge: 60,          // CDN keeps the page for 60 s
+ *   swr: 30,             // serve stale for 30 s while revalidating
+ *   tags: ["posts", "post:42"],  // invalidate via /_alabjs/revalidate
+ * };
+ *
+ * @remarks
+ * CDN-cached pages are **public pages** — Alab skips CSRF token injection for
+ * them because a shared cache would hand the same token to every visitor.
+ * Do not use `cdnCache` on pages that contain user-specific state.
+ */
+export type { CdnCache } from "../server/cdn.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,19 @@
 {
   "name": "alabjs",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "AlabJS — full-stack React framework powered by a Rust compiler",
+  "keywords": [
+    "react",
+    "framework",
+    "ssr",
+    "fullstack",
+    "rust",
+    "vite",
+    "typescript",
+    "server-functions",
+    "signals",
+    "isr"
+  ],
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -103,5 +115,6 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/thinkgrid-labs/alabjs.git"
-  }
+  },
+  "author": "Dennis Paler <dennis@thinkgrid.dev>"
 }

package/src/commands/build.ts

@@ -1,7 +1,9 @@
 import { build as viteBuild, type PluginOption } from "vite";
 import { resolve } from "node:path";
-import { spawn } from "node:child_process";
-import { existsSync, writeFileSync } from "node:fs";
+import { spawn, execSync } from "node:child_process";
+import { existsSync, writeFileSync, readFileSync } from "node:fs";
+import { preRenderPPRShell, findBuildLayoutFiles, PPR_CACHE_SUBDIR } from "../ssr/ppr.js";
+import type { RouteManifest } from "../router/manifest.js";
 
 interface BuildOptions {
   cwd: string;
@@ -165,6 +167,12 @@ export async function build({ cwd, skipTypecheck = false, mode = "ssr", analyze
 
   await Promise.all(tasks);
 
+  // Write a stable build ID for skew protection (must run after Vite so the
+  // route-manifest.json is in place for the content-hash fallback path).
+  const distDir = resolve(cwd, ".alabjs/dist");
+  await writeBuildId(distDir, cwd);
+  await buildPPRShells(distDir, cwd);
+
   // Bundle the offline service worker as a separate iife chunk.
   // Output: .alabjs/dist/client/_alabjs/offline-sw.js (served at /_alabjs/offline-sw.js)
   await buildOfflineSw(cwd);
@@ -172,6 +180,113 @@ export async function build({ cwd, skipTypecheck = false, mode = "ssr", analyze
   console.log("\n  alab  build complete → .alabjs/dist");
 }
 
+/**
+ * Generate a stable build ID and write it to `.alabjs/dist/BUILD_ID`.
+ *
+ * Strategy (in priority order):
+ *  1. Git short SHA — deterministic, human-readable, zero CPU cost.
+ *  2. Rust FNV-1a hash of the route-manifest JSON via `@alabjs/compiler`
+ *     (napi binary) — content-addressed, no git required.
+ *  3. Base-36 millisecond timestamp — last resort when both git and napi
+ *     are unavailable (e.g. first-time contributor without Rust toolchain).
+ */
+async function writeBuildId(distDir: string, cwd: string): Promise<void> {
+  let buildId: string;
+
+  // 1. Git SHA (preferred — zero cost, guaranteed unique per commit)
+  try {
+    buildId = execSync("git rev-parse --short HEAD", { cwd, encoding: "utf8" }).trim();
+  } catch {
+    // 2. Rust FNV-1a hash of the route manifest (content-addressed)
+    try {
+      const manifestPath = resolve(distDir, "route-manifest.json");
+      const manifestContent = readFileSync(manifestPath, "utf8");
+      type NapiWithHash = { hashBuildId(s: string): string };
+      const mod = await import("@alabjs/compiler") as unknown as { default?: NapiWithHash } & NapiWithHash;
+      const napi: NapiWithHash = (mod.default ?? mod) as NapiWithHash;
+      if (typeof napi.hashBuildId === "function") {
+        buildId = napi.hashBuildId(manifestContent);
+      } else {
+        throw new Error("hashBuildId not available");
+      }
+    } catch {
+      // 3. Timestamp fallback
+      buildId = Date.now().toString(36);
+    }
+  }
+
+  writeFileSync(resolve(distDir, "BUILD_ID"), buildId, "utf8");
+  console.log(`  alab  build ID → ${buildId}`);
+}
+
+/**
+ * Pre-render static HTML shells for every page that exports `ppr = true`.
+ *
+ * Runs AFTER the Vite SSR bundle so compiled page modules are available in
+ * `.alabjs/dist/server/`. Each shell is saved to `.alabjs/ppr-cache/`.
+ */
+async function buildPPRShells(distDir: string, cwd: string): Promise<void> {
+  const manifestPath = resolve(distDir, "route-manifest.json");
+  if (!existsSync(manifestPath)) return;
+
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as RouteManifest;
+  const pageRoutes = manifest.routes.filter((r) => r.kind === "page");
+  const pprCacheDir = resolve(cwd, PPR_CACHE_SUBDIR);
+  let count = 0;
+
+  for (const route of pageRoutes) {
+    const modulePath = resolve(distDir, "server", route.file);
+    if (!existsSync(modulePath)) continue;
+
+    // Dynamic import — module is compiled ESM, importable by Node directly.
+    const mod = await import(modulePath) as {
+      default?: unknown;
+      ppr?: unknown;
+      metadata?: Record<string, unknown>;
+    };
+
+    if (mod.ppr !== true) continue;
+    if (typeof mod.default !== "function") {
+      console.warn(`  alab  ppr: ${route.file} has no default export — skipping.`);
+      continue;
+    }
+
+    // Load layout modules (outermost → innermost).
+    const layoutPaths = findBuildLayoutFiles(route.file, distDir);
+    const layoutMods = await Promise.all(
+      layoutPaths.map((p) => import(resolve(distDir, "server", p))),
+    );
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const layouts = layoutMods.map((m: any) => m.default).filter((c: unknown) => typeof c === "function");
+
+    try {
+      await preRenderPPRShell({
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        Page: mod.default as any,
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        layouts: layouts as any[],
+        shellOpts: {
+          metadata: (mod.metadata as never) ?? {},
+          paramsJson: "{}",
+          searchParamsJson: "{}",
+          routeFile: route.file,
+          ssr: true,
+        },
+        pprCacheDir,
+        routePath: route.path,
+      });
+      count++;
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.warn(`  alab  ppr: failed to pre-render ${route.path}: ${msg}`);
+    }
+  }
+
+  if (count > 0) {
+    console.log(`  alab  ppr  → ${count} shell${count === 1 ? "" : "s"} written to ${PPR_CACHE_SUBDIR}`);
+  }
+}
+
 /** Compile the offline service worker to a standalone iife bundle. */
 async function buildOfflineSw(cwd: string): Promise<void> {
   const swEntry = new URL("../client/offline-sw.js", import.meta.url).pathname;

package/src/commands/dev.ts

@@ -63,6 +63,12 @@ async function readJsonBody(req: IncomingMessage): Promise<unknown> {
 export async function dev({ cwd, port = 3000, host = "localhost" }: DevOptions) {
   console.log("  alab  starting dev server...\n");
 
+  // Per-session build ID for skew protection in dev.
+  // A new ID is generated each time the dev server starts so that a browser
+  // tab left open across a restart will hard-reload on the next navigation
+  // rather than silently rendering with stale JS.
+  const devBuildId = `dev-${Date.now().toString(36)}`;
+
   const appDir = resolve(cwd, "app");
 
   const vite = await createServer({
@@ -459,6 +465,7 @@ export async function dev({ cwd, port = 3000, host = "localhost" }: DevOptions)
           layoutsJson,
           loadingFile,
           ssr: ssrEnabled,
+          buildId: devBuildId,
         });
         const shellAfter = htmlShellAfter({});
         const rawHtml = `${shellBefore}${ssrContent}${shellAfter}`;

package/src/components/Dynamic.tsx

@@ -0,0 +1,124 @@
+/**
+ * Alab PPR — Partial Prerendering support.
+ *
+ * Pages that export `export const ppr = true` get their static HTML shell
+ * pre-rendered at build time and stored in `.alabjs/ppr-cache/`. At runtime,
+ * the shell is served instantly (CDN-cacheable) while `<Dynamic>` sections
+ * fill in per-request via React's Suspense streaming or client-side hydration.
+ *
+ * ## How it works
+ *
+ * During the **build-time static render** (pre-render pass):
+ *   • `PPRShellProvider` sets the PPR context to `true`.
+ *   • `<Dynamic>` sees the context and renders only its `fallback` inside a
+ *     `data-ppr-hole` marker — children are omitted entirely.
+ *   • The resulting HTML is the "static shell": complete page minus dynamic parts.
+ *
+ * At **runtime**:
+ *   • `PPRShellProvider` is never rendered → context defaults to `false`.
+ *   • `<Dynamic>` behaves as a plain `<Suspense>` boundary, streaming children
+ *     as their async work resolves.
+ *
+ * ## Usage
+ *
+ * ```tsx
+ * // app/posts/[id]/page.tsx
+ * import { Dynamic } from "alabjs/components";
+ *
+ * export const ppr = true;
+ *
+ * export default function PostPage({ params }: { params: { id: string } }) {
+ *   return (
+ *     <article>
+ *       <h1>Post {params.id}</h1>
+ *       <Dynamic id="sidebar" fallback={<SidebarSkeleton />}>
+ *         <PersonalisedSidebar userId={userId} />
+ *       </Dynamic>
+ *     </article>
+ *   );
+ * }
+ * ```
+ */
+
+import { Suspense, createContext, useContext, type ReactNode } from "react";
+
+// ─── PPR shell context ─────────────────────────────────────────────────────────
+
+/**
+ * When `true`, `<Dynamic>` renders only its `fallback` placeholder.
+ * Set exclusively by `PPRShellProvider` during build-time pre-renders.
+ */
+const PPRShellCtx = createContext(false);
+
+/**
+ * @internal
+ * Wrap the root element with this during build-time PPR pre-rendering so that
+ * every `<Dynamic>` in the tree emits a stable `data-ppr-hole` placeholder
+ * instead of its children.
+ *
+ * Do **not** use this at runtime — it is an implementation detail of
+ * `preRenderPPRShell` in `src/ssr/ppr.ts`.
+ */
+export function PPRShellProvider({ children }: { children: ReactNode }) {
+  return <PPRShellCtx.Provider value={true}>{children}</PPRShellCtx.Provider>;
+}
+
+// ─── Dynamic component ────────────────────────────────────────────────────────
+
+export interface DynamicProps {
+  /**
+   * Unique identifier for this dynamic section within the page.
+   *
+   * Used to correlate the placeholder emitted in the static shell with the
+   * live content streamed at runtime. **Must be stable across renders** —
+   * treat it like a React key: short, descriptive, no dynamic values.
+   *
+   * @example "sidebar", "user-nav", "related-posts"
+   */
+  id: string;
+  /** Per-request dynamic content. Never rendered in the pre-built static shell. */
+  children: ReactNode;
+  /**
+   * Shown in the pre-built static shell **and** as the React Suspense fallback
+   * while the dynamic content is streaming in.
+   *
+   * Keep this lightweight — it is inlined into every CDN-cached response.
+   */
+  fallback?: ReactNode;
+}
+
+/**
+ * Marks a subtree as **dynamic** (per-request) within a PPR page.
+ *
+ * - **Build time** (static shell pre-render): renders `fallback` inside a
+ *   `<div data-ppr-hole="{id}">` marker. Children are not rendered.
+ * - **Runtime** (SSR + hydration): acts as a `<Suspense>` boundary. Children
+ *   stream in as their async work resolves; `fallback` is shown meanwhile.
+ *
+ * The `display: contents` style on the wrapper div means it has no visual
+ * footprint — it exists only as a DOM anchor for Alab's PPR machinery.
+ */
+export function Dynamic({ id, children, fallback = null }: DynamicProps) {
+  const isShell = useContext(PPRShellCtx);
+
+  const holeWrapper = (content: ReactNode) => (
+    <div data-ppr-hole={id} style={{ display: "contents" }}>
+      {content}
+    </div>
+  );
+
+  if (isShell) {
+    // Build-time pre-render: emit only the placeholder + fallback.
+    // Children are intentionally omitted — they contain per-request logic.
+    return holeWrapper(fallback);
+  }
+
+  // Runtime: standard Suspense boundary.
+  // The hole wrapper on the fallback preserves the DOM anchor so client-side
+  // hydration can match it to the pre-rendered shell.
+  return (
+    <Suspense fallback={holeWrapper(fallback)}>
+      {children}
+    </Suspense>
+  );
+}

package/src/components/index.ts

@@ -7,3 +7,5 @@ export { Script } from "./Script.js";
 export type { ScriptProps } from "./Script.js";
 export { Font } from "./Font.js";
 export type { FontProps } from "./Font.js";
+export { Dynamic, PPRShellProvider } from "./Dynamic.js";
+export type { DynamicProps } from "./Dynamic.js";

package/src/index.ts

@@ -6,5 +6,6 @@ export type {
   PageMetadata,
   GenerateMetadata,
   RouteParams,
+  CdnCache,
 } from "./types/index.js";
 export { createApp } from "./server/app.js";