@ultimat3/render 22.0.0 → 22.2.0

package/CLAUDE.md

@@ -25,7 +25,7 @@ axiom 6). Never `cli` (upward).
 |---|---|
 | `offline`, `meta` | required by `RouteDefinition`. Never make them optional. |
 | `hydrate` | optional, **derived from `island()`** — `'interaction'` when the module declared one, `'never'` when not. Declaring it still wins and is the only way to reach `idle` / `visible`. Never give an island its own strategy: `RouteDescriptor.hydrate` is read by `sw.js`, the web manifest and `x routes`. |
-| `defineRoute` shape | exactly the contract's 9 keys. New route *metadata* goes inside `meta`. |
+| `defineRoute` shape | exactly the contract's 10 keys (`cache`, `ssr` only, is the tenth). New route *metadata* goes inside `meta`. |
 | `load` | optional, and the ONE server-side data seam. Resolved once per render by `routeDataFor()` and handed to **both** `meta` and the page component. Absent `load`, the context IS the data (`{ params, url }`). |
 | `load` is required when the context cannot supply the data | `LoadRequirement<TData>` in `defineRoute`'s parameter. `RouteContext` is a type ALIAS on purpose — only an alias carries the implicit index signature that makes it a `RouteData`. |
 | A loader's own error | rethrown only when `isUltimateError` says so (core's brand), never a `code` property and never `instanceof UltimateError` — a tier-0 error is branded, not a subclass. Everything else is `X_ROUTE_LOAD_FAILED`. |

package/README.md

@@ -61,8 +61,10 @@ returns its data through `withStatus(404, data)`. The same object comes back, so
 it (`routeStatusOf`), and a 4xx or 5xx is `robots: noindex` by construction, applied by the
 descriptor's `meta` after the route's own ran. Not a throw: a throw is the framework's error page,
 outside the app's shell, and `As of 2026-09-07` that was the only way to a 404 — ai-maxxing's
