Routes and render modes

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).

The canonical shape

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) }),
});

post — a page URL that also answers 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.

navigation — how the client router treats this page

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.

The descriptor

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.

Four render modes

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.

What a mode's headers are, and who has the last word

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.

A route's own cache, on ssr

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') }),
});

A shared document is rendered as nobody. As of 2026-11-02. isr and static run load, meta and the page with the anonymous actor, services rebuilt for it, the app's default zone, ctx.url at the document's own address, and no inbound headers at all, ctx.ip and ctx.peer null (withAnonymousRequest, @ultimat3/http). Whatever a stored page holds is answered to every later visitor, with public cache headers, so it varies on what its key carries: the URL and the locale. useRequestHeader() answers null; setRedirect() still works. A page that varies per visitor is ssr.

No declared origin: an isr entry is keyed by the request's origin too. canonical and og:url are absolute against the declared origin (APP_URL, SITE_ORIGIN, site.origin) or, with none, the request's own, so without this a first request with a foreign Host wrote that host into a page later visitors were answered. The origin rides the reserved __x_origin parameter. With a declared origin (http or https) there is no such parameter: one entry, and load is handed url at the declared origin. Without one, a process stores pages for 16 request origins (ISR_MAX_REQUEST_ORIGINS); any other Host is answered uncached, private, no-store, and evicts nothing (isr.origin.over_cap, logged once: declare APP_URL).

An isr entry is keyed by the negotiated locale. The store key is isrKey(url, locale, origin?) — 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.

revalidate — what an invalidation does, how old a copy may be, what the page varies on

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 }),
});

An isr route keys on no query unless it says so. As of 2026-11-02. /blog?x=1, /blog?x=2 and /blog?utm_source=mail are one render and one stored page, so no visitor can spend the origin's renders or push real pages out of the bounded store (it holds 1,000), and utm_* / fbclid / gclid do not split a page. An isr document is shared: what it varies on is the route's to declare.

The default store is bounded twice, and keeps what is read. As of 2026-11-09. memoryIsrStore({ maxEntries, maxBytes }): 1,000 pages (DEFAULT_ISR_MAX_ENTRIES) and 256 MiB of html.length (DEFAULT_ISR_MAX_BYTES), whichever is reached first. Least recently used goes first — a hit moves a page to the back, so a home page read on every request outlives cold pages generated after it; a stale mark keeps its place. A page larger than the whole byte cap is not stored and is rendered per request.

Declare every parameter the page reads. A page that reads ?currency= and does not list it 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.

How fast a purge takes a page down

"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.

One store for every replica: storageIsrStore. As of 2026-11-09. memoryIsrStore is one cache per process — three web replicas render a page three times and hold three copies. runtime.isrStore = storageIsrStore({ disk: disk('isr') }) keeps pages (isr/page/…) and tag-fence tokens (isr/fence/…) as objects on a @ultimat3/storage disk every replica reads. A bust writes a fresh token per tag entity; a write checks the reading, writes, then checks again and deletes its own page if a bust landed in between — a disk has no compare-and-put, and the bust lists the store only after its token is written, so no page outlives a bust its render predates. Bounded across replicas by maxEntries and maxBytes (the defaults above), swept every sweepEvery writes (32) per process, oldest write first — a read never writes, so it is not LRU. Every store call is awaited, so a custom store may answer with a promise (IsrAnswer<T>).

What isr never stores. What it does store was rendered as nobody (above); a per-visitor answer has no place in one, so that page is ssr.

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.

One declaration of the vocabulary, at tier 0

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.

Why stream is the app default

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.

x g route, x g resource and x new's dashboard write render: 'stream' on app/. A stream page with no hole registers and pays nothing: it is one flush.

import { Hole } from '@ultimat3/render';
import type { JSX } from 'solid-js';

// Yours: the components and the two reads.
type View = (props: { children?: JSX.Element; rows?: readonly unknown[] }) => JSX.Element;
declare const Layout: View, Header: View, Stats: View, Feed: View;
declare const StatsSkeleton: View, StatsUnavailable: View, FeedSkeleton: View;
declare const statsQuery: (input: object) => Promise<readonly unknown[]>;
declare const feedQuery: (input: object) => Promise<readonly unknown[]>;

// A thunk: it starts after the first flush, in the request's context. `useContext()`, `useT()` and
// the actor all work in it. A promise written straight into the JSX has started already.
const readStats = async () => <Stats rows={await statsQuery({})} />;
const readFeed = async () => <Feed rows={await feedQuery({})} />;

export function Page() {
  return (
    <Layout>
      <Header />                                {/* in the first flush */}
      <Hole fallback={<StatsSkeleton />} error={<StatsUnavailable />}>
        {readStats}                             {/* streamed when the query resolves */}
      </Hole>
      <Hole fallback={<FeedSkeleton />}>
        {readFeed}                              {/* independent hole, independent flush */}
      </Hole>
    </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.

What a hole does

Solid's own boundary component is not this: it throws outside a Solid renderer, and the server JSX factory is inert by design.

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

hydrate timings

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.

Budgets

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.

SEO enforcement

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.

Typed JSON-LD

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.

Generated from the route table

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

i18n routing

See I18n, Timezones and dates, Money.

Image pipeline

<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.

A route that answers a status

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 one adopter's app 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.

Error pages

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.

Rules

• 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.
• A URL off data inside an island goes through @ultimat3/ui's Link, or safeUrl(url, 'href') from @ultimat3/core at the call site. The island's server shell is screened like every page (a javascript: href is not emitted), but once it mounts Solid's compiled setter writes <a href={row.url}> as given; only the app's CSP stands between a looser policy and a live javascript: link. As of 2026-11-09 there is no build check for it.