@ultimat3/render 1.0.0

package/src/render-ssr.ts

@@ -0,0 +1,60 @@
+/**
+ * `ssr` — per-request full render. The whole document waits for the slowest dependency,
+ * which is exactly the trade you want for a fresh SEO page and exactly the trade you do
+ * not want for an app page (use `stream`).
+ */
+
+import type { Ctx } from '@ultimat3/core';
+import type { RouteEntry } from './registry';
+import type { RenderResult, RouteParams } from './route';
+
+export interface SsrRenderInput {
+  readonly entry: RouteEntry;
+  readonly params: RouteParams;
+  readonly url: URL;
+  readonly ctx: Ctx;
+}
+
+export type SsrRenderFn = (input: SsrRenderInput) => string | Promise<string>;
+
+export interface SsrOptions {
+  readonly buildId: string;
+  /** Extra `Vary` dimensions beyond the defaults. */
+  readonly vary?: readonly string[];
+  readonly status?: number;
+}
+
+export async function renderSsr(
+  input: SsrRenderInput,
+  render: SsrRenderFn,
+  options: SsrOptions,
+): Promise<RenderResult> {
+  const html = await render(input);
+  return {
+    status: options.status ?? 200,
+    headers: ssrHeaders(input.entry, options),
+    body: html,
+  };
+}
+
+/**
+ * A gated page is never shared cache material: one actor's HTML in a CDN is the same bug
+ * class as a cache key missing its tenant.
+ */
+export function ssrHeaders(
+  entry: RouteEntry,
+  options: SsrOptions,
+): Readonly<Record<string, string>> {
+  const gated = entry.config.policy !== undefined;
+  const vary = new Set<string>(['accept-language', ...(options.vary ?? [])]);
+  if (gated) vary.add('cookie');
+
+  return {
+    'content-type': 'text/html; charset=utf-8',
+    'cache-control': gated
+      ? 'private, no-store'
+      : 'public, max-age=0, s-maxage=30, stale-while-revalidate=300',
+    vary: [...vary].sort().join(', '),
+    'x-ultimate-build': options.buildId,
+  };
+}

package/src/render-static.ts

