@unitninety/site-kit 0.0.0-stage → 1.6.2

package/src/server/handlers.ts

@@ -0,0 +1,164 @@
+import { MEDIA_SANDBOX } from '../test-preview/media'
+import { createDraftBinding, previewBuildId } from '../test-preview/binding'
+import { timingSafeEqual } from 'node:crypto'
+import { manifestHash, type SiteManifest } from '../site'
+import { createTestPreviewRuntime, EXPECTED_PREVIEW_PARAM, previewResponseHeaders, requestPreviewToken, type TestPreviewContext, type TestPreviewRuntime } from '../test-preview/runtime'
+import { TEST_PREVIEW_ACTIONS, verifyGuardAttestation } from '../test-preview/guard'
+import { isTestPreviewToken } from '../test-preview/protocol.mjs'
+import type { NextAdapters } from './adapters'
+import type { Env } from './read'
+
+const SENTINEL = 'http://u90.invalid'
+/**
+ * A redirect target from a query string, reduced to a path on this site (R35, R41). The candidate is
+ * resolved the way a browser will resolve the `Location` — against a sentinel origin, so tab,
+ * newline and carriage return are stripped, a backslash reads as a slash and `//host` is a host —
+ * and kept only if it is still on that origin; anything else, or anything that does not parse, is
+ * `/`. What goes out is rebuilt from the parsed parts, so no control character reaches the header,
+ * and with the pathname's leading slashes collapsed to one: a dot segment can normalise a path that
+ * is still on the sentinel origin to a leading `//` (`/.//evil.example/x`, `/x/..//evil.example`
+ * and `/%2e//evil.example` all resolve to a pathname of `//evil.example…`), which a browser reads
+ * as protocol-relative — another host. exit-preview needs no secret, so without this every site
+ * would be an open redirect.
+ */
+export const safePath = (value: string | null): string => {
+  if (!value) return '/'
+  try {
+    const url = new URL(value, SENTINEL)
+    return url.origin === SENTINEL ? '/' + url.pathname.replace(/^\/+/, '') + url.search + url.hash : '/'
+  } catch {
+    return '/'
+  }
+}
+/** Explicit exit recovers ordinary navigation; retain other query bytes and the fragment. */
+const exitPath = (value: string | null): string => {
+  const local = new URL(safePath(value), SENTINEL)
+  const query = local.search.slice(1).split('&').filter(part => !new URLSearchParams(part).has(EXPECTED_PREVIEW_PARAM))
+  return local.pathname + (query.some(Boolean) ? '?' + query.join('&') : '') + local.hash
+}
+/** Constant time, so a wrong secret cannot be found a byte at a time; `timingSafeEqual` needs equal lengths. */
+const sameSecret = (provided: string | null, secret: string | undefined): boolean => {
+  if (!secret || provided === null) return false
+  const a = Buffer.from(provided), b = Buffer.from(secret)
+  return a.length === b.length && timingSafeEqual(a, b)
+}
+const bearer = (req: Request): string | null => {
+  const header = req.headers.get('authorization')
+  return header?.startsWith('Bearer ') ? header.slice('Bearer '.length) : null
+}
+
+const MEDIA_HEADERS = ['content-type', 'content-length', 'cache-control', 'content-security-policy', 'x-content-type-options', 'referrer-policy'] as const
+const MEDIA_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/
+const MEDIA_HEADERS_TIMEOUT_MS = 25_000
+
+export function createHandlers(manifest: SiteManifest, env: Env, adapters: NextAdapters, fetchImpl: typeof fetch = fetch, testPreview: TestPreviewRuntime = createTestPreviewRuntime({ env, fetch: fetchImpl }), now?: () => number, buildId?: string) {
+  const authed = (req: Request) => sameSecret(bearer(req), env.REVALIDATE_SECRET)
+  const previewJson = (b: unknown, status = 200) => new Response(JSON.stringify(b), { status, headers: { 'content-type': 'application/json', ...previewResponseHeaders } })
+  const json = (b: unknown, status = 200) => new Response(JSON.stringify(b), { status, headers: { 'content-type': 'application/json', 'cache-control': 'no-store' } })
+  /**
+   * `/api/u90/media/...` on the site's own origin, forwarded server-to-server to the platform (spec D5). It
+   * can only ever fetch the platform's media route: two or three plain segments, nothing else. Only the media
+   * headers come back, and the sandbox is reapplied if missing, because on the client's origin an SVG that
+   * could run script would sit beside the site's own cookies (spec D7).
+   */
+  const media = async (parts: readonly string[], context: TestPreviewContext | null): Promise<Response> => {
+    if ((parts.length !== 2 && parts.length !== 3) || !parts.every((p) => MEDIA_SEGMENT.test(p) && !p.includes('..'))) return json({ error: 'not found' }, 404)
+    if (!env.PLATFORM_URL) return json({ error: 'media is not configured' }, 503)
+    if (context) {
+      if (parts[0] !== context.claims.branchMediaKey && parts[0] !== context.trust.mediaKey) return json({ error: 'not found' }, 404)
+      parts = [context.trust.mediaKey, ...parts.slice(1)]
+    }
+    let upstream: Response
+    // The timeout covers only the wait for headers. A signal still armed would stay attached to the body and cut a long
+    // original — a video, a big PDF, a slow visitor — off mid-stream, after its content-length had already gone out.
+    // A first render of a crop can take seconds, so it is generous.
+    const controller = new AbortController()
+    const timer = setTimeout(() => controller.abort(), MEDIA_HEADERS_TIMEOUT_MS)
+    try {
+      // A redirect is never followed off the media route. `identity`: fetch decompresses a gzip body but keeps the
+      // upstream's compressed content-length, so ask for none.
+      upstream = await fetchImpl(`${env.PLATFORM_URL.replace(/\/+$/, '')}/api/u90/media/${parts.join('/')}`, { cache: 'no-store', headers: { 'accept-encoding': 'identity' }, redirect: 'manual', signal: controller.signal })
+      clearTimeout(timer)
+    } catch (error) {
+      clearTimeout(timer)
+      console.error('[u90] media passthrough failed:', error instanceof Error ? error.name : 'unknown')
+      return json({ error: 'media is unavailable' }, 503)
+    }
+    // The platform's media route never redirects. Forwarded bare, a 3xx would reach the visitor without its Location.
+    if (upstream.status >= 300 && upstream.status <= 399) {
+      void upstream.body?.cancel().catch(() => {})
+      return json({ error: 'media is unavailable' }, 502)
+    }
+    const headers = new Headers()
+    const encoded = upstream.headers.has('content-encoding')
+    for (const name of MEDIA_HEADERS) {
+      if (name === 'content-length' && encoded) continue // the length of bytes the body no longer is
+      const value = upstream.headers.get(name)
+      if (value !== null) headers.set(name, value)
+    }
+    if (!upstream.ok && !headers.has('cache-control')) headers.set('cache-control', 'no-store') // a refusal or an outage must not be kept by the site's CDN
+    if (context) for (const [key, value] of Object.entries(previewResponseHeaders)) headers.set(key, value)
+    if (!headers.has('content-security-policy')) headers.set('content-security-policy', MEDIA_SANDBOX)
+    if (!headers.has('x-content-type-options')) headers.set('x-content-type-options', 'nosniff')
+    return new Response(upstream.body, { status: upstream.status, headers })
+  }
+  const last = async (ctx: { params: Promise<{ u90: string[] }> }) => ((await ctx.params).u90 ?? []).at(-1)
+  return {
+    GET: async (req: Request, ctx: { params: Promise<{ u90: string[] }> }) => {
+      const all = (await ctx.params).u90 ?? []
+      // A query string is ignored, not refused: Vercel's image optimiser adds `?dpl=<deployment>` to every local
+      // fetch, and refusing it broke every optimised media image. `media()` builds the platform URL from the path
+      // segments alone, so the platform is always asked for the bare path and its cache keeps one entry per path.
+      const path = new URL(req.url).pathname
+      if (path === '/api/u90/test-preview' || path === '/api/u90/test-preview-capabilities') {
+        if (!verifyGuardAttestation(req, env, now?.())) return previewJson({ error: 'test preview guard is required' }, 403)
+        const identity = previewBuildId({ env, ...(buildId === undefined ? {} : { buildId }) })
+        const reason = !adapters.draftEnabled ? 'draft_mode_check_unavailable' : !identity ? 'build_identity_unavailable' : !adapters.draftBinding || !adapters.enableDraftBinding ? 'draft_binding_unavailable' : undefined
+        if (path.endsWith('-capabilities')) return new Response(JSON.stringify({ version: 1, protocol: 'u90tp1', guard: true, supported: !reason, ...(reason ? { reason } : {}), actions: reason ? [] : TEST_PREVIEW_ACTIONS, manifestHash: await manifestHash(manifest), deploymentId: identity }), { headers: { 'content-type': 'application/json', ...previewResponseHeaders } })
+        if (reason) return previewJson({ error: 'test preview setup unsupported', reason }, 403)
+        const url = new URL(req.url)
+        try {
+          const context = await testPreview.resolve(url.searchParams.get('token'))
+          if (!context) return previewJson({ error: 'invalid test session' }, 403)
+          await adapters.enableDraft(context.token)
+          const { bypass } = await adapters.draftBinding!()
+          if (!bypass || !(await adapters.draft()).enabled) return previewJson({ error: 'draft mode setup failed' }, 403)
+          const binding = createDraftBinding(env, identity!, context.token, bypass)
+          await adapters.enableDraftBinding!(binding, Math.max(1, context.claims.expiresAt - (now?.() ?? Math.floor(Date.now() / 1000))))
+          const target = new URL(safePath(url.searchParams.get('path')), 'https://u90.invalid')
+          target.searchParams.set(EXPECTED_PREVIEW_PARAM, '1')
+          return new Response(null, { status: 307, headers: { location: target.pathname + target.search + target.hash, ...previewResponseHeaders } })
+        } catch { return previewJson({ error: 'test preview refused' }, 403) }
+      }
+      let context: TestPreviewContext | null = null
+      if (path !== '/api/u90/exit-preview') {
+        try { context = await testPreview.resolve(requestPreviewToken(req)) } catch { return previewJson({ error: 'test preview refused' }, 403) }
+      }
+      if (all[0] === 'media') return media(all.slice(1), context)
+      if (context) return previewJson({ error: 'operation disabled in test preview' }, 403)
+      const seg = await last(ctx); const url = new URL(req.url)
+      if (seg === 'manifest') return authed(req) ? json(manifest) : json({ error: 'unauthorised' }, 401)
+      if (seg === 'preview') {
+        if (!sameSecret(url.searchParams.get('secret'), env.REVALIDATE_SECRET)) return json({ error: 'unauthorised' }, 401)
+        if (isTestPreviewToken(url.searchParams.get('token'))) return json({ error: 'use test-preview entry' }, 403)
+        await adapters.enableDraft(url.searchParams.get('token') ?? env.REVALIDATE_SECRET!)
+        adapters.redirect(safePath(url.searchParams.get('path')))
+      }
+      if (seg === 'exit-preview') { await adapters.disableDraft(); adapters.redirect(exitPath(url.searchParams.get('to'))) }
+      return json({ error: 'not found' }, 404)
+    },
+    POST: async (req: Request, ctx: { params: Promise<{ u90: string[] }> }) => {
+      try { if (await testPreview.resolve(requestPreviewToken(req))) return previewJson({ error: 'operation disabled in test preview' }, 403) } catch { return previewJson({ error: 'test preview refused' }, 403) }
+      const seg = await last(ctx)
+      if (seg !== 'revalidate') return json({ error: 'not found' }, 404)
+      if (!authed(req)) return json({ error: 'unauthorised' }, 401)
+      let body: unknown
+      try { body = await req.json() } catch { return json({ error: 'invalid body' }, 400) }
+      const rawTags = (body as { tags?: unknown } | null)?.tags
+      if (rawTags !== undefined && !(Array.isArray(rawTags) && rawTags.every((t) => typeof t === 'string'))) return json({ error: 'invalid body' }, 400)
+      const tags = rawTags as string[] | undefined
+      for (const t of tags ?? []) await adapters.revalidateTag(t)
+      return json({ ok: true, revalidated: tags ?? [] })
+    },
+  }
+}

