@mandujs/core 0.53.2 → 0.54.0

package/src/runtime/ppr.ts

@@ -1,74 +1,74 @@
-/**
- * Mandu Partial Prerendering (PPR)
- *
- * Caches the static HTML shell (header, sidebar, layout) at build/first-request time,
- * then injects fresh dynamic data (loader results) per request.
- *
- * Result: TTFB of a static page + freshness of a dynamic page.
- *
- * The shell is the expensive part (React render tree traversal).
- * Data injection is cheap (JSON serialization into a script tag).
- */
-
-import { escapeJsonForInlineScript } from "./escape";
-import { serializeProps } from "../client/serialize";
-
-/**
- * PPR shell marker injected at the end of cached HTML.
- * Everything before this marker is the static shell; everything after
- * (closing tags, data scripts) is regenerated per request.
- */
-export const PPR_SHELL_MARKER = "<!--mandu:ppr-split-->";
-
-/**
- * Strip the closing </body></html> and any trailing whitespace from
- * a full SSR HTML string, then append the shell marker.
- * The result is safe to cache and later concatenated with fresh data.
- */
-export function extractShellHtml(fullHtml: string): string {
-  // Remove trailing </body></html> (case-insensitive, whitespace-tolerant)
-  const trimmed = fullHtml.replace(/<\/body>\s*<\/html>\s*$/i, "");
-  return trimmed + PPR_SHELL_MARKER;
-}
-
-/**
- * Build a streaming Response that:
- *   1. Sends the cached shell immediately (near-zero TTFB)
- *   2. Appends a script tag with fresh loader data
- *   3. Closes with </body></html>
- */
-export function createPPRResponse(
-  shellHtml: string,
-  routeId: string,
-  loaderData: unknown,
-): Response {
-  const encoder = new TextEncoder();
-
-  // Build the data payload once; avoid doing work inside the stream callback
-  const serialized = serializeProps({ serverData: loaderData });
-  const escaped = escapeJsonForInlineScript(serialized);
-  const dataScript =
-    `<script>window.__MANDU_DATA__=window.__MANDU_DATA__||{};` +
-    `window.__MANDU_DATA__[${JSON.stringify(routeId)}]=${escaped}</script>`;
-
-  const stream = new ReadableStream<Uint8Array>({
-    start(controller) {
-      // (a) Cached shell -- everything up to the split marker (inclusive)
-      controller.enqueue(encoder.encode(shellHtml));
-      // (b) Fresh data script
-      controller.enqueue(encoder.encode(dataScript));
-      // (c) Close the document
-      controller.enqueue(encoder.encode("</body></html>"));
-      controller.close();
-    },
-  });
-
-  return new Response(stream, {
-    status: 200,
-    headers: {
-      "Content-Type": "text/html; charset=utf-8",
-      "X-Content-Type-Options": "nosniff",
-      "X-Mandu-PPR": "shell-hit",
-    },
-  });
-}
+/**
+ * Mandu Partial Prerendering (PPR)
+ *
+ * Caches the static HTML shell (header, sidebar, layout) at build/first-request time,
+ * then injects fresh dynamic data (loader results) per request.
+ *
+ * Result: TTFB of a static page + freshness of a dynamic page.
+ *
+ * The shell is the expensive part (React render tree traversal).
+ * Data injection is cheap (JSON serialization into a script tag).
+ */
+
+import { escapeJsonForInlineScript } from "./escape";
+import { serializeProps } from "../client/serialize";
+
+/**
+ * PPR shell marker injected at the end of cached HTML.
+ * Everything before this marker is the static shell; everything after
+ * (closing tags, data scripts) is regenerated per request.
+ */
+export const PPR_SHELL_MARKER = "<!--mandu:ppr-split-->";
+
+/**
+ * Strip the closing </body></html> and any trailing whitespace from
+ * a full SSR HTML string, then append the shell marker.
+ * The result is safe to cache and later concatenated with fresh data.
+ */
+export function extractShellHtml(fullHtml: string): string {
+  // Remove trailing </body></html> (case-insensitive, whitespace-tolerant)
+  const trimmed = fullHtml.replace(/<\/body>\s*<\/html>\s*$/i, "");
+  return trimmed + PPR_SHELL_MARKER;
+}
+
+/**
+ * Build a streaming Response that:
+ *   1. Sends the cached shell immediately (near-zero TTFB)
+ *   2. Appends a script tag with fresh loader data
+ *   3. Closes with </body></html>
+ */
+export function createPPRResponse(
+  shellHtml: string,
+  routeId: string,
+  loaderData: unknown,
+): Response {
+  const encoder = new TextEncoder();
+
+  // Build the data payload once; avoid doing work inside the stream callback
+  const serialized = serializeProps({ serverData: loaderData });
+  const escaped = escapeJsonForInlineScript(serialized);
+  const dataScript =
+    `<script>window.__MANDU_DATA__=window.__MANDU_DATA__||{};` +
+    `window.__MANDU_DATA__[${JSON.stringify(routeId)}]=${escaped}</script>`;
+
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      // (a) Cached shell -- everything up to the split marker (inclusive)
+      controller.enqueue(encoder.encode(shellHtml));
+      // (b) Fresh data script
+      controller.enqueue(encoder.encode(dataScript));
+      // (c) Close the document
+      controller.enqueue(encoder.encode("</body></html>"));
+      controller.close();
+    },
+  });
+
+  return new Response(stream, {
+    status: 200,
+    headers: {
+      "Content-Type": "text/html; charset=utf-8",
+      "X-Content-Type-Options": "nosniff",
+      "X-Mandu-PPR": "shell-hit",
+    },
+  });
+}