@@ -0,0 +1,170 @@
+/**
+ * `static` — build-time render. Enumerates `prerender()`, renders each params set once,
+ * content-hashes the output. The hash is the artifact's identity: it becomes the ETag,
+ * the precache revision in `sw.js`, and the asset filename suffix.
+ */
+
+import { useContext } from '@ultimat3/core';
+import { PrerenderFailedError, RouteModeInvalidError } from './errors';
+import type { RouteEntry } from './registry';
+import type { RenderResult, RouteParams } from './route';
+
+export interface StaticArtifact {
+  readonly path: string;
+  readonly params: RouteParams;
+  readonly html: string;
+  /** FNV-1a of the HTML. Stable across machines and across Bun versions. */
+  readonly hash: string;
+  /** Where the file lands on disk, relative to the build output root. */
+  readonly outputPath: string;
+  readonly headers: Readonly<Record<string, string>>;
+}
+
+export type StaticRenderFn = (input: {
+  readonly path: string;
+  readonly params: RouteParams;
+}) => string | Promise<string>;
+
+/** Deterministic, dependency-free 32-bit FNV-1a, hex. */
+export function contentHash(input: string): string {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < input.length; i += 1) {
+    hash ^= input.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return hash.toString(16).padStart(8, '0');
+}
+
+/**
+ * `static` must not observe the request. If a request-scoped context is live while a
+ * static route renders, the output would depend on whoever triggered the build — a bug
+ * that only shows up as one user's data cached for everyone.
+ */
+export function assertNoPerRequestState(file: string): void {
+  let ctx: unknown;
+  try {
+    ctx = useContext();
+  } catch {
+    return; // no ambient context — the expected build-time situation
+  }
+  if (typeof ctx !== 'object' || ctx === null) return;
+  if ('request' in ctx || 'actor' in ctx) {
+    throw new RouteModeInvalidError(
+      `${file} declares render: 'static' but rendered inside a request context ` +
+        '(actor/request visible), so its output would leak per-request state',
+      `change render to 'ssr' in ${file}, or move the request-dependent part into an island`,
+    );
+  }
+}
+
+/** Normalize `prerender()` output. A bare string fills the route's one dynamic param. */
+export async function enumeratePrerender(entry: RouteEntry): Promise<readonly RouteParams[]> {
+  const prerender = entry.config.prerender;
+  if (prerender === undefined) {
+    return entry.pattern.keys.length === 0 ? [{}] : [];
+  }
+
+  let produced: readonly (string | RouteParams)[];
+  try {
+    produced = await prerender();
+  } catch (error) {
+    throw new PrerenderFailedError(
+      `prerender() for ${entry.path} threw: ${describe(error)}`,
+      `fix prerender in ${entry.file} — it runs at build time with no request context`,
+    );
+  }
+
+  if (!Array.isArray(produced)) {
+    throw new PrerenderFailedError(
+      `prerender() for ${entry.path} returned ${typeof produced}, expected an array`,
+      `return an array of params from prerender in ${entry.file}`,
+    );
+  }
+
+  const keys = entry.pattern.keys;
+  return produced.map((item) => {
+    if (typeof item !== 'string') return item;
+    const only = keys[0];
+    if (keys.length !== 1 || only === undefined) {
+      throw new PrerenderFailedError(
+        `prerender() for ${entry.path} returned the bare string ${JSON.stringify(item)} ` +
+          `but the route has ${keys.length} dynamic params (${keys.join(', ')})`,
+        `return objects from prerender in ${entry.file}, e.g. { ${keys.join(': …, ')}: … }`,
+      );
+    }
+    return { [only]: item };
+  });
+}
+
+export interface StaticBuildOptions {
+  readonly buildId: string;
+  /** Extension-less output files get `/index.html` appended. */
+  readonly indexFile?: string;
+}
+
+export async function renderStatic(
+  entry: RouteEntry,
+  render: StaticRenderFn,
+  options: StaticBuildOptions,
+): Promise<readonly StaticArtifact[]> {
+  assertNoPerRequestState(entry.file);
+  const paramSets = await enumeratePrerender(entry);
+  const indexFile = options.indexFile ?? 'index.html';
+
+  const artifacts: StaticArtifact[] = [];
+  for (const params of paramSets) {
+    const path = fillPath(entry.pattern.source, params);
+    let html: string;
+    try {
+      html = await render({ path, params });
+    } catch (error) {
+      throw new PrerenderFailedError(
+        `rendering ${path} failed: ${describe(error)}`,
+        `run \`x build --route ${path}\` to reproduce, then fix ${entry.file}`,
+      );
+    }
+    const hash = contentHash(html);
+    artifacts.push({
+      path,
+      params,
+      html,
+      hash,
+      outputPath: `${path === '/' ? '' : path}/${indexFile}`.replace(/^\/+/, ''),
+      headers: staticHeaders(hash, options.buildId),
+    });
+  }
+  return artifacts;
+}
+
+export function staticHeaders(hash: string, buildId: string): Readonly<Record<string, string>> {
+  return {
+    'content-type': 'text/html; charset=utf-8',
+    // Revalidate cheaply: the HTML URL is stable, its content hash is not.
+    'cache-control': 'public, max-age=0, must-revalidate',
+    etag: `"${hash}"`,
+    'x-ultimate-build': buildId,
+  };
+}
+
+export function staticResult(artifact: StaticArtifact): RenderResult {
+  return { status: 200, headers: artifact.headers, body: artifact.html };
+}
+
+/** `/blog/:slug` + `{ slug: 'hello' }` → `/blog/hello`. */
+export function fillPath(pattern: string, params: RouteParams): string {
+  return (
+    pattern
+      .split('/')
+      .map((segment) => {
+        if (segment.startsWith(':')) return params[segment.slice(1)] ?? segment;
+        if (segment.startsWith('*')) return params[segment.slice(1)] ?? '';
+        return segment;
+      })
+      .join('/')
+      .replace(/\/+$/, '') || '/'
+  );
+}
+
+function describe(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/render-stream.ts

@@ -0,0 +1,149 @@
+/**
+ * `stream` — the default for `app/` pages. A genuinely static shell is flushed on the
+ * first tick; every `<Suspense>` boundary becomes a hole that is filled out of order, in
+ * completion order, as its data resolves.
+ *
+ * Why the shell is free here: Solid compiles templates to DOM operations and tracks
+ * updates with signals, so there is no VDOM tree to replay and no hydration pass over the
+ * shell. A resolved hole patches the exact nodes bound to it; the surrounding markup is
+ * never re-executed. In a VDOM framework a streamed shell still pays to hydrate the whole
+ * tree, which buys TTFB but not TBT — here it buys both, so a `<Suspense>` boundary that
+ * contains no interactive island costs literally zero JS.
+ */
+
+import { logger } from '@ultimat3/core';
+import type { RenderResult } from './route';
+
+export interface StreamHole {
+  /** Stable within a response; becomes the DOM id, so keep it short. */
+  readonly id: string;
+  /** Rendered synchronously into the first flush (the `<Suspense fallback>`). */
+  readonly fallback: string;
+  readonly resolve: () => Promise<string>;
+}
+
+export interface StreamPlan {
+  /** `<!doctype html><html …><head>…</head><body>` — everything before the shell. */
+  readonly head: string;
+  /** The shell markup, containing one `holeMarker()` per hole. */
+  readonly shell: string;
+  readonly holes: readonly StreamHole[];
+  /** `</body></html>` — flushed after the last hole resolves. */
+  readonly tail?: string;
+}
+
+const HOLE_PREFIX = 'x:';
+
+export function holeId(id: string): string {
+  return `${HOLE_PREFIX}${id}`;
+}
+
+/** The placeholder that sits in the first flush, holding the fallback markup. */
+export function holeMarker(id: string, fallback: string): string {
+  return `<x-hole id="${holeId(id)}">${fallback}</x-hole>`;
+}
+
+/**
+ * The entire client half of out-of-order streaming. Inline, uncompressed, ~200 bytes; it
+ * moves a late `<template>`'s content into the placeholder that is already on screen.
+ */
+export const REVEAL_SCRIPT =
+  "<script>window.$X=function(i){var t=document.querySelector('template[data-x-hole=\"'+i+'\"]')," +
+  's=document.getElementById(i);if(t&&s){s.replaceWith(t.content);t.remove()}}</script>';
+
+export function revealChunk(id: string, html: string): string {
+  const key = holeId(id);
+  return `<template data-x-hole="${key}">${html}</template><script>$X("${key}")</script>`;
+}
+
+export interface StreamOptions {
+  readonly buildId: string;
+  /** Rendered into a hole whose promise rejected. Keep it a token-styled inline block. */
+  readonly errorFallback?: (holeId: string) => string;
+}
+
+/**
+ * Flush order is completion order, not declaration order — a fast hole never waits behind
+ * a slow one. The stream closes only after every hole has settled, so a rejected boundary
+ * degrades to its error fallback instead of truncating the document.
+ */
+export function renderStreamHtml(
+  plan: StreamPlan,
+  options: StreamOptions,
+): ReadableStream<Uint8Array> {
+  const encoder = new TextEncoder();
+  const tail = plan.tail ?? '</body></html>';
+  const errorFallback =
+    options.errorFallback ?? ((id) => `<div data-x-hole-error="${id}" hidden></div>`);
+
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      const write = (chunk: string): void => {
+        controller.enqueue(encoder.encode(chunk));
+      };
+
+      // No holes, no reveal script: a page that streams nothing pays nothing.
+      write(plan.head + (plan.holes.length > 0 ? REVEAL_SCRIPT : '') + plan.shell);
+
+      let pending = plan.holes.length;
+      if (pending === 0) {
+        write(tail);
+        controller.close();
+        return;
+      }
+
+      const settle = (): void => {
+        pending -= 1;
+        if (pending === 0) {
+          write(tail);
+          controller.close();
+        }
+      };
+
+      for (const hole of plan.holes) {
+        void hole
+          .resolve()
+          .then(
+            (html) => {
+              write(revealChunk(hole.id, html));
+            },
+            (error: unknown) => {
+              logger.warn(
+                `stream hole ${hole.id} rejected: ${error instanceof Error ? error.message : String(error)}`,
+              );
+              write(revealChunk(hole.id, errorFallback(hole.id)));
+            },
+          )
+          .then(settle, settle);
+      }
+    },
+  });
+}
+
+export function streamResult(plan: StreamPlan, options: StreamOptions, status = 200): RenderResult {
+  return {
+    status,
+    headers: {
+      'content-type': 'text/html; charset=utf-8',
+      'cache-control': 'private, no-store',
+      // Proxies that buffer defeat the entire mode.
+      'x-accel-buffering': 'no',
+      'transfer-encoding': 'chunked',
+      'x-ultimate-build': options.buildId,
+    },
+    body: renderStreamHtml(plan, options),
+  };
+}
+
+/** Test/SSR-to-string helper: drain a stream into one string. */
+export async function collectStream(stream: ReadableStream<Uint8Array>): Promise<string> {
+  const decoder = new TextDecoder();
+  const reader = stream.getReader();
+  let out = '';
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (value !== undefined) out += decoder.decode(value, { stream: true });
+  }
+  return out + decoder.decode();
+}