package/src/server/index.ts

@@ -0,0 +1,6 @@
+export { createU90, type U90, type U90Options } from './createU90'
+export { PREVIEW_COOKIE, type NextAdapters } from './adapters'
+export { DRAFT_LOCALE_PARAM } from '../elements'
+export type { RouteRead } from '../site'
+export { U90Bridge } from '../bridge/U90Bridge'
+export type { TestPreviewContext } from '../test-preview/runtime'

package/src/server/read.ts

@@ -0,0 +1,207 @@
+import { assemble, replyFrom, type Reply, type ReplyTarget, type RouteRead, type Site, type SiteReply, type SitemapReply } from '../site'
+import { seedSite, type Store } from '../site/store'
+import type { SiteLanguages } from '../languages/routing'
+import { sourceMediaPaths } from '../test-preview/media'
+import type { TestPreviewContext, TestPreviewRuntime } from '../test-preview/runtime'
+import type { NextAdapters } from './adapters'
+
+export type Env = Partial<Record<'PLATFORM_URL' | 'PAYLOAD_API_KEY' | 'REVALIDATE_SECRET' | 'SITE_URL' | 'VERCEL_DEPLOYMENT_ID' | 'VERCEL_URL' | 'U90_TEST_PREVIEW_BUILD_ID', string>>
+/** `running` is the running code's `manifestHash`, compared with each reply's to tell whether the platform is behind a deploy. */
+type Deps = { site: Site; fetch: typeof fetch; env: Env; adapters: NextAdapters; running: Promise<string>; testPreview?: TestPreviewRuntime }
+
+const missing = (): RouteRead => ({ status: 'missing', tags: [] })
+// Keyed by site identity, not a single module-level slot: more than one site (e.g. under test) must not share a store.
+const defaultsStores = new WeakMap<Site, Promise<Store>>()
+const defaults = (site: Site): Promise<Store> => {
+  const cached = defaultsStores.get(site)
+  if (cached) return cached
+  const store = seedSite(site)
+  defaultsStores.set(site, store)
+  return store
+}
+let warned = false
+/** Read clients that have warned they read behind a deploy: once each, not once per read. */
+const warnedStale = new WeakSet<Deps>()
+
+/**
+ * URL + bearer + preview token + `cache: 'no-store'`, shared by every platform read; throws on any
+ * non-2xx so callers see one failure mode.
+ *
+ * `draft` is null for a published read. A draft read asks for `draft=1` and carries the preview
+ * cookie's token as `X-U90-Preview-Token`, and no header at all when the request has no preview
+ * cookie, rather than a made-up token.
+ *
+ * Built by concatenation (spec §4: `GET {PLATFORM_URL}/api/u90/v1/…`), not `new URL(path, base)`:
+ * a leading-slash `path` resolves against `base`'s origin only, silently discarding any path
+ * `PLATFORM_URL` itself carries. Concatenation keeps a path prefix (R33).
+ */
+type Draft = { token: string | null; test?: TestPreviewContext } | null
+async function platformFetch(d: Deps, endpoint: string, draft: Draft, locale?: string): Promise<unknown> {
+  const url = new URL(`${(draft?.test?.platformOrigin ?? d.env.PLATFORM_URL!).replace(/\/+$/, '')}/api/u90/v1${endpoint}`)
+  if (draft) url.searchParams.set('draft', '1')
+  // Only a caller that passes a locale sends one: a tenant with no language settings answers 400 to any `locale`, and a read without it is byte-for-byte the read sites made before languages.
+  if (locale) url.searchParams.set('locale', locale)
+  const res = await d.fetch(url, { headers: { authorization: `Bearer ${draft?.test?.token ?? d.env.PAYLOAD_API_KEY ?? ''}`, 'x-u90-media': 'paths', ...(draft?.token ? { 'x-u90-preview-token': draft.token } : {}) }, cache: 'no-store', ...(draft?.test ? { redirect: 'error' as const } : {}) })
+  if (!res.ok) throw new Error(`u90 read ${endpoint}: ${res.status}`)
+  const body = await res.json()
+  return draft?.test ? sourceMediaPaths(body, draft.test) : body
+}
+const endpointOf = (t: ReplyTarget): string =>
+  'route' in t ? `/route?path=${encodeURIComponent(t.route)}` : 'page' in t ? `/page/${encodeURIComponent(t.page)}` : `/entry/${encodeURIComponent(t.entry.collection)}/${encodeURIComponent(t.entry.slug)}`
+/** How a language reaches the reply's links: in their path (`prefix`, from the address), or in their query (`draftLocale`, draft only). */
+type Carry = { draftLocale?: string; prefix?: string }
+/**
+ * A reply assembled with the running code. The code's defaults are seeded only when the platform is behind a deploy.
+ * `carry.draftLocale` is passed only by a read in draft mode that asked for a language: internal link hrefs then keep the language the reply answered in.
+ * `carry.prefix` is passed by a read whose language came from the address: page and entry links then carry that prefix.
+ */
+async function assembled(d: Deps, target: ReplyTarget, reply: Reply, draft: boolean, carry: Carry = {}): Promise<RouteRead> {
+  const stale = reply.manifest !== (await d.running)
+  if (stale && !warnedStale.has(d)) {
+    warnedStale.add(d)
+    console.warn("[u90] the platform holds a different manifest from this deploy; declared pages, layouts and Singles it lacks render from the code's defaults")
+  }
+  const draftLocale = carry.draftLocale ? (reply.status === 'ok' && reply.locale ? reply.locale : carry.draftLocale) : undefined
+  return assemble(d.site, reply, { draft, target, stale, defaults: stale ? await defaults(d.site) : null, ...(draftLocale ? { draftLocale } : {}), ...(carry.prefix ? { localePrefix: carry.prefix } : {}) })
+}
+/** Renders from the declarations' defaults: only a site with no PLATFORM_URL does (spec §17). */
+async function fromDefaults(d: Deps, target: ReplyTarget, reason: string): Promise<RouteRead> {
+  if (!warned) { console.warn(`[u90] ${reason}; rendering from defaults`); warned = true }
+  const reply = replyFrom(d.site, await defaults(d.site), target, await d.running)
+  return { ...assemble(d.site, reply, { draft: false, target, stale: false, defaults: null }), unavailable: true }
+}
+
+/**
+ * R5: a `'use cache'` function has every outer-scope variable it references captured and bound
+ * as a serialisable cache argument. `d` holds functions (`fetch`, `adapters`) and is not
+ * serialisable, so `cachedRead` cannot close over it: `d` is registered here, at module scope, and
+ * looked up by a string key instead. Only `instance` and the JSON of the target, both strings,
+ * cross into the cached function.
+ */
+const registry = new Map<string, Deps>()
+/**
+ * The `target` argument of `cachedRead`, and so the part of its cache key that names what is read. A read without a
+ * locale is the target's own JSON, the key it had before languages, so no existing entry or tag moves; a read with one
+ * adds `locale` to that JSON, so each language is its own entry, and `prefix` too when the language came from the address,
+ * since its links differ from a read of the same language without one.
+ */
+export const cacheTarget = (target: ReplyTarget, locale: string | undefined, prefix?: string): string =>
+  JSON.stringify(locale ? { ...target, locale, ...(prefix ? { prefix } : {}) } : target)
+export function parseCacheTarget(key: string): { target: ReplyTarget; locale: string | undefined; prefix?: string } {
+  const { locale, prefix, ...target } = JSON.parse(key) as ReplyTarget & { locale?: string; prefix?: string }
+  return { target: target as ReplyTarget, locale, ...(prefix ? { prefix } : {}) }
+}
+/** What a read can be asked for besides its target. `prefix` is the address prefix of the language asked for (`/fr`), when the language came from the address: page and entry links then carry it. */
+export type ReadOptions = { locale?: string; prefix?: string }
+/**
+ * Next keeps at most this many tags from one `cacheTag(...)` call (`NEXT_CACHE_TAG_MAX_ITEMS`) and
+ * drops the rest, so a read's tags go in calls of 128; Next accumulates tags across calls within
+ * one cache scope.
+ */
+const CACHE_TAG_MAX_ITEMS = 128
+async function cachedRead(instance: string, target: string): Promise<RouteRead> {
+  'use cache'
+  const d = registry.get(instance)
+  if (!d) throw new Error(`u90: unknown read client "${instance}"`)
+  const { target: t, locale, prefix } = parseCacheTarget(target)
+  const reply = (await platformFetch(d, endpointOf(t), null, locale)) as Reply
+  for (let i = 0; i < reply.tags.length; i += CACHE_TAG_MAX_ITEMS) d.adapters.cacheTag(...reply.tags.slice(i, i + CACHE_TAG_MAX_ITEMS))
+  d.adapters.cacheLife(reply.status === 'ok' ? 'max' : 'minutes') // a missing read expires on its own as well as on `site`
+  return assembled(d, t, reply, false, prefix ? { prefix } : {})
+}
+/** The site-wide SEO settings, cached until `site` is revalidated. */
+async function cachedSite(instance: string): Promise<SiteReply> {
+  'use cache'
+  const d = registry.get(instance)
+  if (!d) throw new Error(`u90: unknown read client "${instance}"`)
+  const settings = (await platformFetch(d, '/site', null)) as SiteReply
+  d.adapters.cacheTag('site')
+  d.adapters.cacheLife('max')
+  return settings
+}
+
+/** isEnabled is permitted inside `use cache`; production can cache this false result without cookie reads.
+ * Next bypasses cache scopes in draft, so a preview evaluates the mode again and resolves its cookie outside cache. */
+async function draftEnabled(instance: string): Promise<boolean> {
+  'use cache'
+  const d = registry.get(instance)
+  if (!d) throw new Error(`u90: unknown read client "${instance}"`)
+  return d.adapters.draftEnabled ? d.adapters.draftEnabled() : false
+}
+
+export function createRead(d: Deps) {
+  const instance = String(registry.size) // deterministic per module evaluation; a site calls createU90 once
+  registry.set(instance, d)
+  /**
+   * This request's `/site`, read once however many callers ask (`perRequest`). Outside draft `cachedSite` is cached until
+   * `site` is revalidated; in draft Next re-runs every `'use cache'` function, so it is one uncached read per request.
+   */
+  const currentDraft = async (): Promise<Draft> => {
+    const { enabled, token } = await d.adapters.draft()
+    const test = await d.testPreview?.resolve(token)
+    if (test) return { token, test }
+    return enabled && token ? { token } : null
+  }
+  const siteOnce = d.adapters.perRequest(async () => {
+    const draft = await draftEnabled(instance) ? await currentDraft() : null
+    return draft?.test ? (await platformFetch(d, '/site', draft)) as SiteReply : cachedSite(instance)
+  })
+  const read = async (target: ReplyTarget, { locale, prefix }: ReadOptions = {}): Promise<RouteRead> => {
+    const draft = await currentDraft()
+    if (!d.env.PLATFORM_URL) return fromDefaults(d, target, 'PLATFORM_URL is not set')
+    // A paired site's failed read throws (spec §17): pages in the cache keep being served, an uncached
+    // page shows an error, and a build fails rather than publish defaults in place of the platform's content.
+    const { enabled, token } = await d.adapters.draft()
+    // A prefix rides only with the locale it names, as `cacheTarget` keys it: a prefix alone is no language.
+    const carry: Carry = locale && prefix ? { prefix } : locale ? { draftLocale: locale } : {}
+    if (draft) return assembled(d, target, (await platformFetch(d, endpointOf(target), draft, locale)) as Reply, true, carry)
+    // Draft mode with no preview token (a draft cookie left behind): what is published, uncached and unmarked.
+    if (enabled) return assembled(d, target, (await platformFetch(d, endpointOf(target), null, locale)) as Reply, false, carry)
+    return cachedRead(instance, cacheTarget(target, locale, prefix))
+  }
+  return {
+    route: (path: string, opts?: ReadOptions) => read({ route: path }, opts),
+    // a code page the running code does not declare is missing without asking
+    page: (key: string, opts?: ReadOptions) => (Object.hasOwn(d.site.pages, key) ? read({ page: key }, opts) : Promise.resolve(missing())),
+    entry: (collection: string, slug: string, opts?: ReadOptions) => read({ entry: { collection, slug } }, opts),
+    /**
+     * The platform's site-wide SEO settings (branch draft in test preview);  `null` for a site with no platform, whose code's `seo` is all
+     * there is. One read per request, shared with `languages()`, and cached outside draft.
+     */
+    site: async (): Promise<SiteReply | null> => {
+      if (!d.env.PLATFORM_URL) return null
+      if (!d.adapters.draftEnabled || await draftEnabled(instance)) await currentDraft()
+      return siteOnce()
+    },
+    /**
+     * The site's languages, from the same per-request `/site` read as `site()`: cached until `site` is revalidated outside
+     * draft, read once per request in draft. Null for a site with no platform, one with no languages, or a `/site` that
+     * cannot be read, in which case every address is the default's. Outside draft, a cache-scoped mode check avoids
+     * cookie reads, so a native root layout remains cacheable. Custom adapters missing that check are inspected
+     * outside cache and test credentials are refused before the availability fallback.
+     */
+    languages: async (): Promise<SiteLanguages | null> => {
+      if (!d.env.PLATFORM_URL) return null
+      // Refusal happens outside the ordinary availability fallback.
+      if (!d.adapters.draftEnabled || await draftEnabled(instance)) await currentDraft()
+      try {
+        return (await siteOnce()).languages ?? null
+      } catch (error) {
+        console.warn(`[u90] the site's languages could not be read, so every address reads in the default language: ${error instanceof Error ? error.message : String(error)}`)
+        return null
+      }
+    },
+    /** Internal legacy html compatibility: published root attributes without request draft APIs.
+     * Incomplete adapters cannot enter editable preview; all public reads still reject test tokens. */
+    legacyHtmlLanguages: async (): Promise<SiteLanguages | null> => {
+      if (!d.env.PLATFORM_URL) return null
+      try { return (await siteOnce()).languages ?? null } catch { return null }
+    },
+    sitemap: async (): Promise<SitemapReply> => {
+      const draft = await currentDraft()
+      if (d.env.PLATFORM_URL) return (await platformFetch(d, '/sitemap', draft?.test ? draft : null)) as SitemapReply
+      const entries = Object.values(d.site.collections).flatMap((c) => (c.route ? (c.entries ?? []).map((e) => ({ path: c.route!.replace(':slug', e.slug), lastModified: null })) : []))
+      return { entries: [...Object.values(d.site.pages).map((p) => ({ path: p.route, lastModified: null })), ...entries] }
+    },
+  }
+}