-`/fleet/nope` rendered the right page and answered 200. A 3xx is `X_ROUTE_STATUS_INVALID`; a
-redirect is `@ultimat3/http`'s `redirect()`. The static export writes the document whatever the
+`/fleet/nope` rendered the right page and answered 200. A 3xx is `X_ROUTE_STATUS_INVALID`. A
+redirect is `setRedirect(location, status)` from `@ultimat3/http`, called inside `load`: the page
+path answers that 3xx before rendering a document, `private, no-store` unless the route declares a
+`cache` (`As of 2026-09-24`, #525). The static export writes the document whatever the
 loader said — a file has no status — and the build's measurer, which renders with `params: {}`,
 never fails on a loader answering 404.
 
@@ -106,6 +108,15 @@ a rejection, so one `catch` covers both. The budget's *fields* stay optional:
 `budget.js === undefined` still means "declared no JS budget", which is exactly what fails
 a hydrating `site/` route below.
 
+## `cache` on an `ssr` route
+
+`defineRoute({ render: 'ssr', cache: 'no-store' | CacheHint })` replaces `ssrHeaders`' default
+(`private, no-store` gated, `public, max-age=0, s-maxage=30, stale-while-revalidate=300` ungated).
+`'no-store'` is `private, no-store`; a hint (`@ultimat3/http`'s `CacheHint`, minus `tags`) goes
+through `cacheControl()`, and its `vary` joins the defaults. `As of 2026-09-24` (#525). The type is
+`RouteCache`; `@ultimat3/http` is a dependency of this package for that type and for
+`cacheControl` in the server half.
+
 ## Mode invariants, checked at registration
 
 | Mode | Invariant | Error if violated |
@@ -113,6 +124,8 @@ a hydrating `site/` route below.
 | `static` | no per-request state — no `policy`, no `revalidate` | `X_ROUTE_MODE_INVALID` |
 | `isr` | needs a trigger: `revalidate.tags` or `revalidate.ttl`; **no `policy`** — one cached document per URL cannot answer two actors | `X_ROUTE_MODE_INVALID` |
 | `ssr` | cannot be prerendered | `X_ROUTE_MODE_INVALID` |
+| any but `ssr` | declares no `cache` — `static`/`isr` headers are the mode, a `stream` is always `private, no-store` | `X_ROUTE_MODE_INVALID` |
+| gated (`policy`) | its `cache` is never `public`/`immutable` — one actor's document in a shared cache | `X_ROUTE_MODE_INVALID` |
 | `stream` | at least one `<Suspense>` boundary | `X_ROUTE_MODE_INVALID` |
 
 Plus surface rules: `site/` allows `static | isr | ssr`, `app/` allows `stream | ssr`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/render",
-  "version": "22.0.0",
+  "version": "22.2.0",
   "description": "The route primitive and the five render modes: static, isr, ssr, stream, spa.",
   "license": "MIT",
   "type": "module",
@@ -36,10 +36,11 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "22.0.0",
-    "@ultimat3/core": "22.0.0",
-    "@ultimat3/i18n": "22.0.0",
-    "@ultimat3/seo": "22.0.0",
+    "@ultimat3/cache": "22.2.0",
+    "@ultimat3/core": "22.2.0",
+    "@ultimat3/http": "22.2.0",
+    "@ultimat3/i18n": "22.2.0",
+    "@ultimat3/seo": "22.2.0",
     "sass": "1.104.0"
   }
 }

package/src/index.ts

@@ -128,6 +128,7 @@ export type {
   RenderResult,
   RevalidateConfig,
   RouteBudget,
+  RouteCache,
   RouteConfig,
   RouteContext,
   RouteData,

package/src/modes.ts

@@ -133,6 +133,27 @@ export function assertModeShape(config: RouteShape): void {
     );
   }
 
+  // cache: the `ssr` mode's key alone. `static` and `isr` are content-hashed / TTL'd documents
+  // whose headers ARE the mode, and a `stream` is always `private, no-store` — a declaration on
+  // any of them would be read by nothing.
+  if (config.cache !== undefined && config.render !== 'ssr') {
+    throw new RouteModeInvalidError(
+      `render: '${config.render}' decides its own cache headers, but \`cache\` was declared`,
+      "change render to 'ssr' to declare the cache, or remove cache",
+    );
+  }
+  // A gated page is one actor's document. A shared-cache offer on it is the tenant-leak class
+  // `ssrHeaders` exists to rule out, so a guard can narrow the cache and never widen it.
+  const mode =
+    config.cache === undefined || config.cache === 'no-store' ? 'no-store' : config.cache.mode;
+  if (config.policy !== undefined && (mode === 'public' || mode === 'immutable')) {
+    throw new RouteModeInvalidError(
+      `a route gated by ${config.policy.permission} declares cache mode '${mode}', which offers ` +
+        "one actor's document to a shared cache",
+      "declare cache: 'no-store' or { mode: 'private', … }, or drop the policy",
+    );
+  }
+
   // ssr: cannot be prerendered — the whole point is that it runs per request.
   if (config.render === 'ssr' && config.prerender !== undefined) {
     throw new RouteModeInvalidError(

package/src/render-ssr.ts

@@ -5,9 +5,10 @@
  */
 
 import type { Ctx } from '@ultimat3/core';
+import { cacheControl } from '@ultimat3/http';
 import { finiteStatus } from './finite-status';
 import type { RouteEntry } from './registry';
-import type { RenderResult, RouteParams } from './route';
+import type { RenderResult, RouteCache, RouteParams } from './route';
 
 export interface SsrRenderInput {
   readonly entry: RouteEntry;
@@ -40,23 +41,45 @@ export async function renderSsr(
   };
 }
 
+const PRIVATE_NO_STORE = 'private, no-store';
+
+/**
+ * The route's own `cache`, as a header. `no-store` in either spelling is `private, no-store`, the
+ * gated page's answer: `private` is what `documentCarriesScope` reads, so a page the author just
+ * made uncacheable carries its principal scope like every other private document. Everything else
+ * is `@ultimat3/http`'s one emitter, never a second serializer.
+ */
+function declaredCacheControl(cache: RouteCache): string {
+  if (cache === 'no-store' || cache.mode === 'no-store') return PRIVATE_NO_STORE;
+  return cacheControl(cache);
+}
+
 /**
  * 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.
+ * class as a cache key missing its tenant. A route's declared `cache` replaces the default —
+ * `modes.ts` refuses a gated one that would widen it — and the pipeline's `cache-headers` stage
+ * still reviews a `public` answer against the actor, so a signed-in visitor never gets one.
  */
 export function ssrHeaders(
   entry: RouteEntry,
   options: SsrOptions,
 ): Readonly<Record<string, string>> {
   const gated = entry.config.policy !== undefined;
+  const declared = entry.config.cache;
   const vary = new Set<string>(['accept-language', ...(options.vary ?? [])]);
   if (gated) vary.add('cookie');
+  if (declared !== undefined && declared !== 'no-store') {
+    for (const name of declared.vary ?? []) vary.add(name);
+  }
 
   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',
+    'cache-control':
+      declared !== undefined
+        ? declaredCacheControl(declared)
+        : 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/route.ts

@@ -16,6 +16,7 @@ import type { CacheTag } from '@ultimat3/cache';
 import { serializeTags } from '@ultimat3/cache';
 import type { HydrateStrategy, OfflineStrategy, RenderMode } from '@ultimat3/core';
 import { OFFLINE_STRATEGIES } from '@ultimat3/core';
+import type { CacheHint } from '@ultimat3/http';
 import type { Translator } from '@ultimat3/i18n';
 import type { RouteMeta } from '@ultimat3/seo';
 import { RouteLoadInvalidError, RouteMetaMissingError, RouteOfflineMissingError } from './errors';
@@ -159,7 +160,17 @@ export type LoadRequirement<TData> = RouteContext extends TData
   ? unknown
   : { readonly load: RouteLoadFn<TData> };
 
-/** The input shape of `defineRoute` — exactly the contract's nine keys, nothing else. */
+/**
+ * How an `ssr` response may be cached, when the default is wrong for it. The default is decided
+ * by the guard — a gated page is `private, no-store`, an ungated one is offered to a CDN for 30s —
+ * and an ungated page can still be personal: a recipient landing addressed by a capability token
+ * in its path, a verification page that must never answer a superseded result. `'no-store'` is
+ * `private, no-store`; a hint is `@ultimat3/http`'s own `CacheHint`, minus `tags` (a purge
+ * targets `isr` documents, and a key nothing reads is a key that lies). `ssr` only — `modes.ts`.
+ */
+export type RouteCache = 'no-store' | Omit<CacheHint, 'tags'>;
+
+/** The input shape of `defineRoute` — exactly the contract's ten keys, nothing else. */
 export interface RouteDefinition<TData = RouteData> {
   readonly render: RenderMode;
   readonly revalidate?: RevalidateConfig;
@@ -180,6 +191,7 @@ export interface RouteDefinition<TData = RouteData> {
   readonly load?: RouteLoadFn<TData>;
   readonly meta: RouteMetaFn<TData>;
   readonly policy?: RouteGuard;
+  readonly cache?: RouteCache;
 }
 
 /**
@@ -290,6 +302,7 @@ export function defineRoute<TData = RouteData>(
     ...(def.revalidate ? { revalidate: def.revalidate } : {}),
     ...(def.prerender ? { prerender: def.prerender } : {}),
     ...(def.policy ? { policy: def.policy } : {}),
+    ...(def.cache === undefined ? {} : { cache: def.cache }),
   };
 
   assertModeShape(config);