A route is a URL + render mode + metadata + offline strategy. Render mode is a per-route property. SEO is enforced by the build, not described in a guide.

As of 2026-08. Stable API — semver from here (Upgrading).

export const config = defineRoute({
  render:     'isr',                  // static | isr | ssr | stream
  revalidate: { tags: [tag.post] },
  prerender:  () => db.posts.slugs(),
  offline:    'precache',             // precache | runtime | network-only
  hydrate:    'visible',              // idle | visible | interaction | never
  budget:     { js: '40kb' },
  meta:       ({ post }) => ({ title: post.title, description: post.excerpt,
                               og: { image: post.cover }, ld: ld.Article(post) }),
});

defineRoute({ render: 'ssr', …, post: 'unsubscribeOnboarding' }) (As of 22.6.0) mounts POST at the page's own path, answered by that action — its policy, idempotency and redirect — with the URL's query merged over the posted fields (the query wins a shared name: it is the URL the server minted). The RFC 8058 case: the mail client POSTs List-Unsubscribe=One-Click to /correos/baja?t=… and the action receives { t, 'List-Unsubscribe': 'One-Click' }; the page's GET stays the confirm page, and its form can post to itself with no JavaScript. Declare optional input keys for what the client posts. Not an export name, or on render: 'static': X_ROUTE_POST_INVALID at declaration; naming no registered action: the same code at boot.

Only on a surface listed in app.config.ts navigation.client (Client navigation); anywhere else X_ROUTE_NAVIGATION_INVALID at boot, and any value but these two at declaration.