package/src/runtime/registry.ts

@@ -1,171 +1,171 @@
-/**
- * Runtime manifest registry.
- *
- * This module provides the **official** accessor for generated content at
- * runtime. User code must NEVER `import` anything under `.mandu/generated/`
- * or any path containing `/generated/` — the guard rule
- * `INVALID_GENERATED_IMPORT` catches that at build time.
- *
- * Why the indirection?
- *
- * - **Hot reload** — in dev, generated modules are rebuilt and re-imported.
- *   A direct ESM import caches the first version; the registry re-reads the
- *   current manifest on every access.
- * - **Determinism** — compiled binaries (`bun build --compile`) embed a
- *   fixed manifest. Direct imports would bypass the embedded copy and fail.
- * - **ESM cache invalidation** — see #184. Transitive generated modules get
- *   stuck on stale copies when hot-reload fires; the registry's `getManifest`
- *   is the single choke point that the bundled importer invalidates cleanly.
- *
- * @see https://mandujs.com/docs/architect/generated-access
- */
-import type { RoutesManifest, RouteSpec } from "../spec/schema";
-
-// ═══════════════════════════════════════════════════════════════════════════
-// Generated artifact map
-// ═══════════════════════════════════════════════════════════════════════════
-
-/**
- * Map of generated artifacts keyed by well-known names.
- *
- * Extend this interface (via module augmentation) in consumers that emit
- * their own generated artifacts — collections, resources, db schemas, etc.
- *
- * @example Module augmentation
- * ```ts
- * declare module "@mandujs/core/runtime" {
- *   interface GeneratedRegistry {
- *     collections: Record<string, CollectionIndex>;
- *   }
- * }
- * ```
- */
-export interface GeneratedRegistry {
-  /** Route manifest — the single source of truth for page/API routes. */
-  routes: RoutesManifest;
-}
-
-/** Union of well-known generated artifact keys. */
-export type GeneratedKey = keyof GeneratedRegistry;
-
-/** Typed accessor — narrows the return shape from the key. */
-export type GeneratedShape<K extends GeneratedKey> = GeneratedRegistry[K];
-
-// ═══════════════════════════════════════════════════════════════════════════
-// Global registry state
-// ═══════════════════════════════════════════════════════════════════════════
-
-/**
- * The live manifest, populated by `registerManifest()` (typically driven by
- * `registerManifestHandlers()` from `@mandujs/cli`). Kept on `globalThis`
- * so reloading the core module in dev does not lose registration.
- */
-declare global {
-  // eslint-disable-next-line no-var
-  var __MANDU_MANIFEST__: Partial<GeneratedRegistry> | undefined;
-}
-
-function ensureGlobalSlot(): Partial<GeneratedRegistry> {
-  if (!globalThis.__MANDU_MANIFEST__) {
-    globalThis.__MANDU_MANIFEST__ = {};
-  }
-  return globalThis.__MANDU_MANIFEST__;
-}
-
-// ═══════════════════════════════════════════════════════════════════════════
-// Public API
-// ═══════════════════════════════════════════════════════════════════════════
-
-/**
- * Register a generated artifact under a well-known key.
- *
- * Called by the framework (typically from `registerManifestHandlers()` in
- * `@mandujs/cli`) during server boot. User code normally does not call this
- * directly — the only exception is tests that want to seed a manifest.
- *
- * @example Test setup
- * ```ts
- * import { registerManifest, clearGeneratedRegistry } from "@mandujs/core/runtime";
- *
- * beforeEach(() => clearGeneratedRegistry());
- * registerManifest("routes", { version: 1, routes: [] });
- * ```
- */
-export function registerManifest<K extends GeneratedKey>(
-  key: K,
-  value: GeneratedShape<K>,
-): void {
-  const slot = ensureGlobalSlot();
-  slot[key] = value;
-}
-
-/**
- * Read a generated artifact by key. Throws a helpful error if the manifest
- * has not been registered yet — this almost always means the server boot
- * skipped `registerManifestHandlers()` or the test forgot to seed fixtures.
- *
- * @example Reading the route manifest
- * ```ts
- * import { getGenerated } from "@mandujs/core/runtime";
- *
- * const manifest = getGenerated("routes");
- * for (const route of manifest.routes) {
- *   console.log(route.id, route.pattern);
- * }
- * ```
- *
- * @throws {Error} when the key has not been registered
- */
-export function getGenerated<K extends GeneratedKey>(key: K): GeneratedShape<K> {
-  const slot = globalThis.__MANDU_MANIFEST__;
-  if (!slot || !(key in slot) || slot[key] === undefined) {
-    throw new Error(
-      `[Mandu] Generated artifact "${String(key)}" not registered. ` +
-        `Call registerManifestHandlers() during server boot, or seed the ` +
-        `manifest with registerManifest("${String(key)}", …) in tests. ` +
-        `See https://mandujs.com/docs/architect/generated-access`,
-    );
-  }
-  return slot[key] as GeneratedShape<K>;
-}
-
-/**
- * Return the registered artifact, or `undefined` if absent. Prefer
- * `getGenerated()` for the common case — this variant exists for hot paths
- * where absence is not an error (e.g., optional collections).
- */
-export function tryGetGenerated<K extends GeneratedKey>(
-  key: K,
-): GeneratedShape<K> | undefined {
-  const slot = globalThis.__MANDU_MANIFEST__;
-  return slot?.[key] as GeneratedShape<K> | undefined;
-}
-
-/**
- * Return the full routes manifest. Thin wrapper around `getGenerated("routes")`
- * kept for call-site readability.
- *
- * @throws {Error} when no manifest has been registered yet
- */
-export function getManifest(): RoutesManifest {
-  return getGenerated("routes");
-}
-
-/**
- * Find a single route by its stable ID. Returns `undefined` if no match.
- * Use this instead of `manifest.routes.find(…)` at call sites that already
- * want the readability of a named helper.
- */
-export function getRouteById(id: string): RouteSpec | undefined {
-  const manifest = tryGetGenerated("routes");
-  if (!manifest) return undefined;
-  return manifest.routes.find((route) => route.id === id);
-}
-
-/**
- * Clear all registered artifacts. Test-only — production code should never
- * call this.
- */
-export function clearGeneratedRegistry(): void {
-  globalThis.__MANDU_MANIFEST__ = {};
-}
+/**
+ * Runtime manifest registry.
+ *
+ * This module provides the **official** accessor for generated content at
+ * runtime. User code must NEVER `import` anything under `.mandu/generated/`
+ * or any path containing `/generated/` — the guard rule
+ * `INVALID_GENERATED_IMPORT` catches that at build time.
+ *
+ * Why the indirection?
+ *
+ * - **Hot reload** — in dev, generated modules are rebuilt and re-imported.
+ *   A direct ESM import caches the first version; the registry re-reads the
+ *   current manifest on every access.
+ * - **Determinism** — compiled binaries (`bun build --compile`) embed a
+ *   fixed manifest. Direct imports would bypass the embedded copy and fail.
+ * - **ESM cache invalidation** — see #184. Transitive generated modules get
+ *   stuck on stale copies when hot-reload fires; the registry's `getManifest`
+ *   is the single choke point that the bundled importer invalidates cleanly.
+ *
+ * @see https://mandujs.com/docs/architect/generated-access
+ */
+import type { RoutesManifest, RouteSpec } from "../spec/schema";
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Generated artifact map
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Map of generated artifacts keyed by well-known names.
+ *
+ * Extend this interface (via module augmentation) in consumers that emit
+ * their own generated artifacts — collections, resources, db schemas, etc.
+ *
+ * @example Module augmentation
+ * ```ts
+ * declare module "@mandujs/core/runtime" {
+ *   interface GeneratedRegistry {
+ *     collections: Record<string, CollectionIndex>;
+ *   }
+ * }
+ * ```
+ */
+export interface GeneratedRegistry {
+  /** Route manifest — the single source of truth for page/API routes. */
+  routes: RoutesManifest;
+}
+
+/** Union of well-known generated artifact keys. */
+export type GeneratedKey = keyof GeneratedRegistry;
+
+/** Typed accessor — narrows the return shape from the key. */
+export type GeneratedShape<K extends GeneratedKey> = GeneratedRegistry[K];
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Global registry state
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * The live manifest, populated by `registerManifest()` (typically driven by
+ * `registerManifestHandlers()` from `@mandujs/cli`). Kept on `globalThis`
+ * so reloading the core module in dev does not lose registration.
+ */
+declare global {
+  // eslint-disable-next-line no-var
+  var __MANDU_MANIFEST__: Partial<GeneratedRegistry> | undefined;
+}
+
+function ensureGlobalSlot(): Partial<GeneratedRegistry> {
+  if (!globalThis.__MANDU_MANIFEST__) {
+    globalThis.__MANDU_MANIFEST__ = {};
+  }
+  return globalThis.__MANDU_MANIFEST__;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Public API
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Register a generated artifact under a well-known key.
+ *
+ * Called by the framework (typically from `registerManifestHandlers()` in
+ * `@mandujs/cli`) during server boot. User code normally does not call this
+ * directly — the only exception is tests that want to seed a manifest.
+ *
+ * @example Test setup
+ * ```ts
+ * import { registerManifest, clearGeneratedRegistry } from "@mandujs/core/runtime";
+ *
+ * beforeEach(() => clearGeneratedRegistry());
+ * registerManifest("routes", { version: 1, routes: [] });
+ * ```
+ */
+export function registerManifest<K extends GeneratedKey>(
+  key: K,
+  value: GeneratedShape<K>,
+): void {
+  const slot = ensureGlobalSlot();
+  slot[key] = value;
+}
+
+/**
+ * Read a generated artifact by key. Throws a helpful error if the manifest
+ * has not been registered yet — this almost always means the server boot
+ * skipped `registerManifestHandlers()` or the test forgot to seed fixtures.
+ *
+ * @example Reading the route manifest
+ * ```ts
+ * import { getGenerated } from "@mandujs/core/runtime";
+ *
+ * const manifest = getGenerated("routes");
+ * for (const route of manifest.routes) {
+ *   console.log(route.id, route.pattern);
+ * }
+ * ```
+ *
+ * @throws {Error} when the key has not been registered
+ */
+export function getGenerated<K extends GeneratedKey>(key: K): GeneratedShape<K> {
+  const slot = globalThis.__MANDU_MANIFEST__;
+  if (!slot || !(key in slot) || slot[key] === undefined) {
+    throw new Error(
+      `[Mandu] Generated artifact "${String(key)}" not registered. ` +
+        `Call registerManifestHandlers() during server boot, or seed the ` +
+        `manifest with registerManifest("${String(key)}", …) in tests. ` +
+        `See https://mandujs.com/docs/architect/generated-access`,
+    );
+  }
+  return slot[key] as GeneratedShape<K>;
+}
+
+/**
+ * Return the registered artifact, or `undefined` if absent. Prefer
+ * `getGenerated()` for the common case — this variant exists for hot paths
+ * where absence is not an error (e.g., optional collections).
+ */
+export function tryGetGenerated<K extends GeneratedKey>(
+  key: K,
+): GeneratedShape<K> | undefined {
+  const slot = globalThis.__MANDU_MANIFEST__;
+  return slot?.[key] as GeneratedShape<K> | undefined;
+}
+
+/**
+ * Return the full routes manifest. Thin wrapper around `getGenerated("routes")`
+ * kept for call-site readability.
+ *
+ * @throws {Error} when no manifest has been registered yet
+ */
+export function getManifest(): RoutesManifest {
+  return getGenerated("routes");
+}
+
+/**
+ * Find a single route by its stable ID. Returns `undefined` if no match.
+ * Use this instead of `manifest.routes.find(…)` at call sites that already
+ * want the readability of a named helper.
+ */
+export function getRouteById(id: string): RouteSpec | undefined {
+  const manifest = tryGetGenerated("routes");
+  if (!manifest) return undefined;
+  return manifest.routes.find((route) => route.id === id);
+}
+
+/**
+ * Clear all registered artifacts. Test-only — production code should never
+ * call this.
+ */
+export function clearGeneratedRegistry(): void {
+  globalThis.__MANDU_MANIFEST__ = {};
+}