@ultimat3/render 1.0.0

package/src/index.ts

@@ -0,0 +1,170 @@
+/** Public API of `@ultimat3/render`: the `route` primitive, the five modes, the table. */
+
+export type { RenderErrorCode } from './errors';
+export {
+  BudgetExceededError,
+  PrerenderFailedError,
+  RENDER_ERROR_CODES,
+  RENDER_ERROR_TITLES,
+  RouteDuplicateError,
+  RouteFileInvalidError,
+  RouteMetaMissingError,
+  RouteModeInvalidError,
+  RouteOfflineMissingError,
+  SurfaceBoundaryError,
+} from './errors';
+export type {
+  HeadRenderers,
+  HeadTag,
+  HeadTagKind,
+  LdRenderer,
+  MetaRenderer,
+  ThemeScriptOptions,
+} from './head';
+export {
+  headFromMeta,
+  mergeHead,
+  renderHead,
+  THEME_SCRIPT_MAX_BYTES,
+  themeScript,
+} from './head';
+export { headTagKey, seoRenderers, toHeadTag } from './head-seo';
+export type { IslandDirective } from './hydrate';
+export {
+  DEFAULT_REPLAY_EVENTS,
+  emitIslandAttributes,
+  emitIslandProps,
+  hydrateRuntime,
+  hydrateRuntimeBytes,
+  requiredStrategies,
+} from './hydrate';
+export type { BudgetReport, BundleGraph, GraphName, Island, RouteBytes } from './islands';
+export {
+  assertBudget,
+  checkBudget,
+  checkBudgets,
+  formatBytes,
+  graphFor,
+  parseByteBudget,
+  routeJsBytes,
+} from './islands';
+export type { ModeCheckContext, ModeSpec, RouteShape } from './modes';
+export {
+  assertModeInvariants,
+  assertModeShape,
+  defaultHydrate,
+  MODE_SPECS,
+  RENDER_MODES,
+} from './modes';
+export type {
+  CompiledPattern,
+  RegisterRouteInput,
+  RouteDescriptor,
+  RouteEntry,
+  RouteMatch,
+} from './registry';
+export {
+  clearRoutes,
+  compilePattern,
+  describeRoutes,
+  matchRoute,
+  ROUTE_FILENAME,
+  registerRoute,
+  routeCount,
+  routeEntries,
+  routeFor,
+  routePathFromFile,
+} from './registry';
+export type {
+  IsrController,
+  IsrControllerOptions,
+  IsrEntry,
+  IsrRenderFn,
+  IsrServeResult,
+  IsrState,
+  IsrStore,
+} from './render-isr';
+
+export {
+  createIsrController,
+  invalidateAndRevalidate,
+  memoryIsrStore,
+  parseTtlMs,
+} from './render-isr';
+export type { SpaShell, SpaShellInput } from './render-spa';
+export { renderSpa, renderSpaShell, SPA_ROOT_ID } from './render-spa';
+export type { SsrOptions, SsrRenderFn, SsrRenderInput } from './render-ssr';
+export { renderSsr, ssrHeaders } from './render-ssr';
+export type { StaticArtifact, StaticBuildOptions, StaticRenderFn } from './render-static';
+export {
+  assertNoPerRequestState,
+  contentHash,
+  enumeratePrerender,
+  fillPath,
+  renderStatic,
+  staticHeaders,
+  staticResult,
+} from './render-static';
+export type { StreamHole, StreamOptions, StreamPlan } from './render-stream';
+export {
+  collectStream,
+  holeId,
+  holeMarker,
+  REVEAL_SCRIPT,
+  renderStreamHtml,
+  revealChunk,
+  streamResult,
+} from './render-stream';
+export type {
+  HydrateStrategy,
+  OfflineStrategy,
+  PrerenderFn,
+  RenderMode,
+  RenderResult,
+  RevalidateConfig,
+  RouteBudget,
+  RouteConfig,
+  RouteData,
+  RouteDefinition,
+  RouteGuard,
+  RouteMetaAsyncFn,
+  RouteMetaFn,
+  RouteParams,
+} from './route';
+export {
+  defineRoute,
+  HYDRATE_STRATEGIES,
+  isRouteConfig,
+  OFFLINE_STRATEGIES,
+  tagKeys,
+} from './route';
+export type {
+  NavigateOptions,
+  NavigationGuard,
+  PrefetchContainer,
+  PrefetchLink,
+  ReactivePrimitives,
+  ResolvedRoute,
+  Router,
+  RouterHost,
+  RouterOptions,
+  RouterRoute,
+} from './router-client';
+export { createRouter } from './router-client';
+export type {
+  BoundaryRule,
+  BoundaryViolation,
+  ImportGraph,
+  ImportRef,
+  Surface,
+  SurfaceSpec,
+} from './surfaces';
+export {
+  assertSurfaceBoundary,
+  checkSurfaceBoundary,
+  importGraph,
+  SURFACE_SPECS,
+  SURFACES,
+  surfaceAllows,
+  surfaceOf,
+} from './surfaces';