route is the one primitive whose façade is a normalized descriptor rather than a set of projection methods, because a route declares no behaviour to project. It is read by the router, the prerenderer, the sitemap and the budget check — and is designed to be read by sw.js generation, which no build calls yet (#362). The descriptor's job is to hand all of them one shape so none of them branches. There is no .describe() on a route either — describePages() is the one route list.

The always-present budget does not weaken the site/ JS-budget check. budget is always an object, but its fields stay optional — so budget.js === undefined still means "this route declared no JS budget", and a site/ route that opts into any hydrate other than never without one is X_ROUTE_MODE_INVALID, exactly as before the normalization. Measuring the declared numbers against the built output is the separate concern in Budgets, below.

Validation runs at module evaluation. defineRoute checks the shape and the mode-local invariants immediately, so a bad route fails at build time rather than on the first request in production.

The split is about what is knowable, not about strictness: everything decidable from the config alone is decided at import; the rest needs the file's surface, which only the route table knows.

A served static page, As of 2026-09: a matching If-None-Match is a bodiless 304, and the container renders each page once per locale and answers from memory after — no load, no render — for a page with no dynamic segment, asked for with no query string, that answered 200. x dev renders per request. No other mode is kept this way. What is kept is bounded twice — 1,024 entries and 32 MiB of bodies (STATIC_MEMO_MAX_BYTES) — because the request origin is in the key when the app declares none; past either bound a page is rendered per request.

A mode outside a surface's allowed set is a build error, not a runtime fallback. Surfaces and their boundaries: Project layout.

spa was the fifth mode and was deleted in 6.0.0. It served <body><div id="x-root"></div></body> for the framework's whole history — 200, correct headers, blank page — because renderSpa preloaded a chunks array no build ever produced and never read the route's component. render: 'spa' is now X_ROUTE_MODE_INVALID at defineRoute time; the migration is one line, render: 'ssr', in Upgrading.

A render mode states the mode's intent; @ultimat3/http's cache-headers stage makes the final answer. As of 2026-08-23 that stage REVIEWS a cache-control the mode already wrote instead of standing down, which is what made the rule below reachable for a page at all.

As of 2026-09-24. An ungated ssr page is offered to a CDN for 30 seconds (public, max-age=0, s-maxage=30, stale-while-revalidate=300). A page can be public and still personal: a recipient landing addressed by a capability token in its path, or a verification page that must never answer with an old result. cache replaces that default:

export const config = defineRoute({
  render: 'ssr',
  offline: 'network-only',
  cache: 'no-store',                  // or a CacheHint: { mode: 'public', sMaxAgeSeconds: 5 }
  meta: ({ t }) => ({ title: t('verify.title'), description: t('verify.description') }),
});

An isr entry is keyed by the negotiated locale. The store key is isrKey(url, locale) — the path in its one spelling (below), the reserved __x_locale parameter, then the query the route declared (revalidate.query, below) with its params sorted. Without it, an app shipping two locales served visitor 2 the document rendered for visitor 1, for the whole TTL, and told the CDN to do the same. The time zone is deliberately not a dimension — a locale set is declared and bounded, a zone list is not — so a date on an isr page belongs in a zone the page itself names, or the page belongs in ssr.

An isr page is one entry however its URL is spelled. The router answers /blog//abc/, /blog/%61bc and /blog/abc with the same route and the same slug, so the store keys on the address it matched, never on the pathname as written: empty segments and the trailing slash dropped, each segment decoded and re-encoded one way (@ultimat3/http's canonicalPath, built from the functions the router itself segments and decodes with). As of 2026-10-11.

• load, meta and the page are handed that same address as url (base path included), so the document's canonical is /blog/abc whichever spelling arrived first. A static page is rendered at its address too, as the export writes it; ssr and stream keep the URL as the visitor wrote it.
• Nothing is redirected, and no status changes: a spelling the router answered with a 200 is still a 200, with the canonical page's cache-control, purge keys and canonical link. Redirect at the ingress if you want one URL in a browser's address bar.
• A key no route owns is never stored. An entry takes its ttl and its tags from its route, so stored without one it was fresh for ever and on no tag edge. isrController().serve() renders it for the request that asked, private, no-store, and logs isr.key.unowned once. The same holds for a request the router matched as one route while its address reads back as another (//en/x is the /[lang]/x route; /en/x is the /x route in English): answered, never stored.
• Releases through 27.8.0 keyed on the raw pathname (Known Gaps).

A locale-prefixed isr page is its route's page. The key keeps the prefix — /en/blog/a?__x_locale=en is the document rendered for that URL — and the route it belongs to is found on the path with the routed prefix removed (unlocalizedPath), as the router matches it. So /en/blog/a takes /blog/:slug's revalidate.ttl (s-maxage included), joins its revalidate.tags, and is regenerated in its own locale: a tag bust or the TTL expires every locale's copy of a page, stored 404s included. A page whose truth changes with the clock (publishedAt <= now) is written by nothing when the instant passes, so no tag is busted — it needs a ttl, and the ttl alone is enough in every locale. Releases through 27.6.1 matched no route for a prefixed page (Known Gaps): tag-only s-maxage=60, no tag edge, fresh for the life of the process.

An isr regeneration holds its page for at most 30 s (DEFAULT_ISR_REGENERATE_DEADLINE_MS; isrController({ regenerateDeadlineMs }), a whole number ≥ 1) As of 2026-10-02. A render that never settles used to pin its page for the life of the process: a missed page hung every later request, a stale one was served stale forever. Past the deadline the next request renders again; the hung render is not cancelled, and its late result is dropped if a newer one has started. A stored path takes its TTL and tags from the most specific route that matches it — segment by segment, static beats :param beats *catch-all, as the request router resolves it — so /docs/7 is /docs/:id's, never /docs/*path's. A zero-length ttl ('0s', 0) is no trigger at all: X_ROUTE_MODE_INVALID.

As of 2026-10-10. Three optional keys beside tags and ttl, each refused at defineRoute when the controller could not act on it (X_ROUTE_MODE_INVALID).

import { tag } from '@ultimat3/cache';
import { defineRoute } from '@ultimat3/render';

declare const posts: { page(n: number): Promise<{ readonly titles: readonly string[] }> };

export const config = defineRoute({
  render: 'isr',
  revalidate: {
    tags: [tag('post')],
    ttl: '10m',
    onInvalidate: 'purge', // 'stale' (default) | 'purge'
    maxStale: '1h',        // past ttl + 1h a copy is not an answer; 0 (purge's default) is never
    query: ['page'],       // the only query parameters in the key; [] for none
  },
  offline: 'runtime',
  load: ({ url }) => posts.page(Number(new URL(url).searchParams.get('page') ?? '1')),
  meta: ({ url }) => ({ title: 'Blog', description: 'Every post, newest first.', canonical: url }),
});

Declare query on every isr route. Omitted, the key carries whatever the visitor sent: /blog?x=1, /blog?x=2, … are each a render and a stored page (the store holds 1,000), which is a cost-amplification vector, and utm_* / fbclid / gclid split one page into many — each of which a withdrawal has to reach. x verify names every isr route without a declaration (the seo step's warnings), and the server logs isr.query.undeclared once per route the first time a visitor uses it. The default becomes [] in the next major.

Declare every parameter the page reads — [] only when it reads none. A page that reads ?currency= under query: [] is ONE stored document, the first visitor's, answered to every other currency. Two nets, both best-effort: x verify reads each isr route module for query.<name>, query['<name>'] and searchParams.get('<name>') and warns for a name the declaration omits (a read made through a helper in another file is not seen); and outside production, the query a page component receives warns once (isr.query.unkeyed-read) when the page reads a parameter the route did not declare. load and meta read the narrowed url, where an undeclared parameter is simply absent.

Nothing is redirected. /blog?utm_source=mail is answered with the /blog page: load and meta are given the narrowed URL, so canonical: url is /blog and a parameter outside the key cannot change the document stored under it. A declared parameter's values are still the visitor's — ?page=999999 is a key — so load answers withStatus(404, …) for one that names nothing, and the bounded store evicts the rest.

"The bust" below is the moment invalidateTags reaches its ISR step — after the read tiers (redis, lru, request-memo) cleared, so the re-render reads fresh rows. An action's cache.invalidates runs after its commit and is not awaited by the action's response, so the response can precede the bust by those tiers' latency.

Order inside one bust: read tiers (farthest first) → this origin's ISR pages → the broadcast to peers → the cdn tier last. Each replica that receives the broadcast purges the edge again after its own delete, so a peer that answered the old page inside the broadcast window is cleared from the edge too. A render that read its rows before the bust is answered to its own request private, no-store, with no purge key, and is never stored.

Finish a rollout before relying on 'purge'. A replica still on a release before this one reads onInvalidate as nothing: it marks the page stale and answers it once more, with stale-while-revalidate=86400.

Past maxStale the copy is dropped before the re-render, so a render that fails there answers its 5xx rather than the old page — that is what the bound means. Ages are measured by each replica's own clock against the entry's generatedAt; over a shared store, skew between replicas moves ttl and maxStale by that skew.

A shared store must be able to refuse a write. runtime.isrStore under 'purge' needs IsrStore.tagFence — sample(entities) before a render reads its rows, bump(entities) on a bust, and an atomic setIfCurrent(entry, entities, sampled) (a transaction, a script, a conditional put) that refuses a write whose reading moved. The generation is per tag entity (post for post:1), so an unrelated row's bust costs one extra render and never a stale page. memoryIsrStore implements it; a store without it is refused at boot when any route purges (X_ROUTE_MODE_INVALID, naming the route). A bust also asks the store which keys it holds under the tags, by the route table, as well as the invalidation graph — the graph only knows the pages this process rendered. It matches on the route's tags: a post:1 bust reaches every stored page of a route tagged post.

What isr never stores.

noStore is @ultimat3/render's, a mark on the data like withStatus and composable with it (noStore(withStatus(404, data))). isr only — an ssr page's cache is its route's cache key.

A page with an island is admitted to its own CSP by hash. The hydration runtime is an inline <script type="module">, and script-src admits it as one of the seven bodies HYDRATE_RUNTIME_BODIES enumerates, hashed at boot. Hashes and not a nonce because a render: 'static' page is a file on disk. The theme boot script is the second body the boot hashes, from theme.defaultMode (As of 20.2.0; an app writes neither the tag nor the hash). The speculation rules are the third (As of 2026-09, Client navigation). An app that adds its own inline script beyond those has to admit it the same way, at module scope in a file under apps/*/: configureHttp({ security: { csp: { extend: { 'script-src': [cspHashSource(body)] } } } }). The boot's own hashes are merged per directive, never replaced, so admitting a CDN source does not evict the hydration runtime's hash and lock every island out of the page.

As of 2026-08 the three closed sets a route is declared in — RENDER_MODES, OFFLINE_STRATEGIES, HYDRATE_STRATEGIES — are declared once, in @ultimat3/core, with each union derived from its array so the pair cannot disagree.

Re-export, never restate. Six packages each kept a hand-written copy until 2026-08 — 14 declarations in all — because imports only go down tiers and copying was the move available. 'spa' was then deleted from one of them and five went on admitting it under a green project-wide typecheck; @ultimat3/pwa's copy mapped it to cache-first, the one strategy that gives an app/ route a shared cache entry. bun run scripts/render-modes.ts --json refuses a second declaration, matching on the literal set rather than the name — the copy that did the damage was called PwaRenderMode.

Status, As of 2026-09-05: the design below is not what a generator emits. x g route and x new's dashboard both write render: 'ssr' on app/, deliberately: stream requires at least one <Suspense> boundary (X_ROUTE_MODE_INVALID without it), and the server JSX factory ships no hole marker yet — Solid's <Suspense> throws outside a Solid renderer. A page that declares stream today registers only with a boundary count it can prove, so the mode is available and the scaffold does not write it. Async data needs no boundary: await it in load.

An authed page needs fresh data and fast first paint. ssr gives freshness and a slow TTFB — the whole page waits for the slowest query. stream gives both halves: shell now, data as it resolves. A page whose body belongs in the browser declares an island({ src }), budgeted in real bytes; there is no client-side-only mode and no client router.

export default function Dashboard() {
  return (
    <Layout>
      <Header />                                {/* in the first flush */}
      <Suspense fallback={<StatsSkeleton />}>
        <Stats />                               {/* streamed when the query resolves */}
      </Suspense>
      <Suspense fallback={<FeedSkeleton />}>
        <Feed />                                {/* independent hole, independent flush */}
      </Suspense>
    </Layout>
  );
}