package/src/server/render.tsx

@@ -0,0 +1,46 @@
+import { createElement, Fragment, type ReactElement, type ReactNode } from 'react'
+import type { Site } from '../site'
+import type { RouteRead } from '../site'
+import type { LanguageLinks } from '../languages/routing'
+import { LanguageProvider } from '../switcher/LanguageSwitcher'
+import { DraftBlocks } from '../bridge/DraftBlocks'
+
+type BlockItem = { _id: string; _block: string; $path?: string } & Record<string, unknown>
+/** What a block declared with `entry:` receives, when the document being rendered is an entry page. */
+type EntryProp = { id: string; slug?: string; route?: string; fields?: Record<string, unknown> }
+
+export function createRender(site: Site) {
+  const Blocks = ({ value, slot, entry }: { value: unknown; slot?: ReactNode; entry?: EntryProp }): ReactElement => {
+    const items = (Array.isArray(value) ? value : []) as BlockItem[]
+    const renderedItems = items.map((item) => {
+      if (item._block === 'SLOT') return createElement(Fragment, { key: item._id }, slot)
+      const def = Object.hasOwn(site.blocks, item._block) ? site.blocks[item._block] : undefined
+      if (!def) return item.$path ? createElement('div', { key: item._id, 'data-u90-block': item.$path, 'data-u90-missing': item._block }, `Block "${item._block}" was removed`) : null
+      const { _id, _block, $path, ...fields } = item
+      // zones arrive rendered: replace each zone-typed field with <Blocks/>, threading `entry` through
+      const props: Record<string, unknown> = { ...fields }
+      for (const [name, decl] of Object.entries(def.fields)) if ('container' in (decl as object) && (decl as { container: string }).container === 'u90/zone') props[name] = createElement(Blocks, { value: fields[name], entry })
+      // a block declared with `entry:` renders inside that collection's entry pages and receives the entry itself
+      if (def.entry) props.entry = entry
+      const rendered = createElement(def.component as never, { key: _id, ...props } as never)
+      return $path ? createElement('div', { key: _id, 'data-u90-block': $path, style: { display: 'contents' } }, rendered) : rendered
+    })
+    return items.some((item) => item.$path)
+      ? createElement(DraftBlocks, { items: items.map((item, index) => ({ id: item._id, path: item.$path, content: renderedItems[index] })) })
+      : createElement(Fragment, null, ...renderedItems)
+  }
+  const Layout = ({ chain, layouts, children }: { chain: string[]; layouts: Record<string, unknown>; children: ReactNode }): ReactElement =>
+    chain.reduceRight<ReactElement>((inner, key) => createElement(Blocks, { value: (layouts[key] as { blocks: unknown })?.blocks, slot: inner }), createElement(Fragment, null, children))
+  /** `language`, on a language site's page only, puts the page's language and its addresses within reach of `LanguageSwitcher`. Without it the tree is the one it always was. */
+  const render = (read: RouteRead, language?: LanguageLinks): ReactElement => {
+    const doc = read.read as { blocks?: unknown; fields?: Record<string, unknown> } | undefined
+    const document = read.document
+    // an entry page's document carries no `route`; the collection declaration supplies the pattern
+    const entry: EntryProp | undefined = document?.kind === 'entry'
+      ? { id: document.id, slug: document.slug, route: document.collection ? site.collections[document.collection]?.route?.replace(':slug', document.slug) : undefined, fields: doc?.fields }
+      : undefined
+    const tree = <Layout chain={document?.layoutChain ?? []} layouts={read.layouts ?? {}}><Blocks value={doc?.blocks} entry={entry} /></Layout>
+    return language ? createElement(LanguageProvider, { value: language }, tree) : tree
+  }
+  return { Blocks, Layout, render }
+}