package/src/islands.ts

@@ -0,0 +1,171 @@
+/**
+ * Island boundaries and the two separate bundle graphs. `site/` and `app/` never share a
+ * graph: that is the mechanical half of axiom 6 (the surface boundary in `surfaces.ts` is
+ * the other half). `site/` starts at a 0kb baseline and every byte after that is an
+ * opt-in, budgeted island.
+ */
+
+import { BudgetExceededError } from './errors';
+import type { IslandDirective } from './hydrate';
+import { hydrateRuntimeBytes } from './hydrate';
+import type { RouteEntry } from './registry';
+import type { HydrateStrategy } from './route';
+import type { Surface } from './surfaces';
+import { SURFACE_SPECS } from './surfaces';
+
+/** A bundle graph is per surface. There are exactly two that ship JS: `site` and `app`. */
+export type GraphName = 'site' | 'app';
+
+export interface Island {
+  readonly id: string;
+  readonly file: string;
+  readonly graph: GraphName;
+  readonly strategy: HydrateStrategy;
+  /** Measured from the real bundle, gzip-before-brotli agnostic: raw bytes. */
+  readonly bytes: number;
+  /** The import chain that pulled the heaviest dependency in, for error messages. */
+  readonly heaviestChain?: readonly string[];
+}
+
+export interface BundleGraph {
+  readonly name: GraphName;
+  readonly baselineBytes: number;
+  readonly islands: readonly Island[];
+}
+
+export function graphFor(surface: Surface, islands: readonly Island[]): BundleGraph {
+  const name: GraphName = surface === 'site' ? 'site' : 'app';
+  return {
+    name,
+    baselineBytes: SURFACE_SPECS[name].jsBaselineBytes,
+    islands: islands.filter((island) => island.graph === name && island.strategy !== 'never'),
+  };
+}
+
+const UNITS: Readonly<Record<string, number>> = { b: 1, kb: 1024, mb: 1024 * 1024 };
+
+/** `'40kb'` → 40960. Throws nothing: an unparseable budget is `null` and skipped. */
+export function parseByteBudget(budget: string | undefined): number | null {
+  if (budget === undefined) return null;
+  const match = /^(\d+(?:\.\d+)?)\s*(b|kb|mb)$/i.exec(budget.trim());
+  const amount = match?.[1];
+  const unit = match?.[2]?.toLowerCase();
+  if (amount === undefined || unit === undefined) return null;
+  const factor = UNITS[unit];
+  return factor === undefined ? null : Math.round(Number(amount) * factor);
+}
+
+export function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes}b`;
+  return `${Math.round((bytes / 1024) * 10) / 10}kb`;
+}
+
+export interface RouteBytes {
+  readonly total: number;
+  readonly baseline: number;
+  readonly islandBytes: number;
+  readonly runtimeBytes: number;
+  readonly heaviest: Island | null;
+}
+
+export function routeJsBytes(
+  entry: RouteEntry,
+  islands: readonly Island[],
+  directives: readonly IslandDirective[] = [],
+): RouteBytes {
+  const graph = graphFor(entry.surface, islands);
+  const onRoute = graph.islands.filter((island) => entry.islands.includes(island.id));
+  const islandBytes = onRoute.reduce((sum, island) => sum + island.bytes, 0);
+  const runtimeBytes = directives.length > 0 ? hydrateRuntimeBytes(directives) : 0;
+  const baseline = islandBytes === 0 && runtimeBytes === 0 ? 0 : graph.baselineBytes;
+  const heaviest = onRoute.reduce<Island | null>(
+    (max, island) => (max === null || island.bytes > max.bytes ? island : max),
+    null,
+  );
+  return {
+    total: baseline + islandBytes + runtimeBytes,
+    baseline,
+    islandBytes,
+    runtimeBytes,
+    heaviest,
+  };
+}
+
+export interface BudgetReport {
+  readonly path: string;
+  readonly measured: number;
+  readonly limit: number | null;
+  readonly ok: boolean;
+  readonly cause: string | null;
+}
+
+/**
+ * The build gate. Failure names the *cause* — the island and the transitive import that
+ * added the bytes — because "bundle too big" without a chain is not an instruction.
+ */
+export function checkBudget(
+  entry: RouteEntry,
+  islands: readonly Island[],
+  directives: readonly IslandDirective[] = [],
+): BudgetReport {
+  const bytes = routeJsBytes(entry, islands, directives);
+  const limit = parseByteBudget(entry.config.budget.js);
+
+  // site/ has a 0kb default: shipping JS there without declaring a budget is the failure.
+  if (limit === null && entry.surface === 'site' && bytes.total > 0) {
+    return {
+      path: entry.path,
+      measured: bytes.total,
+      limit: 0,
+      ok: false,
+      cause:
+        `${entry.path} is in site/ (0kb JS baseline) and ships ${formatBytes(bytes.total)} ` +
+        `with no budget.js${chainOf(bytes.heaviest)}`,
+    };
+  }
+
+  if (limit === null) {
+    return { path: entry.path, measured: bytes.total, limit: null, ok: true, cause: null };
+  }
+
+  const ok = bytes.total <= limit;
+  return {
+    path: entry.path,
+    measured: bytes.total,
+    limit,
+    ok,
+    cause: ok
+      ? null
+      : `${entry.path}  js ${formatBytes(bytes.total)} > ${formatBytes(limit)}${chainOf(bytes.heaviest)}`,
+  };
+}
+
+function chainOf(island: Island | null): string {
+  if (island === null) return '';
+  const chain = island.heaviestChain;
+  if (chain === undefined || chain.length === 0) return ` (heaviest island: ${island.file})`;
+  return ` (${chain.join(' → ')})`;
+}
+
+export function assertBudget(
+  entry: RouteEntry,
+  islands: readonly Island[],
+  directives: readonly IslandDirective[] = [],
+): void {
+  const report = checkBudget(entry, islands, directives);
+  if (report.ok || report.cause === null) return;
+  throw new BudgetExceededError(
+    report.cause,
+    `raise budget.js in ${entry.file} deliberately, or remove the import that added the bytes`,
+  );
+}
+
+/** `x verify` prints every route, not just the first failure. */
+export function checkBudgets(
+  entries: readonly RouteEntry[],
+  islands: readonly Island[],
+): readonly BudgetReport[] {
+  return entries
+    .map((entry) => checkBudget(entry, islands))
+    .sort((a, b) => a.path.localeCompare(b.path));
+}

package/src/modes.ts

@@ -0,0 +1,208 @@
+/**
+ * The five render modes as a table of invariants, checked at registration.
+ * Each mode has properties the framework can rely on; a config that contradicts one is
+ * rejected with `X_ROUTE_MODE_INVALID` and the exact edit that fixes it. A mode whose
+ * invariant is only documented is a mode that silently degrades in production.
+ */
+
+import { RouteModeInvalidError } from './errors';
+import type { HydrateStrategy, RenderMode, RouteConfig } from './route';
+import { HYDRATE_STRATEGIES } from './route';
+import type { Surface } from './surfaces';
+import { SURFACE_SPECS, surfaceAllows } from './surfaces';
+
+export const RENDER_MODES = ['static', 'isr', 'ssr', 'stream', 'spa'] as const;
+
+/**
+ * Everything about a route except its `meta`. Mode invariants never read metadata, and
+ * omitting it keeps these checks free of the route's data generic.
+ */
+export type RouteShape = Omit<RouteConfig, 'meta'>;
+
+export interface ModeSpec {
+  readonly mode: RenderMode;
+  /** May the render function observe the request (actor, headers, cookies, geo)? */
+  readonly perRequestState: boolean;
+  /** May the route be built ahead of time via `prerender()`? */
+  readonly prerenderable: boolean;
+  /** Does the mode need a revalidation trigger (tags or TTL)? */
+  readonly needsRevalidate: boolean;
+  /** Does the mode need at least one `<Suspense>` boundary to mean anything? */
+  readonly needsSuspense: boolean;
+  /** Does the mode need a `policy` (it renders no data, so the shell must be gated)? */
+  readonly needsPolicy: boolean;
+  readonly description: string;
+}
+
+export const MODE_SPECS: Readonly<Record<RenderMode, ModeSpec>> = Object.freeze({
+  static: {
+    mode: 'static',
+    perRequestState: false,
+    prerenderable: true,
+    needsRevalidate: false,
+    needsSuspense: false,
+    needsPolicy: false,
+    description: 'built once, served as a file',
+  },
+  isr: {
+    mode: 'isr',
+    perRequestState: false,
+    prerenderable: true,
+    needsRevalidate: true,
+    needsSuspense: false,
+    needsPolicy: false,
+    description: 'static + background regen on tag/TTL',
+  },
+  ssr: {
+    mode: 'ssr',
+    perRequestState: true,
+    prerenderable: false,
+    needsRevalidate: false,
+    needsSuspense: false,
+    needsPolicy: false,
+    description: 'per-request full render',
+  },
+  stream: {
+    mode: 'stream',
+    perRequestState: true,
+    prerenderable: false,
+    needsRevalidate: false,
+    needsSuspense: true,
+    needsPolicy: false,
+    description: 'static shell flushed instantly, holes streamed',
+  },
+  spa: {
+    mode: 'spa',
+    perRequestState: false,
+    prerenderable: true,
+    needsRevalidate: false,
+    needsSuspense: false,
+    needsPolicy: true,
+    description: 'shell only, client fetches',
+  },
+});
+
+/** Mode-local checks that need nothing but the config. Called by `defineRoute`. */
+export function assertModeShape(config: RouteShape): void {
+  // Widened on purpose: JS callers reach `defineRoute` with unvalidated strings.
+  const spec: ModeSpec | undefined = MODE_SPECS[config.render];
+  if (spec === undefined) {
+    throw new RouteModeInvalidError(
+      `render: ${JSON.stringify(config.render)} is not a render mode`,
+      `use one of ${RENDER_MODES.join(' | ')}`,
+    );
+  }
+
+  if (!HYDRATE_STRATEGIES.includes(config.hydrate)) {
+    throw new RouteModeInvalidError(
+      `hydrate: ${JSON.stringify(config.hydrate)} is not a hydration strategy`,
+      `use one of ${HYDRATE_STRATEGIES.join(' | ')}`,
+    );
+  }
+
+  // static: no per-request state. `policy` needs an actor and `revalidate` needs a
+  // request to regenerate on — both mean the page is not a file on disk.
+  if (config.render === 'static' && config.policy !== undefined) {
+    throw new RouteModeInvalidError(
+      "render: 'static' cannot read per-request state, but a `policy` was declared " +
+        `(${config.policy.permission} needs an actor)`,
+      "change render to 'ssr' (fresh, gated) or 'spa' (gated shell), or drop the policy",
+    );
+  }
+  if (config.render === 'static' && config.revalidate !== undefined) {
+    throw new RouteModeInvalidError(
+      "render: 'static' is built once and never regenerates, but `revalidate` was declared",
+      "change render to 'isr' to keep the revalidate trigger",
+    );
+  }
+
+  // isr: needs a trigger, otherwise it is `static` wearing a costume.
+  if (config.render === 'isr' && !hasRevalidateTrigger(config)) {
+    throw new RouteModeInvalidError(
+      "render: 'isr' requires a regeneration trigger, but revalidate has neither tags nor ttl",
+      "add revalidate: { tags: [tag.post] } or revalidate: { ttl: '5m' }",
+    );
+  }
+
+  // ssr: cannot be prerendered — the whole point is that it runs per request.
+  if (config.render === 'ssr' && config.prerender !== undefined) {
+    throw new RouteModeInvalidError(
+      "render: 'ssr' renders per request and cannot be prerendered, but `prerender` was declared",
+      "change render to 'isr' to prerender and regenerate, or remove prerender",
+    );
+  }
+
+  // spa: the shell carries no data, so authz has to live on the route itself.
+  if (config.render === 'spa' && config.policy === undefined) {
+    throw new RouteModeInvalidError(
+      "render: 'spa' ships a shell with no server-rendered data and requires a `policy`",
+      "add policy: can('dashboard:read') — or use 'stream' for a public page",
+    );
+  }
+}
+
+function hasRevalidateTrigger(config: RouteShape): boolean {
+  const revalidate = config.revalidate;
+  if (revalidate === undefined) return false;
+  const hasTags = revalidate.tags !== undefined && revalidate.tags.length > 0;
+  const hasTtl = revalidate.ttl !== undefined && revalidate.ttl !== '';
+  return hasTags || hasTtl;
+}
+
+export interface ModeCheckContext {
+  readonly file: string;
+  readonly path: string;
+  readonly surface: Surface;
+  /** Counted from the route module's JSX by the build. `stream` needs at least one. */
+  readonly suspenseBoundaries: number;
+}
+
+/** Checks that need the surrounding module and surface. Called by `registerRoute`. */
+export function assertModeInvariants(config: RouteShape, ctx: ModeCheckContext): void {
+  if (ctx.surface === 'api') {
+    throw new RouteModeInvalidError(
+      `${ctx.file} is in api/, which renders nothing, but declares render: '${config.render}'`,
+      `move ${ctx.file} into site/ or app/, or replace defineRoute with an action`,
+    );
+  }
+
+  if (!surfaceAllows(ctx.surface, config.render)) {
+    const allowed = SURFACE_SPECS[ctx.surface].allowedModes.join(' | ');
+    throw new RouteModeInvalidError(
+      `${ctx.file} is in ${ctx.surface}/ and declares render: '${config.render}', ` +
+        `which ${ctx.surface}/ does not allow`,
+      `use one of ${allowed} in ${ctx.file}`,
+    );
+  }
+
+  // `budget` is always on the descriptor; `budget.js` is the field that stays optional,
+  // and its absence is the failure — site/ is 0kb until a route says otherwise, in bytes.
+  if (ctx.surface === 'site' && config.hydrate !== 'never' && config.budget.js === undefined) {
+    throw new RouteModeInvalidError(
+      `${ctx.file} is in site/ (0kb JS baseline) and opts into hydrate: '${config.hydrate}' ` +
+        'without a JS budget',
+      `add budget: { js: '10kb' } to ${ctx.file} — hydration on site/ is explicit and budgeted`,
+    );
+  }
+
+  if (config.render === 'stream' && ctx.suspenseBoundaries < 1) {
+    throw new RouteModeInvalidError(
+      `${ctx.file} declares render: 'stream' but has no <Suspense> boundary, so there is ` +
+        'nothing to stream — the whole page waits like ssr',
+      `wrap the data-dependent part of ${ctx.file} in <Suspense fallback={…}> ` +
+        "or change render to 'ssr'",
+    );
+  }
+
+  if (config.prerender !== undefined && !MODE_SPECS[config.render].prerenderable) {
+    throw new RouteModeInvalidError(
+      `${ctx.file} declares prerender with render: '${config.render}', which is not prerenderable`,
+      `remove prerender from ${ctx.file} or change render to 'static' | 'isr'`,
+    );
+  }
+}
+
+/** Default hydration timing per surface — `site/` ships nothing unless asked. */
+export function defaultHydrate(surface: Surface): HydrateStrategy {
+  return surface === 'site' ? 'never' : 'idle';
+}