Solid's fine-grained reactivity is what makes this cheap:

In a VDOM framework a streaming shell still pays for hydrating the whole tree, which is why streaming there buys TTFB but not TBT. Here it buys both.

Independent holes each resolve their own queries; the tier-1 request memo means three holes reading the same query hit Postgres once.

Hydration is per-island, never per-page. A blown budget.js is a build failure, so islands cannot quietly accumulate.

One kind of island is hidden until it mounts, whatever the strategy (As of 2026-10): on a signed-in page with a sync node, an island that reads realtime's record store or outbox is held (data-x-hold, visibility:hidden, its box kept), booted at once, and revealed when it mounts or after 3 s. An island that only follows a channel's events, a roster or the connection is not, and with scripting off none is. The rule and the list of names: Realtime.

Per route, and one key: budget.js, in bytes. budget.lcp is deleted — nothing in the build observes a paint, so it was declared and never weighed.

budget.js counts raw minified bytes on disk — uncompressed, As of 2026-09-05: what the browser parses and executes, never the gzip or brotli size it transfers. A 350 kB library is 350 kB against the budget however well it compresses, because the number bounds execution cost, not bandwidth. measureDocumentJs in packages/cli/src/budgets.ts is the one reader, and the X_BUDGET_EXCEEDED line says (minified, uncompressed) so the unit is never inferred.