package/src/server/routes.tsx

@@ -0,0 +1,171 @@
+import type { Metadata, MetadataRoute } from 'next'
+import { createElement, Fragment, Suspense, type ReactElement } from 'react'
+import { metadataFor, type PageSeoInput, type RouteSeo, type Site } from '../site'
+import { robotsFor } from '../seo/robots'
+import { sitemapFor } from '../seo/sitemap'
+import { DRAFT_LOCALE_PARAM } from '../elements'
+import { withDraftLocale } from '../elements/leaves/link'
+import { languageAlternates, languageDirection, languageLinks, languageOfPath, type LanguageLinks, type PathLanguage, type SiteLanguages } from '../languages/routing'
+import type { NextAdapters } from './adapters'
+import type { createRead, ReadOptions } from './read'
+import type { createRender } from './render'
+
+type SearchParams = Promise<Record<string, string | string[] | undefined>>
+/** Next's page props. `searchParams` is optional so a caller that passes only `params` renders as before. */
+type PageParams = { params: Promise<{ slug?: string[] }>; searchParams?: SearchParams }
+/** A language id as the platform spells one (`fr`, `fr-CA`), of at most 35 characters, the length the Canvas keeps for a screen's language. Any other value of the parameter is no language. */
+const LOCALE_RE = /^(?=.{2,35}$)[A-Za-z]{2,8}(-[A-Za-z0-9]{1,8})*$/
+
+export function createRoutes(site: Site, read: ReturnType<typeof createRead>, r: ReturnType<typeof createRender>, adapters: NextAdapters, siteUrl: string | undefined) {
+  const pathOf = async (params: Promise<{ slug?: string[] }>) => '/' + ((await params).slug ?? []).join('/')
+  /**
+   * The language a draft render reads in: `DRAFT_LOCALE_PARAM` from the site's own address, in draft mode only. Outside draft
+   * `searchParams` is never awaited, so a published render reads, caches and renders exactly as it did before languages.
+   */
+  const draftLocale = async (searchParams: SearchParams | undefined): Promise<string | undefined> => {
+    if (!searchParams || !(await adapters.draft()).enabled) return undefined
+    const value = (await searchParams)[DRAFT_LOCALE_PARAM]
+    return typeof value === 'string' && LOCALE_RE.test(value) ? value : undefined
+  }
+  /** The read options for an address: a draft `DRAFT_LOCALE_PARAM` first, then the address's own language unless it is the default. None otherwise, so the read is the one sites made before languages. */
+  const readOptions = (language: PathLanguage | null, draft: string | undefined): ReadOptions | undefined =>
+    draft ? { locale: draft } : language?.prefix ? { locale: language.id, prefix: language.prefix } : undefined
+  /** Where a request reads: its address, the path the platform knows the page by, and the read options for its language. */
+  const placed = async (params: Promise<{ slug?: string[] }>, searchParams: SearchParams | undefined, languages: SiteLanguages | null) => {
+    const path = await pathOf(params)
+    const language = languageOfPath(path, languages)
+    const draft = await draftLocale(searchParams)
+    return { path, language, draft, rest: language?.rest ?? path, options: readOptions(language, draft) }
+  }
+  /**
+   * The switcher's links for a page of a language site: the language it is shown in (a draft `DRAFT_LOCALE_PARAM` first) and its
+   * address in each active language. In draft mode every link carries its language as `DRAFT_LOCALE_PARAM` on the unprefixed path,
+   * as internal links in a translated frame do, the default's included (R17): a Canvas screen that follows one changes its
+   * language, the default's link to a screen with no language, and never its path to a prefixed one it would edit as the base.
+   */
+  const switcherLinks = async (languages: SiteLanguages, language: PathLanguage, rest: string, draft: string | undefined): Promise<LanguageLinks> => {
+    const links = languageLinks(languages, rest, draft ?? language.id)
+    if (!(await adapters.draft()).enabled) return links
+    return { ...links, links: links.links.map((link) => ({ ...link, href: withDraftLocale(rest, link.id) })) }
+  }
+  /**
+   * The platform's site-wide SEO, or null when there is no platform or `/site` cannot be read. A
+   * failed read is never thrown into the page: the page keeps the manifest's defaults and sets no
+   * robots, so a platform hiccup cannot take a site out of search.
+   */
+  const siteSeo = () => read.site().catch((error: unknown) => {
+    console.warn(`[u90] the site-wide SEO settings could not be read, so this page uses the site's own defaults: ${error instanceof Error ? error.message : String(error)}`)
+    return null
+  })
+
+  /**
+   * R6: the async body of the page route. `pageBody` itself touches request-time state
+   * (`adapters.draft()`, backed by `draftMode()`/`cookies()`), so Cache Components requires a
+   * Suspense boundary above it — `page` below provides that boundary and never calls `pageBody`
+   * directly. `react-dom/server`'s `renderToString` cannot render an async component, which is
+   * why tests call `pageBody` (awaiting it themselves) rather than rendering `page`.
+   */
+  const pageBody = async ({ params, searchParams }: PageParams): Promise<ReactElement> => {
+    const languages = await read.languages()
+    const { path, language, draft, rest, options } = await placed(params, searchParams, languages)
+    const rr = await read.route(rest, options)
+    if (rr.status === 'missing') { if (!(await adapters.draft()).enabled) adapters.notFound(); return createElement('main', { 'data-u90-empty': path }, 'This page has no content yet.') }
+    const body = r.render(rr, languages && language ? await switcherLinks(languages, language, rest, draft) : undefined)
+    // Draft only, with a language from `DRAFT_LOCALE_PARAM`: the root layout cannot see the query, so the bridge puts this on `<html>`.
+    return draft ? createElement(Fragment, null, createElement('span', { hidden: true, 'data-u90-language': draft, 'data-u90-dir': languageDirection(draft) }), body) : body
+  }
+  const PageBody = async ({ params, searchParams }: PageParams): Promise<ReactElement> => pageBody({ params, searchParams })
+  const page = ({ params, searchParams }: PageParams): ReactElement => createElement(Suspense, { fallback: null }, createElement(PageBody, { params, searchParams }))
+
+  type FragmentParams = { searchParams: SearchParams }
+  /**
+   * The async body of the fragment page: one block, rendered on its own, for the Canvas to drop in
+   * while a newly added block is still saving. It reads draft state, so like `pageBody` it sits
+   * under a Suspense boundary (`fragment`) and is what the tests await.
+   *
+   * Draft mode is the gate, and the check reads `.enabled`: `adapters.draft()` resolves to
+   * `{ enabled, token }`, an object that is always truthy. The page is fetched with the draft cookie,
+   * not a secret, and a reader already in draft mode can see the whole draft page, so rendering one
+   * of its blocks shows them nothing new. An unknown block, a missing path or a reader not in draft
+   * renders nothing rather than an error; the Canvas treats an empty page as a failed fetch and
+   * leaves its skeleton for the refresh to replace.
+   *
+   * It makes no platform read, so `DRAFT_LOCALE_PARAM` changes nothing here: in a translated frame the block renders the same
+   * skeleton, and the frame's refresh then reads the page in that frame's language.
+   */
+  const fragmentBody = async ({ searchParams }: FragmentParams): Promise<ReactElement | null> => {
+    if (!(await adapters.draft()).enabled) return null
+    const params = await searchParams
+    const name = typeof params.block === 'string' ? params.block : ''
+    const path = typeof params.path === 'string' ? params.path : ''
+    if (!path || !Object.hasOwn(site.blocks, name)) return null
+    return <r.Blocks value={[{ _id: `preview-${path}`, _block: name, $path: path }]} />
+  }
+  const FragmentBody = async ({ searchParams }: FragmentParams): Promise<ReactElement | null> => fragmentBody({ searchParams })
+  /**
+   * Mounted by the site at `app/%5Fu90/fragment/page.tsx`, or inside a route group such as `app/(kit)/%5Fu90/fragment/page.tsx`
+   * when the site's root layout is `app/[[...slug]]/layout.tsx`, as a language site's is (a folder named `_u90` would be a
+   * private folder and serve nothing; `%5F` is Next's spelling of a leading underscore). Either serves `/_u90/fragment`.
+   */
+  const fragment = ({ searchParams }: FragmentParams): ReactElement => createElement(Suspense, { fallback: null }, createElement(FragmentBody, { searchParams }))
+
+  return {
+    page,
+    pageBody,
+    fragment,
+    fragmentBody,
+    metadata: async ({ params, searchParams }: PageParams): Promise<Metadata> => {
+      // `/site` before the route, because which route is read depends on its languages, which come from `read.languages()` as the page's do.
+      // `site()` and `languages()` share the request's one `/site` read, which the page's body shares too.
+      const [settings, languages] = await Promise.all([siteSeo(), read.languages()])
+      const { path, language, rest, options } = await placed(params, searchParams, languages)
+      const rr = await read.route(rest, options)
+      // R24: under Cache Components, `notFound()` inside the streamed body is a soft 404 (still
+      // a 200 response) — noindex a missing route explicitly rather than relying on status alone.
+      if (rr.status === 'missing') return { title: undefined, robots: { index: false, follow: false } }
+      const doc = rr.document
+      // Spec §8: the page's stored title, then its key, then its slug. An SEO title, when set, is the whole title.
+      const pageTitle = filled(doc?.title) ?? (doc?.key ? humanKey(doc.key) : doc?.slug) ?? ''
+      return metadataFor({ site: settings, manifest: site.seo, page: doc?.seo ? pageSeoInput(doc.seo) : null, pageTitle, origin: siteUrl, path, ...(language && languages ? { language: languageAlternates(languages, language, rr.translated) } : {}) })
+    },
+    sitemap: async (): Promise<MetadataRoute.Sitemap> => {
+      await adapters.connection() // R6: evaluated per request rather than cached at build
+      const [{ entries }, languages] = await Promise.all([read.sitemap(), read.languages()])
+      return sitemapFor(siteUrl, entries, languages)
+    },
+    /**
+     * `<html lang dir>` for a language site's root layout, mounted at `app/[[...slug]]/layout.tsx` so the address is a root
+     * parameter (`next/root-params`): the address's language, or `fallback` for a site with no languages and whenever `/site`
+     * cannot be read. `fallback` is `'en'` unless given, so a site whose default language is not English passes its default
+     * (`html({ params }, 'fr')`), or a page in its default would be marked English while the platform is down. It reads `params`
+     * and the request's one `/site` (`read.languages()`), and never calls draft mode or reads a cookie. Outside draft that
+     * `/site` is cached; in draft Next re-runs it uncached, once per request. Awaiting `params` outside Suspense means an
+     * address `rootParams` doesn't list has no static shell, so the layout exports `instant = false` for Cache Components'
+     * development checks.
+     */
+    html: async ({ params }: { params: Promise<{ slug?: string[] }> }, fallback = 'en'): Promise<{ lang: string; dir: 'ltr' | 'rtl' }> => {
+      // Incomplete legacy adapters retain root-attribute compatibility, but cannot start editable tests.
+      const languages = await (adapters.draftEnabled ? read.languages() : read.legacyHtmlLanguages())
+      const lang = languageOfPath(await pathOf(params), languages)?.id ?? fallback
+      return { lang, dir: languageDirection(lang) }
+    },
+    /** The root layout's `generateStaticParams`: Cache Components needs one value of each root parameter, and `/` is that value. Every other address renders on request. */
+    rootParams: async (): Promise<{ slug: string[] }[]> => [{ slug: [] }],
+    robots: async (): Promise<MetadataRoute.Robots> => {
+      await adapters.connection()
+      return robotsFor({ origin: siteUrl, site: await siteSeo() })
+    },
+  }
+}
+/** A value that holds more than whitespace, or null. */
+const filled = (s: string | undefined): string | null => (s && s.trim() !== '' ? s.trim() : null)
+const humanKey = (k: string) => k.replace(/([a-z])([A-Z])/g, '$1 $2').replace(/^./, (c) => c.toUpperCase())
+/**
+ * A read document's SEO as `metadataFor` takes it. The reply's `ogImage` media id was resolved to
+ * the media's URL when the reply was assembled (`site/assemble.ts`). A v1 media record carries no
+ * alt text, so the image has none.
+ */
+const pageSeoInput = (s: RouteSeo): PageSeoInput => ({
+  title: s.title ?? null, description: s.description ?? null, ogTitle: s.ogTitle ?? null, ogDescription: s.ogDescription ?? null,
+  ogImage: s.ogImage ? { url: s.ogImage } : null, canonical: s.canonical ?? null, noindex: s.noindex === true,
+})