npm - @ultimat3/render - Versions diffs - 19.3.1 → 19.3.3 - Mend

@ultimat3/render 19.3.1 → 19.3.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/CLAUDE.md CHANGED Viewed

@@ -37,6 +37,7 @@ for the mirror-image reason, keeping `render → pwa` refused. Never `cli` (upwa
 | `load` | optional, and the ONE server-side data seam. Resolved once per render by `routeDataFor()` and handed to **both** `meta` and the page component. Two resolutions is a `<title>` describing content the body does not contain. Absent `load`, the context IS the data (`{ params, url }`), which is what `meta` received before the key existed — so no consumer branches on whether a route declared one. |
 | `load` is required when the context cannot supply the data | `LoadRequirement<TData>` in `defineRoute`'s parameter — `unknown` when `RouteContext` satisfies `TData`, a required `load` when it does not. That is what makes the no-`load` fallback true rather than asserted: it was `ctx as unknown as TData`, so a `meta` reading `data.post` off a route that loads nothing type-checked and rendered `undefined` in a `<title>`. `RouteContext` is a type ALIAS for the same reason — only an alias carries the implicit index signature that makes it a `RouteData`; as an `interface` the compiler cannot see it and the cast comes back. |
 | A loader's own error | rethrown only when `isUltimateError` says so — core's brand, never a `code` property. Every `ENOENT` is an `Error` with a string `code`, and the duck-type that preceded this let all of them out of `routeDataFor` unwrapped: no `X_ROUTE_LOAD_FAILED`, no fix line, no route named. A tier-0 error (`@ultimat3/schema` cannot import core) is branded, not a subclass — never narrow this to `instanceof UltimateError`. |
+| A loader's own STATUS | `withStatus(status, data)` in `route-status.ts` — the ONE way a page answers 404 (or 410, or 503) while still rendering its own component inside the app's shell. Measured in ai-maxxing 2026-09-07: the only route to a status was a throw, which is the framework's error page OUTSIDE the shell, so `/fleet/nope` rendered the right page and answered 200. The status rides on the data by IDENTITY, in a `WeakMap` — the same object comes back, so `load`'s type, `routeDataFor`'s signature and every consumer that never asks are untouched, and a frozen or class-instance result is never written into. Never a `RouteContext` method: every builder of a context (`x dev`, the prerenderer, the SEO scan, both scaffold templates) would have to supply it, and an optional method is a second way. `routeStatusOf(data)` is the reader, TOTAL, 200 when nothing asked. A 3xx is `X_ROUTE_STATUS_INVALID` — a redirect is a `Location` and no body — and the range is `finiteStatus`'s. A 4xx/5xx is `robots.index = false` BY CONSTRUCTION in `defineRoute`'s `meta` wrapper, the one function every `<head>` renderer calls; a 200 hands the author's `meta` object back by reference. The response status itself is minted by `@ultimat3/cli`'s `dev-render.ts` (`resultFor`), which reads `routeStatusOf(data)` once and hands it to the mode — this package owns the seam, never the `Response`. |
 | Type claims | `type-pins.tsx`, never a `.test.ts` — `tsconfig.json` excludes tests, so `tsc` never reads one. `.tsx` since 1.2.0: the island-as-JSX claim is only decidable by writing the JSX an author writes, checked against the same `solid-js` `JSX.Element` a page is. |
 | Descriptor `meta` / `load` | always `(x) => Promise<…>`. Authors may declare either sync; consumers never branch. |
 | Descriptor `budget` | always an object, `{}` when undeclared. Its *fields* stay optional — `budget.js === undefined` is the site/ hydration failure. |
@@ -80,7 +81,7 @@ for the mirror-image reason, keeping `render → pwa` refused. Never `cli` (upwa
 | A bust that lands MID-render | fenced with `@ultimat3/cache`'s `sampleFence({ key, tags })`, taken before `render()` and asked before `store.set` — the same mechanism `CacheStack`'s read-through fill uses, never a second one grown here. `regenerate` rendered and then wrote `{ stale: false }` unconditionally, so a `markStale` arriving in between was ERASED by HTML built from pre-write rows; for a tag-only route `isFresh` is then true forever and the process serves it for the rest of its life. `registerPath` runs BEFORE the render for the other half: `revalidateByTags` reads the graph, so a bust could not see a cold path whose first render was still in flight. |
 | Marking a page stale | `IsrStore.markStale(path)`, in place — never `set({ ...entry, stale: true })`. `set` means "this page was just generated" and the default store orders eviction by exactly that, so the read-modify-write made the STALEST page the newest: a tag bust protected the pages that most needed regenerating and evicted the freshest one instead. **Breaking**: `markStale` is a required member of `IsrStore`. |
 | ISR store bound | `memoryIsrStore()` caps at `DEFAULT_ISR_MAX_ENTRIES` (1,000), least recently generated first — a route table supports `:params` and `*`, so `/blog/:slug` retains one full HTML string per slug ever requested, 404-shaped ones included. |
-| A `RenderResult.status` | `finiteStatus(subject, status)` in `finite-status.ts`, at both sites that take one from a caller (`renderSsr`'s `options.status`, `streamResult`'s third argument) — 200–599, whole. It reaches `new Response(body, { status })`, which answers a bare `RangeError` for anything else: `NaN` arrives there as `The status provided (-9223372036854775808)`, no code, no fix, and the render fails two frames above the route that set it. The screen is NARROWER than the boundary on purpose — `new Response` also takes `101`, and no rendered document is a protocol switch. The name carries `finite` because `bun run finite-bounds` recognises a repair by the shape of the CALL; spelled `renderStatus` it read as no screen at all. |
+| A `RenderResult.status` | `finiteStatus(subject, status)` in `finite-status.ts`, at every site that takes one from a caller (`renderSsr`'s `options.status`, `streamResult`'s third argument, `withStatus`'s first, and an `IsrRenderFn` answering `{ html, status }` at generation — `isRenderStatus`, the same range as a predicate, is the TOTAL read of a stored `IsrEntry.status` on the request path, because a custom store may JSON-round-trip one and a throw there is a 500 for the page's whole TTL) — 200–599, whole. It reaches `new Response(body, { status })`, which answers a bare `RangeError` for anything else: `NaN` arrives there as `The status provided (-9223372036854775808)`, no code, no fix, and the render fails two frames above the route that set it. The screen is NARROWER than the boundary on purpose — `new Response` also takes `101`, and no rendered document is a protocol switch. The name carries `finite` because `bun run finite-bounds` recognises a repair by the shape of the CALL; spelled `renderStatus` it read as no screen at all. |
 | `IsrEntry.ttlMs` off a store | normalised by `entryTtlMs`, TOTAL, never a throw — a ttl that is not a POSITIVE FINITE number of ms is the tag-only `null` `parseTtlMs` would have answered. `IsrStore` is a driver seam, and one backed by Redis round-trips the entry through JSON where a `ttlMs` nobody wrote reads back as `undefined`, so `entry.ttlMs === null` is false. Two failures, neither raising: `now - generatedAt < NaN` is false so the page is NEVER fresh and every request regenerates it, and the CDN is handed `s-maxage=NaN` — a directive a conforming cache IGNORES, dropping the page to heuristic caching. Read on the request path, so a refusal would turn a bad stored entry into a 500; the `isr.entry_ttl_invalid` warning is what keeps it from being silent. |
 | Route path from file | ONE reader of the surface segment: `locateSurface()` answers which surface AND where it starts. `registry.ts` sliced at `indexOf('app/')` instead, which matched inside `myapp/`, so every route under `apps/myapp/app/` served at `/app/…`. Never re-derive the offset from the surface NAME. |
 | An undecodable path segment | not a match, never a throw — `decodeSegment` in `registry.ts` is the one reader. `decodeURIComponent('%zz')` is a bare `URIError`, so a typo in a path segment was a 500 where `@ultimat3/http`'s router already answers "this branch does not match". A literal route matching the same text still wins. `router-client.ts` was the second reader and went with `createRouter`. |
@@ -102,6 +103,7 @@ for the mirror-image reason, keeping `render → pwa` refused. Never `cli` (upwa
 | CSS order | `stylesFor` sorts **globals before modules** (`isGlobalStylesheet`), never plain insertion order — the reset styles bare elements at the lowest specificity there is, so whichever page loaded first must not decide who wins a tie. `shared/` is carried by both graphs, like a package sheet: it is where an app's own global layer lives, and filtering it out is what made every deployed app render token-less. |
 | The global layer | this package may not import `@ultimat3/ui` (tier 4, the same tier — sideways, not upward: `ui` moved 5 → 4 in 2026-08 and `render → ui` stays forbidden because a same-tier edge has to be declared in `scripts/lib/tiers.ts`, and this one deliberately is not — the static bundle graph may not reach the design system, axiom 6), so the app's source graph carries it: one `shared/global.scss` that `@use`s `@ultimat3/ui/global.scss`, side-effect-imported by `shared/global.ts`. One file, because each stylesheet is its own Sass compilation — a token file `@use`d per module duplicates its `:root` block per module. `x verify` fails with `X_STYLES_GLOBAL_MISSING` when a surface's document defines none. |
 | Colours | tokens and `data-theme` only. No hex in `head.ts` or any emitted script. |
+| An island's `mount` | may return `() => void`, its disposer — `return render(…)`. The runtime resolves `el.__x` with it and never calls it; `@ultimat3/testing`'s `mountIsland` does, on dispose. |
 | `<head>` binding | `head.ts` stays injection-only (testable with no catalog); `head-seo.ts` is the ONE binding of `HeadRenderers` to `@ultimat3/seo`. A caller writing its own converter is the drift this file prevents. |
 Cross-package: `@ultimat3/pwa` consumes route descriptors as **data**, never by import.

package/README.md CHANGED Viewed

@@ -55,6 +55,17 @@ already carries a better code and a better fix than any wrapper could. Membershi
 brand, not a `code` property: an `ENOENT` is an `Error` with a string `code` too, and it gets
 wrapped like any other loader failure.
+A loader that wants the page to answer a **status** — a row the URL names and the table lacks —
+returns its data through `withStatus(404, data)`. The same object comes back, so nothing about
+`load`'s type, `meta`'s `data` or the page's props changes; every render mode reads the status off
+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
+loader said — a file has no status — and the build's measurer, which renders with `params: {}`,
+never fails on a loader answering 404.
 ## `offline` and `meta` are required by the type
 Not by a lint rule, not by a doc — by `RouteDefinition`. Axiom 3 lives in the type system:
@@ -429,6 +440,7 @@ side effect. Anything that loads an app's source — `x dev`, `x build`, `server
 | Export | Owns |
 |---|---|
 | `defineRoute` | the `route` primitive |
+| `withStatus`, `routeStatusOf` | the status a loader answers, carried on its data; 200 when nothing asked |
 | `island`, `createIslandCollector` | one interactive component on a static page |
 | `MODE_SPECS`, `assertModeShape`, `assertModeInvariants` | the mode invariant table |
 | `registerRoute`, `describeRoutes`, `routeFor`, `routePathFromFile` | the route table |

package/package.json CHANGED Viewed

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

package/src/css-modules.ts CHANGED Viewed

@@ -115,15 +115,47 @@ const TOKEN_FIX =
   "@ultimat3/ui/tokens exports functions and mixins — space(4), radius(md), role('surface-raised'), " +
   'text(sm) — and no $variables';
+/**
+ * A leading byte-order mark or `@charset` rule: the encoding claim Sass writes at the head of any
+ * output holding a non-ASCII character. Anchored to the START — a `@charset` anywhere else is
+ * already invalid CSS and not this function's to repair.
+ */
+const CHARSET_HEAD = /^\uFEFF?(?:@charset\s+"[^"]*"\s*;\s*)?/u;
+/**
+ * Drop the encoding claim from the head of one compiled sheet. Sass emits it for the FILE it
+ * believes it is writing, and it is right about a file: a stylesheet that begins with U+FEFF is
+ * decoded as UTF-8 by every browser. It is wrong about a fragment. The registry concatenates
+ * modules verbatim, so every module after the first that holds a `content: '·'` began with a BOM
+ * glued to its first selector — `\uFEFF.dashboard_256ee8e0{display:grid}` — which the browser reads
+ * as an unparseable selector and drops with its whole rule. Measured on ai-maxxing's home
+ * stylesheet, 2026-09-06: seven modules, seven first rules gone, the dashboard's grid container
+ * painting `display: block` with only the UA rule in Chrome's matched styles. The bundle is served
+ * `text/css; charset=utf-8` by the route, so no sheet needs to claim its encoding at all.
+ *
+ * Applied at BOTH seams: on the compile, where `charset: false` already asks Sass not to write it,
+ * and again where the sheets are joined, so a future Sass that ignores the option — or a sheet
+ * that reached the registry by another road — still cannot put a BOM mid-file.
+ */
+export function stripCharset(css: string): string {
+  return css.replace(CHARSET_HEAD, '');
+}
 export function compileStylesheet(file: string, source: string): CompiledStylesheet {
   let css: string;
   try {
-    css = sass.compileString(source, {
-      url: pathToFileURL(file),
-      loadPaths: [dirname(file)],
-      importers: [packageImporter(dirname(file))],
-      style: 'compressed',
-    }).css;
+    css = stripCharset(
+      sass.compileString(source, {
+        url: pathToFileURL(file),
+        loadPaths: [dirname(file)],
+        importers: [packageImporter(dirname(file))],
+        style: 'compressed',
+        // No `@charset`, no BOM — see `stripCharset`. Dart Sass writes one for any compressed
+        // output holding a non-ASCII character, and re-emits an escaped `\\00b7` as the literal
+        // character, so escaping in the app cannot avoid it.
+        charset: false,
+      }).css,
+    );
   } catch (error) {
     // `renderThrowable`, never `.message`/`String()`: an importer, a plugin or a future Sass
     // release can throw a value whose own read raises, and this frame is what turns a failed

package/src/errors.ts CHANGED Viewed

@@ -14,6 +14,7 @@ export const RENDER_ERROR_CODES = [
   'X_ROUTE_FILE_INVALID',
   'X_ROUTE_LOAD_INVALID',
   'X_ROUTE_LOAD_FAILED',
+  'X_ROUTE_STATUS_INVALID',
   'X_SURFACE_BOUNDARY',
   'X_BUDGET_EXCEEDED',
   'X_PRERENDER_FAILED',
@@ -37,6 +38,7 @@ export const RENDER_ERROR_TITLES: Readonly<Record<RenderErrorCode, string>> = {
   X_ROUTE_FILE_INVALID: 'a route file is not named for its surface',
   X_ROUTE_LOAD_INVALID: 'a route declared a load that is not a function',
   X_ROUTE_LOAD_FAILED: "a route's load threw while resolving its data",
+  X_ROUTE_STATUS_INVALID: 'a route answered a status a rendered page cannot carry',
   X_SURFACE_BOUNDARY: 'a surface imported across the hard boundary',
   X_BUDGET_EXCEEDED: 'a route blew its JS or LCP budget',
   X_PRERENDER_FAILED: 'a prerendered path threw during build',
@@ -254,3 +256,20 @@ export class RouteLoadFailedError extends UltimateError {
     });
   }
 }
+/**
+ * A loader answered a status through `withStatus` that no rendered document can carry: a 3xx. A
+ * redirect is a `Location` and no body, and this seam only ever produces a body — so the answer
+ * is refused where it was written, with the redirect the author meant named as the fix. The
+ * out-of-range half (`NaN`, `199`, `600`) is `finiteStatus`'s, the same screen every mode uses.
+ */
+export class RouteStatusInvalidError extends UltimateError {
+  static readonly code = 'X_ROUTE_STATUS_INVALID' as const;
+  constructor(cause: string, fix: string) {
+    super({
+      code: RouteStatusInvalidError.code,
+      cause,
+      fix,
+    });
+  }
+}

package/src/finite-status.ts CHANGED Viewed

@@ -14,6 +14,15 @@ import { assert, finiteCount } from '@ultimat3/core';
 const MIN_RENDER_STATUS = 200;
 const MAX_RENDER_STATUS = 599;
+/**
+ * The one range, as a predicate, for the request-path reader that must stay TOTAL: an `IsrEntry`
+ * a custom store round-tripped through JSON is read on every hit, and a throw there turns one bad
+ * stored number into a 500 for the page's whole TTL. `finiteStatus` below is the throwing form
+ * and reads the same two bounds, so the two cannot disagree about what a rendered status is.
+ */
+export const isRenderStatus = (status: number): boolean =>
+  Number.isSafeInteger(status) && status >= MIN_RENDER_STATUS && status <= MAX_RENDER_STATUS;
 /**
  * `NaN` is the value that gets here: `??` guards NULLISH, so a status read from a config, a JSON
  * body or `Number(process.env.X)` walks past its default intact — and the boundary then reports it
@@ -22,7 +31,7 @@ const MAX_RENDER_STATUS = 599;
 export function finiteStatus(subject: string, status: number): number {
   finiteCount(subject, 'status', status, 0);
   assert(
-    status >= MIN_RENDER_STATUS && status <= MAX_RENDER_STATUS,
+    isRenderStatus(status),
     `${subject} status is ${String(status)}, which new Response() refuses with a RangeError instead of returning a document`,
     `pass a status between ${String(MIN_RENDER_STATUS)} and ${String(MAX_RENDER_STATUS)} to ${subject}, or omit it and take 200`,
   );

package/src/hydrate.ts CHANGED Viewed

@@ -117,6 +117,10 @@ export function requiredStrategies(
 // The rejection handler rethrows: swallowing it would resolve `el.__x`, and the interaction
 // runtime below would then flush its replay queue into an island that never mounted — the bug
 // `el.__x`-as-a-promise was introduced to fix, reintroduced one layer further out.
+//
+// `el.__x` resolves to whatever `mount()` returned. An island's `mount` may return `() => void`,
+// its disposer (Solid's `render` answers one); the runtime keeps it there and
+// `@ultimat3/testing`'s `mountIsland` calls it on dispose. Nothing here ever calls it.
 const RUNTIME_PRELUDE = `
 function boot(el){var e=el.getAttribute('data-x-entry');
 if(!e)return Promise.resolve();if(el.__x)return el.__x;

package/src/index.ts CHANGED Viewed

@@ -33,6 +33,7 @@ export {
   RouteMetaMissingError,
   RouteModeInvalidError,
   RouteOfflineMissingError,
+  RouteStatusInvalidError,
   SurfaceBoundaryError,
 } from './errors';
 export type {
@@ -129,6 +130,7 @@ export { DEFAULT_ISLAND_HYDRATE, defineRoute, isRouteConfig, tagKeys } from './r
 export type { RouteComponent } from './route-component';
 export { pageComponentOf } from './route-component';
 export { metaContextFor, routeDataFor } from './route-data';
+export { DEFAULT_ROUTE_STATUS, isErrorStatus, routeStatusOf, withStatus } from './route-status';
 export type {
   BoundaryRule,
   BoundaryViolation,

package/src/module-loader.ts CHANGED Viewed

@@ -5,7 +5,7 @@
  */
 import { renderThrowable } from '@ultimat3/core';
-import { compileStylesheet, isGlobalStylesheet } from './css-modules';
+import { compileStylesheet, isGlobalStylesheet, stripCharset } from './css-modules';
 import { PrerenderFailedError } from './errors';
 import type { Surface } from './surfaces';
 import { surfaceOf } from './surfaces';
@@ -125,8 +125,10 @@ export function stylesFor(surface: Surface | null): string {
   const carried = [...stylesheets.values()].filter(
     (sheet) => sheet.surface === null || sheet.surface === 'shared' || sheet.surface === surface,
   );
+  // `stripCharset` on every sheet, not only the first: a `@charset` or a BOM is legal at byte 0 of
+  // a FILE and nowhere else, and this join is what turns seven files into one.
   return [...carried.filter((sheet) => sheet.global), ...carried.filter((sheet) => !sheet.global)]
-    .map((sheet) => sheet.css)
+    .map((sheet) => stripCharset(sheet.css))
     .join('');
 }
@@ -169,6 +171,9 @@ let installed = false;
  * placement that covers `x dev`, `x build`, the production `server.ts` and `bun test` without each
  * of them remembering to. A plugin only affects modules loaded AFTER it, and every route module is.
  */
+/** `/a/page.tsx?x-reload=3` → `/a/page.tsx`: the file on disk, which is what the hook reads. */
+const withoutQuery = (path: string): string => path.replace(/\?[^/]*$/, '');
 export function installRenderLoader(): void {
   if (installed) return;
   installed = true;
@@ -176,8 +181,13 @@ export function installRenderLoader(): void {
   Bun.plugin({
     name: 'ultimate-render',
     setup(build): void {
-      build.onLoad({ filter: /\.tsx$/ }, async ({ path }) => ({
-        contents: transformTsx(await Bun.file(path).text()),
+      // The query is admitted and then stripped. `x dev` re-imports an edited route module as
+      // `<path>?x-reload=<hash>` — the only cache key Bun honours — and Bun hands this hook the
+      // specifier QUERY INCLUDED. Anchored on `.tsx$` the filter let that import fall through to
+      // Bun's own loader, which compiles JSX to `React.createElement`: every reloaded page then
+      // died on its first render with `__xh is not defined`.
+      build.onLoad({ filter: /\.tsx(?:\?[^/]*)?$/ }, async ({ path }) => ({
+        contents: transformTsx(await Bun.file(withoutQuery(path)).text()),
         loader: 'js',
       }));

package/src/render-isr.ts CHANGED Viewed

@@ -17,6 +17,7 @@ import {
 } from '@ultimat3/cache';
 import { finiteCount, logger, renderThrowable } from '@ultimat3/core';
 import { parseTtlMs } from './duration';
+import { finiteStatus, isRenderStatus } from './finite-status';
 import type { RouteDescriptor } from './registry';
 import { describeRoutes } from './registry';
 import { contentHash, staticHeaders } from './render-static';
@@ -37,6 +38,12 @@ export interface IsrEntry {
   readonly ttlMs: number | null;
   /** Set by a tag invalidation; independent of the TTL clock. */
   readonly stale: boolean;
+  /**
+   * What the page answers, 200–599. Optional because an entry can come back from an app's own
+   * store, written before this field existed or JSON-round-tripped without it; absent reads as
+   * 200, the only status an entry ever had until `withStatus`.
+   */
+  readonly status?: number;
 }
 export interface IsrStore {
@@ -150,7 +157,22 @@ function routePathOf(key: string): string {
   return query === -1 ? key : key.slice(0, query);
 }
-export type IsrRenderFn = (path: string) => string | Promise<string>;
+/**
+ * A render that also answers a status — what a loader's `withStatus(404, …)` becomes once the
+ * document is built. A bare string is the 200 every render before this one was: the union is
+ * additive, and a render function that never learned the object shape keeps compiling.
+ */
+export interface IsrRendered {
+  readonly html: string;
+  readonly status: number;
+}
+export type IsrRenderFn = (path: string) => string | IsrRendered | Promise<string | IsrRendered>;
+/** One shape for the generator, so nothing below branches on what the render handed back. */
+function renderedOf(rendered: string | IsrRendered): IsrRendered {
+  return typeof rendered === 'string' ? { html: rendered, status: 200 } : rendered;
+}
 export interface IsrServeResult {
   readonly state: IsrState;
@@ -266,7 +288,7 @@ export function createIsrController(options: IsrControllerOptions = {}): IsrCont
         key: path,
         tags: (descriptor?.revalidateTags ?? []).map(parseWireTag),
       });
-      const html = await render(path);
+      const { html, status } = renderedOf(await render(path));
       const entry: IsrEntry = {
         path,
         html,
@@ -274,6 +296,9 @@ export function createIsrController(options: IsrControllerOptions = {}): IsrCont
         generatedAt: now(),
         ttlMs: parseTtlMs(descriptor?.revalidateTtl),
         stale: false,
+        // Screened at generation, the one place a status enters the store: a `NaN` written here
+        // would be served for the whole TTL as a `RangeError` on every hit.
+        status: finiteStatus('IsrRenderFn', status),
       };
       // Refused, never published stale-flagged: the next request re-renders from rows that now
       // include the write, where a stored-but-stale entry would serve this pre-write body once
@@ -432,6 +457,20 @@ function cacheControl(ttlMs: number | null): string {
   return `public, max-age=0, s-maxage=${sMaxAge}, stale-while-revalidate=86400`;
 }
+/**
+ * `entryTtlMs`'s reason, one field over: a store may hand back an entry with no `status`, or one
+ * that JSON turned into something else, on the request path. Absent is 200 — the only value any
+ * entry carried before the field existed — and anything the range refuses is 200 with a warning,
+ * because a stored number must not 500 the page for its whole TTL.
+ */
+function entryStatus(entry: IsrEntry): number {
+  const status = entry.status;
+  if (status === undefined) return 200;
+  if (isRenderStatus(status)) return status;
+  logger.warn('isr.entry_status_invalid', { path: entry.path, status: String(status) });
+  return 200;
+}
 function toResult(entry: IsrEntry, buildId: string, servedStale = false): RenderResult {
   const headers: Record<string, string> = {
     ...staticHeaders(entry.hash, buildId),
@@ -443,5 +482,5 @@ function toResult(entry: IsrEntry, buildId: string, servedStale = false): Render
     vary: 'accept-language',
   };
   if (servedStale) headers['x-ultimate-isr'] = 'stale';
-  return { status: 200, headers, body: entry.html };
+  return { status: entryStatus(entry), headers, body: entry.html };
 }

package/src/route-status.ts ADDED Viewed

@@ -0,0 +1,72 @@
+// The one way a loader answers a response STATUS while still rendering the route's own page.
+//
+// Measured in ai-maxxing, 2026-09-07: `/fleet/nope` — a host id the fleet does not have — rendered
+// the app's own "Not found" page inside its shell, the right page, and answered **200**. The only
+// route to a 404 was throwing, and a throw renders the framework's error page OUTSIDE the shell.
+// So an app that did the right thing for its visitor could not do the right thing for a crawler,
+// a CDN or a monitor, and one that did the right thing for those lost its shell.
+//
+// The status rides ON the data, by identity: `withStatus(404, data)` hands the same object back,
+// so `load`'s return type is untouched, `routeDataFor` still hands ONE object to `meta` and the
+// page, and every consumer that never asks reads 200. A `WeakMap` and not a symbol property — the
+// data may be frozen, may be a class instance, and is the author's; nothing here writes into it.
+// A `RouteContext` method (`ctx.notFound()`) was the alternative and was refused: every builder of
+// a context — `x dev`, the prerenderer, the SEO scan, both scaffold templates — would have had to
+// learn to supply it, and an optional method is a second way.
+import { RouteStatusInvalidError } from './errors';
+import { finiteStatus } from './finite-status';
+/** What every render answers when the loader said nothing, and what a no-`load` route answers. */
+export const DEFAULT_ROUTE_STATUS = 200;
+const STATUSES = new WeakMap<object, number>();
+/**
+ * What `withStatus` can mark, read back off `unknown`: exactly TypeScript's `object` — a non-null
+ * object OR a function. Both are `WeakMap` keys and both satisfy `withStatus`'s constraint, so a
+ * loader answering `withStatus(404, () => …)` — data that is a function, which `load`'s type
+ * allows — must read back as 404 and not as the default. The two sides of the seam share this
+ * one predicate so they cannot disagree about what carries a status.
+ */
+const canCarryStatus = (data: unknown): data is object =>
+  (typeof data === 'object' && data !== null) || typeof data === 'function';
+const isRedirect = (status: number): boolean => status >= 300 && status < 400;
+/**
+ * Answer `status` for this render, and render the page with `data` all the same.
+ *
+ * Any 2xx, 4xx or 5xx. A 3xx is refused by name: a redirect is a `Location` and no body, which is
+ * `@ultimat3/http`'s `redirect()` and never a page. Out of range is `finiteStatus`'s refusal, the
+ * same screen `renderSsr` and `streamResult` apply — `NaN` reaching `new Response` is a bare
+ * `RangeError` two frames above the loader that set it.
+ *
+ * A 4xx or 5xx is `robots: noindex` BY CONSTRUCTION — `defineRoute`'s `meta` wrapper applies it —
+ * so a page that does not exist is never indexed however its `meta` was written.
+ */
+export function withStatus<TData extends object>(status: number, data: TData): TData {
+  const screened = finiteStatus('withStatus', status);
+  if (isRedirect(screened)) {
+    throw new RouteStatusInvalidError(
+      `withStatus(${String(screened)}, …) asks a page to be a redirect, and a rendered document has no Location to send`,
+      "answer 2xx, 4xx or 5xx from load; a redirect is `redirect(location)` from '@ultimat3/http', thrown or returned by the handler",
+    );
+  }
+  STATUSES.set(data, screened);
+  return data;
+}
+/**
+ * The status a render of `data` answers: what `withStatus` recorded, else 200. TOTAL, and asked
+ * of `unknown` on purpose — the callers are the render modes, and the data is whatever the app's
+ * loader returned, an object or not.
+ */
+export function routeStatusOf(data: unknown): number {
+  if (!canCarryStatus(data)) return DEFAULT_ROUTE_STATUS;
+  const status = STATUSES.get(data);
+  return status === undefined ? DEFAULT_ROUTE_STATUS : status;
+}
+/** A 4xx or 5xx: a document a crawler must forget, whatever its `meta` said. */
+export const isErrorStatus = (status: number): boolean => status >= 400;

package/src/route.ts CHANGED Viewed

@@ -22,6 +22,7 @@ import { RouteLoadInvalidError, RouteMetaMissingError, RouteOfflineMissingError
 import type { IslandSpec } from './island';
 import { drainDeclaredIslands } from './island';
 import { assertModeShape } from './modes';
+import { isErrorStatus, routeStatusOf } from './route-status';
 /**
  * What a page that declares an island hydrates as when it says nothing. The most conservative of
@@ -274,7 +275,12 @@ export function defineRoute<TData = RouteData>(
     // 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 (metaCtx: RouteMetaContext<TData>) => declaredMeta(metaCtx),
+    // And the one place a 4xx/5xx becomes `noindex`: every consumer that renders a `<head>` —
+    // `x dev`, the prerenderer, the SEO scan — calls THIS function, so a page whose loader said
+    // 404 is never indexed however its `meta` was written. A 200 hands the author's object back
+    // untouched, so an app that never sets a status is byte-identical.
+    meta: async (metaCtx: RouteMetaContext<TData>) =>
+      noindexOnError(await declaredMeta(metaCtx), routeStatusOf(metaCtx.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 ?? {},
@@ -290,6 +296,12 @@ export function defineRoute<TData = RouteData>(
   return Object.freeze(config);
 }
+/** Only `index` is decided here; `follow` and the rest stay the author's. */
+function noindexOnError(meta: RouteMeta, status: number): RouteMeta {
+  if (!isErrorStatus(status)) return meta;
+  return { ...meta, robots: { ...meta.robots, index: false } };
+}
 export function isRouteConfig(value: unknown): value is RouteConfig {
   return typeof value === 'object' && value !== null && 'kind' in value && value.kind === 'route';
 }

package/src/server.ts CHANGED Viewed

@@ -16,7 +16,13 @@ installRenderLoader();
 // ---- scss → css, and the scoped class map every `import styles from` receives -------------------
 export type { CompiledStylesheet } from './css-modules';
-export { compileStylesheet, isCssModule, isGlobalStylesheet, scopeClasses } from './css-modules';
+export {
+  compileStylesheet,
+  isCssModule,
+  isGlobalStylesheet,
+  scopeClasses,
+  stripCharset,
+} from './css-modules';
 // ---- the two Bun loaders: `.tsx` → the server JSX factory, `.scss` → css + a class map ----------
 export type { Stylesheet } from './module-loader';
 export {
@@ -35,6 +41,7 @@ export type {
   IsrController,
   IsrControllerOptions,
   IsrEntry,
+  IsrRendered,
   IsrRenderFn,
   IsrServeResult,
   IsrState,