A blown budget is a build failure, not a warning:

x verify
  ✓ typecheck            ✓ import boundaries      ✓ migration drift
  ✓ lint                 ✓ tests (6 types)        ✓ contract diff
  ✗ budgets
      site/pricing   js 61kb > 40kb   (chart.js via shared/ui/button.tsx)

Failures name the cause — the transitive import that added the bytes — because "bundle too big" without a chain is not an instruction. x verify --json emits the same content machine-readably.

A convention that isn't a build error doesn't exist. SEO is the archetype — every SEO regression in history was a documented convention someone forgot.

meta: ({ post }) => ({ /* ... */ ld: ld.Article(post) })

Helpers, typed against schema.org shapes:

A missing required property is a type error, not a Rich Results Test failure discovered next week. Output is a single <script type="application/ld+json">, deduped per page.

Nothing here is a plugin. Deleting a route removes it from the sitemap in the same build.

See I18n, Timezones and dates, Money.

<Image src={post.cover} alt={post.title} sizes="(max-width: 700px) 100vw, 700px" priority />

One <Image> shape, one capability contract, stated once — in docs/idea/07-rendering-seo.md → Image pipeline: variants, srcset, inlined dimensions, the blur placeholder, the @ultimat3/core runtime, and the ImageTransformDriver seam AVIF/WebP variants come from. Restating it here would let the two copies drift.