package/src/route.ts

@@ -0,0 +1,158 @@
+/**
+ * The `route` primitive. `defineRoute` is the only way to declare a URL's render mode,
+ * offline strategy, hydration timing and metadata, and it hands back a descriptor that is
+ * already normalized: `meta` always awaits, `budget` is always there.
+ *
+ * `offline`, `hydrate` and `meta` are REQUIRED BY THE TYPE. That is axiom 3 — enforced,
+ * not documented — expressed in the type system: a route that forgets its offline
+ * strategy or its `<head>` is a compile error, not a checklist item nobody reads.
+ */
+
+import type { CacheTag } from '@ultimat3/cache';
+import { serializeTags } from '@ultimat3/cache';
+import type { RouteMeta } from '@ultimat3/seo';
+import { RouteMetaMissingError, RouteOfflineMissingError } from './errors';
+import { assertModeShape } from './modes';
+
+export type RenderMode = 'static' | 'isr' | 'ssr' | 'stream' | 'spa';
+export type OfflineStrategy = 'precache' | 'runtime' | 'network-only';
+export type HydrateStrategy = 'idle' | 'visible' | 'interaction' | 'never';
+
+export const OFFLINE_STRATEGIES = ['precache', 'runtime', 'network-only'] as const;
+export const HYDRATE_STRATEGIES = ['idle', 'visible', 'interaction', 'never'] as const;
+
+export type RouteParams = Readonly<Record<string, string>>;
+export type RouteData = Readonly<Record<string, unknown>>;
+
+/** ISR trigger. At least one of `tags` / `ttl` is required by `modes.ts`. */
+export interface RevalidateConfig {
+  readonly tags?: readonly CacheTag[];
+  /** `'5m'`, `'1h'`, `'7d'` or milliseconds. */
+  readonly ttl?: string | number;
+}
+
+export interface RouteBudget {
+  /** `'40kb'` — measured from the real bundle graph, not the source size. */
+  readonly js?: string;
+  readonly css?: string;
+  /** Milliseconds, median of N headless runs. */
+  readonly lcp?: number;
+  readonly cls?: number;
+  readonly tbt?: number;
+}
+
+/**
+ * Structural view of a `@ultimat3/policy` guard. Render only needs to know a route HAS
+ * one (the `spa` invariant) — evaluation stays in policy, so there is exactly one authz
+ * system and render cannot grow a second door.
+ */
+export interface RouteGuard {
+  readonly permission: string;
+}
+
+/** What an author writes. Sync or async, whichever the page's data needs. */
+export type RouteMetaFn<TData = RouteData> = (data: TData) => RouteMeta | Promise<RouteMeta>;
+
+/** What the descriptor hands back. One shape, so no consumer branches on a thenable. */
+export type RouteMetaAsyncFn<TData = RouteData> = (data: TData) => Promise<RouteMeta>;
+
+/** Returns the params to build at deploy time. Bare strings fill a single dynamic param. */
+export type PrerenderFn = () =>
+  | readonly (string | RouteParams)[]
+  | Promise<readonly (string | RouteParams)[]>;
+
+/** The input shape of `defineRoute` — exactly the contract's eight keys, nothing else. */
+export interface RouteDefinition<TData = RouteData> {
+  readonly render: RenderMode;
+  readonly revalidate?: RevalidateConfig;
+  readonly prerender?: PrerenderFn;
+  readonly offline: OfflineStrategy;
+  readonly hydrate: HydrateStrategy;
+  readonly budget?: RouteBudget;
+  readonly meta: RouteMetaFn<TData>;
+  readonly policy?: RouteGuard;
+}
+
+/**
+ * The frozen descriptor. `kind` lets the registry reject non-route exports.
+ *
+ * Two fields are narrower here than in the declaration so every consumer reads one shape:
+ * `meta` always returns a promise, and `budget` is always an object. Its *fields* stay
+ * optional — `budget.js === undefined` still means "this route declared no JS budget",
+ * which is exactly what `modes.ts` fails a hydrating `site/` route on.
+ */
+export interface RouteConfig<TData = RouteData> extends RouteDefinition<TData> {
+  readonly kind: 'route';
+  readonly meta: RouteMetaAsyncFn<TData>;
+  readonly budget: RouteBudget;
+}
+
+/** What every render mode hands back to `@ultimat3/http`'s `html()` / `stream()`. */
+export interface RenderResult {
+  readonly status: number;
+  readonly headers: Readonly<Record<string, string>>;
+  readonly body: string | ReadableStream<Uint8Array>;
+}
+
+/**
+ * Route descriptors carry tags in `@ultimat3/cache`'s wire form (`post`, `post:123`), the
+ * same strings every cache tier speaks. Render never invents a key convention of its own.
+ */
+export function tagKeys(tags: readonly CacheTag[] | undefined): readonly string[] {
+  return tags === undefined ? [] : serializeTags(tags);
+}
+
+/**
+ * Declare a route. Validates the shape (for JS callers who bypass the types) and the
+ * mode-local invariants immediately, so a bad route fails at module evaluation — build
+ * time — rather than on the first request in production.
+ */
+export function defineRoute<TData = RouteData>(
+  definition: RouteDefinition<TData>,
+): RouteConfig<TData> {
+  const def = definition as Partial<RouteDefinition<TData>>;
+
+  if (def.offline === undefined) {
+    throw new RouteOfflineMissingError(
+      'defineRoute() called without an `offline` strategy',
+      "add offline: 'precache' | 'runtime' | 'network-only' to defineRoute",
+    );
+  }
+  if (!OFFLINE_STRATEGIES.includes(def.offline)) {
+    throw new RouteOfflineMissingError(
+      `offline: ${JSON.stringify(def.offline)} is not a known strategy`,
+      `use one of ${OFFLINE_STRATEGIES.join(' | ')}`,
+    );
+  }
+  if (typeof def.meta !== 'function') {
+    throw new RouteMetaMissingError(
+      'defineRoute() called without a `meta` function',
+      'add meta: () => ({ title, description }) to defineRoute',
+    );
+  }
+
+  const declaredMeta = def.meta;
+  const config: RouteConfig<TData> = {
+    kind: 'route',
+    render: def.render as RenderMode,
+    offline: def.offline,
+    hydrate: def.hydrate as HydrateStrategy,
+    // Wrapped rather than stored: the declaration may be sync, the descriptor never is.
+    // A meta that throws synchronously becomes a rejection here, so `await config.meta(d)`
+    // is the one way to fail as well as the one way to succeed.
+    meta: async (data: TData) => declaredMeta(data),
+    // Always an object. `budget.js` is the only reach a consumer needs, so an undeclared
+    // budget is `{}` instead of a second undefined-check at every call site.
+    budget: def.budget ?? {},
+    ...(def.revalidate ? { revalidate: def.revalidate } : {}),
+    ...(def.prerender ? { prerender: def.prerender } : {}),
+    ...(def.policy ? { policy: def.policy } : {}),
+  };
+
+  assertModeShape(config);
+  return Object.freeze(config);
+}
+
+export function isRouteConfig(value: unknown): value is RouteConfig {
+  return typeof value === 'object' && value !== null && 'kind' in value && value.kind === 'route';
+}