@ultimat3/render 27.8.0 → 27.9.0

package/CLAUDE.md

@@ -77,7 +77,7 @@ axiom 6). Never `cli` (upward).
 | "Is this a TTL?" has one reader | `parseTtlMs` in `duration.ts`, below `modes.ts` and `render-isr.ts`. |
 | A build-time frame reads a throw with `renderThrowable` | `render-html.ts`, `render-static.ts`, `css-modules.ts`, `module-loader.ts`, `route-data.ts`. `bun run error-render` cannot see a value laundered through a local helper. |
 | `X_ROUTE_LOAD_FAILED` computes its pathname BEFORE the try | `pathnameOf` never throws on a relative `ctx.url`. |
-| The ISR key | `isrKey(url, locale)` — pathname, the negotiated locale in the reserved `__x_locale` parameter, then the sorted query. The locale is REQUIRED. The time zone is deliberately not a dimension. `toResult` emits `vary: accept-language`, and `surrogate-key`/`cache-tag` from `@ultimat3/cache`'s `surrogateKeys()` over the route's `revalidateTags` — kept only while the response stays shared: http's `applyCacheHeaders` strips both on a rewrite to `private`/`no-store`. `registry.ts`'s `assertPurgeableTags` screens the tags at registration (`X_ROUTE_MODE_INVALID`); the rest of the shared key is `@ultimat3/http`'s `cache-headers` stage. The one shipped emitter of purge keys; file and mounted routes are both screened, so `toResult` never refuses on the request path |
+| The ISR key | `isrKey(url, locale)` — the path in http's `canonicalPath` spelling (no base path), the locale in the reserved `__x_locale` parameter, the sorted query. A key no route owns is never stored. The locale is REQUIRED. The time zone is deliberately not a dimension. `toResult` emits `vary: accept-language`, and `surrogate-key`/`cache-tag` from `@ultimat3/cache`'s `surrogateKeys()` over the route's `revalidateTags` — kept only while the response stays shared: http's `applyCacheHeaders` strips both on a rewrite to `private`/`no-store`. `registry.ts`'s `assertPurgeableTags` screens the tags at registration (`X_ROUTE_MODE_INVALID`); the rest of the shared key is `@ultimat3/http`'s `cache-headers` stage. File and mounted routes are both screened |
 | A bust that lands MID-render | fenced with `@ultimat3/cache`'s `sampleFence({ key, tags })`, taken before `render()` and asked before `store.set`. `registerPath` runs BEFORE the render. |
 | ISR regeneration | `@ultimat3/core`'s `singleFlight`, `deadlineMs` = `regenerateDeadlineMs` (`DEFAULT_ISR_REGENERATE_DEADLINE_MS`, 30 s; `finiteCount` ≥ 1, no opt-out), `schedule` injectable. Past it the PATH is free; the hung render runs on, and `latest` (by identity) drops its result once a newer run started. `render-isr-flight.test.ts`, on a hand-fired scheduler. |
 | Which route a stored ISR path is | exact path first, else the MOST SPECIFIC pattern: `route-pattern.ts`'s `compilePattern` (never a second compiler), sorted on `CompiledPattern.specificity`. Never table order: `describePages()` sorts `*` before `:`. |

package/README.md