As of 2026-09-07. A loader hands its data through withStatus(status, data) and the page renders as it always did — the route's own component, inside the app's own shell — with that status on the response.

import { defineRoute, withStatus } from '@ultimat3/render';

export const config = defineRoute({
  render: 'ssr',
  offline: 'runtime',
  load: async ({ params }) => {
    const host = await hostList({ id: params.host });
    return host === undefined
      ? withStatus(404, { kind: 'missing' as const, hostId: params.host })
      : { kind: 'page' as const, host };
  },
  meta: ({ data, t }) => ({ title: data.kind === 'missing' ? t('notFound') : data.host.label }),
});

A redirect is setRedirect(), from load. As of 2026-09-24. It is the same call an action's handler uses, from @ultimat3/http. On the page path, the request answers with that Location and status (default 303, and 302/307/308 when named) and no document is rendered:

import { setRedirect } from '@ultimat3/http';

load: async ({ params }) => {
  await recordOpen(params.token);            // a tracking pixel, a download link
  setRedirect('/pixel.gif', 302);
  return { params };                          // never rendered
},

With no declared cache, the redirect is private, no-store: the loader decided it for this one request, and a cached copy would answer later requests without running the loader. A route with a declared cache gets that instead. withStatus still refuses a 3xx, because a rendered document has no Location.

A refused page is withStatus(403, data). The same call answers a denial rendered in the shell — an @ultimat3/admin mount whose guardedPage() returned AdminPageDenied asks the same decideAll in its load and returns withStatus(403, data) (the admin README shows the load).

Not a throw, deliberately. Throwing is the other 404 and it is still there: a route the table does not have, or a loader that throws X_NOT_FOUND, gets the framework's error page — outside the app's shell, no sidebar, no session list. Measured in ai-maxxing on 2026-09-07, /fleet/nope rendered the right page inside the shell and answered 200, because the only way to the status was the way that lost the shell. The two answers stay distinct: the table lacks the route → throw → error page; the route exists and says "not found" → withStatus → its own page.

A browser that hits a failure in a production process gets the framework's error page — the status, the code, the request id, and nothing off the throwable. Until As of 2026-08-23 a production browser got problem+json with the internal cause and the author-facing fix: in it.

A 4xx in dev is the page a visitor will see, so it is the one the author sees; a 5xx is a defect, and the overlay is how dev debugs one. An agent (accept: application/json) gets problem+json in both.

• render and offline are declared on the route or defaulted by surface. Never inferred at runtime.
• revalidate.tags are typed handles from the tag graph — an unknown tag is a compile error (Caching and invalidation).
• Routes never touch the DB directly. Data comes from a query.
• A route holds no business logic. That is a service, behind an action.
• prerender() must be deterministic and bounded — it is a build input.
• Never hand-write a canonical URL, a sitemap entry, or sw.js.