@@ -26,6 +26,14 @@ export const config = defineRoute({
 export function Page(props: { data: Post }) { /* the SAME object meta was given */ }
 ```
 
+`prerender()` answers the pages to build: a bare string (a one-param route), a params object, or an
+entry — `{ params, lastmod?, locales? }` (`PrerenderEntry`) — mixed freely. The build reads `params`
+alone and renders every routed locale; `lastmod` (a `Date` or ISO 8601 with a zone) and `locales`
+are what the page says of itself for the sitemap: its `<lastmod>`, and the locales it is listed and
+cross-linked in. `enumeratePrerender()` answers params, `enumeratePrerenderEntries()` the entries.
+A key outside the three, a `lastmod` that is neither a string nor a `Date`, or `locales` that is
+not a list of names is `X_PRERENDER_FAILED`, naming the route file.
+
 ## `load` is the one server-side data seam
 
 Optional, and the only way a page gets data. It runs **once per render** and the result is handed
@@ -557,7 +565,7 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `checkSurfaceBoundary`, `assertSurfaceBoundary`, `surfaceOf` | the hard boundary |
 | `renderStatic`†, `enumeratePrerender`† | build-time render, content hashing |
 | `isrController`†, `invalidateAndRevalidate`† | SWR + single-flight + tag triggers |
-| `isrKey`†, `isrRequestUrl`†, `undeclaredQuery`† | the one derivation of an `isr` store key, and the request URL narrowed to `revalidate.query` |
+| `isrKey`†, `isrRequestUrl`†, `undeclaredQuery`†, `isrRouteFor`† | the one derivation of an `isr` store key — the path in `@ultimat3/http`'s `canonicalPath` spelling, so every spelling the router answers with a page is that page's one entry — the request URL narrowed to `revalidate.query`, and the route a key reads back as (a key no route owns is never stored) |
 | `noStore`, `routeNoStoreOf` | a loader's "do not keep this answer" — a mark on the data, like `withStatus`; read by `isr` |
 | `renderSsr`†, `streamResult`† | the per-request modes |
 | `renderToHtml`†, `renderComponent`†, `stylesFor`† | the server JSX writer and the surface's css |

package/package.json

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

package/src/index.ts

@@ -182,7 +182,9 @@ export {
 export type {
   InvalidateMode,
   LoadRequirement,
+  PrerenderEntry,
   PrerenderFn,
+  PrerenderItem,
   RenderResult,
   RevalidateConfig,
   RouteAlternate,

package/src/prerender-enumerate.ts

@@ -0,0 +1,108 @@
+// Single responsibility: what a route's `prerender()` answered, normalised — every page as its
+// params, plus what the page said about itself for a sitemap (`lastmod`, `locales`).
+
+import { renderCauseValue, renderThrowable } from '@ultimat3/core';
+import { PrerenderFailedError } from './errors';
+import type { RouteEntry } from './registry';
+import type { PrerenderEntry, RouteParams } from './route';
+
+const ENTRY_KEYS: readonly string[] = ['params', 'lastmod', 'locales'];
+
+const isRecord = (value: unknown): value is Readonly<Record<string, unknown>> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/**
+ * Is `item` the ENTRY form — `{ params: { … }, lastmod?, locales? }` — rather than a params object?
+ * Decided by `params` holding an object: a param VALUE is always a string, so `{ params: 'a' }` on a
+ * route whose own dynamic segment is `[params]` stays the plain params it has always been.
+ */
+const isEntry = (item: Readonly<Record<string, unknown>>): boolean => isRecord(item['params']);
+
+function entryOf(entry: RouteEntry, item: Readonly<Record<string, unknown>>): PrerenderEntry {
+  const refuse = (problem: string): never => {
+    throw new PrerenderFailedError(
+      `prerender() for ${entry.path} returned an entry ${problem}`,
+      `x build --target static --json   # after prerender in ${entry.file} returns { params, lastmod?: Date | ISO 8601 string, locales?: string[] }`,
+    );
+  };
+  const extra = Object.keys(item).find((key) => !ENTRY_KEYS.includes(key));
+  if (extra !== undefined) {
+    refuse(`with the key ${JSON.stringify(extra)}, which is not one of ${ENTRY_KEYS.join(', ')}`);
+  }
+  const { lastmod, locales } = item;
+  if (lastmod !== undefined && typeof lastmod !== 'string' && !(lastmod instanceof Date)) {
+    refuse(`whose lastmod is ${renderCauseValue(lastmod)}, neither a Date nor an ISO 8601 string`);
+  }
+  if (
+    locales !== undefined &&
+    !(Array.isArray(locales) && locales.every((locale) => typeof locale === 'string'))
+  ) {
+    refuse(`whose locales is ${renderCauseValue(locales)}, not a list of locale names`);
+  }
+  return {
+    params: item['params'] as RouteParams,
+    ...(lastmod === undefined ? {} : { lastmod: lastmod as string | Date }),
+    ...(locales === undefined ? {} : { locales: locales as readonly string[] }),
+  };
+}
+
+/**
+ * Every page `prerender()` enumerates, as an entry. A bare string fills the route's one dynamic
+ * param; a params object is an entry with nothing to add. `lastmod` is carried AS WRITTEN — whether
+ * it names an instant is the sitemap's question (`@ultimat3/seo`, `X_SITEMAP_ENTRY_INVALID`).
+ */
+export async function enumeratePrerenderEntries(
+  entry: RouteEntry,
+): Promise<readonly PrerenderEntry[]> {
+  const prerender = entry.config.prerender;
+  if (prerender === undefined) {
+    return entry.pattern.keys.length === 0 ? [{ params: {} }] : [];
+  }
+
+  let produced: unknown;
+  try {
+    produced = await prerender();
+  } catch (error) {
+    throw new PrerenderFailedError(
+      // `renderThrowable`, never `.message`/`String()`: `prerender` is app code and may throw a
+      // value whose read raises in turn — this frame is what makes the build failure a coded one.
+      `prerender() for ${entry.path} threw: ${renderThrowable(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: unknown): PrerenderEntry => {
+    if (typeof item === 'string') {
+      const only = keys[0];
+      if (keys.length !== 1 || only === undefined) {
+        throw new PrerenderFailedError(
+          `prerender() for ${entry.path} returned the bare string ${renderCauseValue(item)} ` +
+            `but the route has ${keys.length} dynamic params (${keys.join(', ')})`,
+          `return objects from prerender in ${entry.file}, e.g. { ${keys.join(': …, ')}: … }`,
+        );
+      }
+      return { params: { [only]: item } };
+    }
+    // A `null` reached `Object.hasOwn` in `static-path.ts` and left the build as a bare `TypeError`.
+    if (!isRecord(item)) {
+      throw new PrerenderFailedError(
+        `prerender() for ${entry.path} returned ${renderCauseValue(item)} as one of its items, which is neither a params object nor a string`,
+        `return an array of params objects (or strings, for a one-param route) from prerender in ${entry.file}`,
+      );
+    }
+    return isEntry(item) ? entryOf(entry, item) : { params: item as RouteParams };
+  });
+}
+
+/** The params of every page `prerender()` enumerates — what a build renders, one document each. */
+export async function enumeratePrerender(entry: RouteEntry): Promise<readonly RouteParams[]> {
+  return (await enumeratePrerenderEntries(entry)).map((page) => page.params);
+}

package/src/render-isr-key.ts

@@ -4,6 +4,7 @@
  * the controller, which only ever holds the key this file derived.
  */
 
+import { canonicalPath } from '@ultimat3/http';
 import { unlocalizedPath } from '@ultimat3/i18n';
 
 /**
@@ -57,6 +58,13 @@ export function undeclaredQuery(url: URL, query: readonly string[] | null): read
  * The ISR store key for one URL: pathname, the negotiated LOCALE, and the query, **params
  * sorted**. The URL is `isrRequestUrl`'s — already narrowed to the route's declared parameters.
  *
+ * The pathname is keyed in its ONE spelling — `@ultimat3/http`'s `canonicalPath`, built from the
+ * functions the router segments and decodes a request with, never a second normaliser. The router
+ * answers `/blog//a/`, `/blog/%61` and `/blog/a` with one page; keyed raw, each was an entry of
+ * its own (a 20-letter slug has a million percent-spellings, and the store holds 1,000), and one
+ * the route table could not read back (`/blog//a`) was stored with no ttl and no tags, which no
+ * bust reached: a withdrawn page stayed up at that spelling for the life of the process.
+ *
  * Exported because deriving it is the caller's job and there may only be ONE derivation — a
  * server that keyed on `url.pathname` while the store believed it held a whole URL is the shape
  * of #171. Sorting makes `?a=1&b=2` and `?b=2&a=1` one entry rather than two renders of one page.
@@ -72,7 +80,7 @@ export function isrKey(url: URL, locale: string): string {
   const params = new URLSearchParams(url.search);
   params.set(ISR_LOCALE_PARAM, locale);
   params.sort();
-  return `${url.pathname}?${params.toString()}`;
+  return `${canonicalPath(url.pathname)}?${params.toString()}`;
 }
 
 /**

package/src/render-isr.ts

@@ -108,6 +108,24 @@ export function isrController(options: IsrControllerOptions = {}): IsrController
 
   const descriptorFor = (key: string): RouteDescriptor | undefined => isrRouteFor(routes(), key);
 
+  /**
+   * A key NO route owns is rendered for the request that asked and never stored. Its ttl and tags
+   * are its route's, so stored it had neither: fresh for ever, on no tag edge, and found by no
+   * bust — the one page a purge could not take down. `@ultimat3/cli` keys every request on the
+   * path the router matched, so this is a caller that derived a key some other way. Told once.
+   */
+  let toldUnowned = false;
+  function tellUnowned(path: string): void {
+    if (toldUnowned) return;
+    toldUnowned = true;
+    logger.warn('isr.key.unowned', {
+      path,
+      cause:
+        'no route in the table matches this key, so it has no ttl and no tags to be revalidated by — it was rendered and not stored',
+      fix: 'isrKey(url, locale)   // key on the URL the router matched, base path removed; never on a hand-built string',
+    });
+  }
+
   /**
    * A rendered page joins the invalidation graph under its route's tags, so `/blog/a` and
    * `/blog/b` are separately addressable and a `tag.post` bust does not touch `/team`.
@@ -192,7 +210,8 @@ export function isrController(options: IsrControllerOptions = {}): IsrController
           status: finiteStatus('IsrRenderFn', rendered.status),
         };
         const current = latest.get(path) === run;
-        const unstorable = isServerError(rendered.status) || rendered.noStore === true;
+        const unstorable =
+          descriptor === undefined || isServerError(rendered.status) || rendered.noStore === true;
         // Kept only when nothing invalidated the page while it rendered — in this process (the
         // fence) or in any other (the store's) — and no newer run started. Refused, never
         // published stale-flagged: the next request re-renders from rows that include the write.
@@ -203,6 +222,8 @@ export function isrController(options: IsrControllerOptions = {}): IsrController
           // store holds stays (still stale, so the next request tries again); a miss has none, and
           // answers this 5xx to its own request only.
           logger.warn('isr.render.unstored', { path, status: String(rendered.status) });
+        } else if (descriptor === undefined) {
+          tellUnowned(path);
         } else if (rendered.noStore === true) {
           // The loader's answer is not a failure, so the copy held is no longer the page.
           if (current) store.delete(path);
@@ -331,7 +352,9 @@ export function isrController(options: IsrControllerOptions = {}): IsrController
           ageMs: Math.max(0, now() - entry.generatedAt),
         });
       let cached = store.get(path);
-      if (cached !== undefined && pastMaxStale(cached, policy)) {
+      // A copy under a key no route owns (a shared store an earlier release wrote) is not served:
+      // nothing could have invalidated it since.
+      if (cached !== undefined && (descriptor === undefined || pastMaxStale(cached, policy))) {
         store.delete(path);
         cached = undefined;
       }

package/src/render-static.ts

@@ -4,12 +4,16 @@
  * the precache revision in `sw.js`, and the asset filename suffix.
  */
 
-import { BUILD_ID_HEADER, renderCauseValue, renderThrowable, useContext } from '@ultimat3/core';
+import { BUILD_ID_HEADER, renderThrowable, useContext } from '@ultimat3/core';
 import { PrerenderFailedError, RouteModeInvalidError } from './errors';
+import { enumeratePrerender } from './prerender-enumerate';
 import type { RouteEntry } from './registry';
 import type { RenderResult, RouteParams } from './route';
 import { filePathOf, filledSegments, urlPathOf } from './static-path';
 
+// Re-exported where it has always been imported from; the enumeration is `prerender-enumerate.ts`'s.
+export { enumeratePrerender } from './prerender-enumerate';
+
 export interface StaticArtifact {
   readonly path: string;
   readonly params: RouteParams;
@@ -61,59 +65,6 @@ export function assertNoPerRequestState(file: string): void {
   }
 }
 
-/** 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(
-      // `renderThrowable`, never `.message`/`String()`: `prerender` is app code and may throw a
-      // value whose read raises in turn — this frame is what makes the build failure a coded one.
-      `prerender() for ${entry.path} threw: ${renderThrowable(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: unknown) => {
-    if (typeof item !== 'string') return paramsOf(entry, item);
-    const only = keys[0];
-    if (keys.length !== 1 || only === undefined) {
-      throw new PrerenderFailedError(
-        `prerender() for ${entry.path} returned the bare string ${renderCauseValue(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 };
-  });
-}
-
-/**
- * One `prerender()` item that is not a bare string: a params object, or a coded refusal. A `null`
- * reached `Object.hasOwn` in `static-path.ts` and left the build as a bare `TypeError`.
- */
-function paramsOf(entry: RouteEntry, item: unknown): RouteParams {
-  if (typeof item === 'object' && item !== null && !Array.isArray(item)) return item as RouteParams;
-  throw new PrerenderFailedError(
-    `prerender() for ${entry.path} returned ${renderCauseValue(item)} as one of its items, which is neither a params object nor a string`,
-    `return an array of params objects (or strings, for a one-param route) from prerender in ${entry.file}`,
-  );
-}
-
 export interface StaticBuildOptions {
   readonly buildId: string;
   /** Extension-less output files get `/index.html` appended. */

package/src/route.ts

@@ -186,10 +186,29 @@ export type RouteMetaAsyncFn<TData = RouteData> = (
   ctx: RouteMetaContext<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)[]>;
+/**
+ * One page `prerender()` answers, with what the page says about itself for the SITEMAP. The build
+ * reads `params` alone: every routed locale's document is still rendered.
+ */
+export interface PrerenderEntry {
+  readonly params: RouteParams;
+  /**
+   * When this page last changed — the sitemap's `<lastmod>` for it. A `Date`, or ISO 8601 with an
+   * explicit zone (`row.updatedAt`); a moment in the future is written as now.
+   */
+  readonly lastmod?: string | Date;
+  /**
+   * The locales this page is LISTED in: one sitemap `<url>` each, cross-linked with hreflang among
+   * themselves only. Omitted: every routed locale. Empty: built, and listed nowhere.
+   */
+  readonly locales?: readonly string[];
+}
+
+/** One item of a `prerender()` answer: a bare string, a params object, or an entry. */
+export type PrerenderItem = string | RouteParams | PrerenderEntry;
+
+/** Returns the pages to build at deploy time. Bare strings fill a single dynamic param. */
+export type PrerenderFn = () => readonly PrerenderItem[] | Promise<readonly PrerenderItem[]>;
 
 /**
  * The rule that makes the no-`load` fallback true: a route that loads nothing renders

package/src/server.ts

@@ -36,10 +36,10 @@ export {
   stylesheetsRevision,
   transformTsx,
 } from './module-loader';
+export { enumeratePrerenderEntries } from './prerender-enumerate';
 // ---- the render pipeline: one entry point per mode ----------------------------------------------
 export type { RenderHtmlOptions } from './render-html';
 export { ROOT_ELEMENT_ID, renderComponent, renderToHtml } from './render-html';
-
 export {
   DEFAULT_ISR_REGENERATE_DEADLINE_MS,
   invalidateAndRevalidate,
@@ -47,6 +47,7 @@ export {
 } from './render-isr';
 export { DEFAULT_ISR_FAILURE_COOLDOWN_MS } from './render-isr-cooldown';
 export { ISR_LOCALE_PARAM, isrKey, isrRequestUrl, undeclaredQuery } from './render-isr-key';
+export { isrRouteFor } from './render-isr-routes';
 export type {
   IsrEntry,
   IsrState,