@unitninety/site-kit 0.0.0-stage → 1.6.1

package/src/redirects/proxy.ts

@@ -0,0 +1,91 @@
+import { siteLocation } from './location'
+import { matchRedirect, type RedirectMatch } from './match'
+import { redirectsReplySchema, type RedirectRule } from './wire'
+
+type Options = {
+  /** The rules baked into the build (`env.U90_REDIRECTS_SNAPSHOT`), as JSON or already parsed. Defaults to that variable. */
+  snapshot?: string | { rules: RedirectRule[]; generatedAt: string } | null
+  /** Defaults to `process.env.PLATFORM_URL`. Without one the snapshot is all there is. */
+  platformUrl?: string
+  /** Defaults to `process.env.PAYLOAD_API_KEY`. */
+  apiKey?: string
+  fetch?: typeof fetch
+  now?: () => number
+  /** How long rules stay fresh before the next request starts a refresh. Defaults to 60. */
+  refreshSeconds?: number
+}
+
+/**
+ * The redirect step of a site's `proxy.ts`: `return (await redirects(request)) ?? next()`.
+ * It runs before routing, so a moved address never renders. Rules start from the build's snapshot and
+ * refresh from the v1 read API with the site's key. A refresh never delays a request: the request that
+ * finds the rules stale is answered from the rules it has, and the next one sees the new ones. The last
+ * good rules survive a failed or malformed refresh, and the next attempt waits a full interval.
+ * Next's own paths (`/_next/`) and the API (`/api/`) are never redirected.
+ */
+export function redirectsProxy(o: Options = {}): (request: Request) => Promise<Response | undefined> {
+  const platformUrl = o.platformUrl ?? process.env.PLATFORM_URL ?? ''
+  const apiKey = o.apiKey ?? process.env.PAYLOAD_API_KEY
+  const fetchImpl = o.fetch ?? globalThis.fetch
+  const now = o.now ?? Date.now
+  const intervalMs = (o.refreshSeconds ?? 60) * 1000
+  const snapshot = o.snapshot === undefined ? process.env.U90_REDIRECTS_SNAPSHOT : o.snapshot
+
+  let rules: readonly RedirectRule[] = []
+  if (snapshot) {
+    try {
+      const parsed = redirectsReplySchema.safeParse(typeof snapshot === 'string' ? JSON.parse(snapshot) : snapshot)
+      if (parsed.success) rules = parsed.data.rules
+      else console.warn('U90_REDIRECTS_SNAPSHOT is not a valid set of redirect rules, so the proxy starts with none until the platform answers.')
+    } catch {
+      console.warn('U90_REDIRECTS_SNAPSHOT is not readable JSON, so the proxy starts with no redirect rules until the platform answers.')
+    }
+  }
+
+  let refreshedAt = 0
+  let inFlight = false
+  async function refresh() {
+    inFlight = true
+    refreshedAt = now()
+    try {
+      const res = await fetchImpl(`${platformUrl.replace(/\/+$/, '')}/api/u90/v1/redirects`, { headers: { authorization: `Bearer ${apiKey ?? ''}` }, cache: 'no-store', signal: AbortSignal.timeout(5000) })
+      if (!res.ok) { console.warn(`The platform answered ${res.status} for the site's redirect rules, so the last good rules stay.`); return }
+      const parsed = redirectsReplySchema.safeParse(await res.json())
+      if (parsed.success) rules = parsed.data.rules
+      else console.warn('The platform\'s redirect rules did not parse, so the last good rules stay.')
+    } catch (err) {
+      console.warn(`The site's redirect rules could not be refreshed (${err instanceof Error ? err.message : String(err)}), so the last good rules stay.`)
+    } finally {
+      inFlight = false
+    }
+  }
+
+  /** Each warning once per rule: `unusable:<source>` for a destination no URL could be made of, `unsafe:<source>` for a refused Location. */
+  const warned = new Set<string>()
+  const warnOnce = (key: string, message: string) => {
+    if (warned.has(key)) return
+    warned.add(key)
+    console.warn(message)
+  }
+
+  // The `Location` is made safe by `siteLocation`: absolute, every run of `/` and `\` in a same-origin path collapsed, and a
+  // same-origin path under `/_next/` refused. A refused or unusable destination passes the request through rather than answer 500.
+  const answer = (m: RedirectMatch | null, requestUrl: URL): Response | undefined => {
+    if (!m) return undefined
+    if (m.status === 410) return new Response('Gone', { status: 410, headers: { 'content-type': 'text/plain; charset=utf-8' } })
+    const made = siteLocation(m.destination, requestUrl)
+    if ('refused' in made) {
+      if (made.refused === 'unusable') warnOnce(`unusable:${m.rule.source}`, `The redirect from ${m.rule.source} has a destination that is not a usable address, so requests for it pass through.`)
+      else warnOnce(`unsafe:${m.rule.source}`, `A request matched the redirect from ${m.rule.source} but its Location would be under /_next/ or leave the site, so it passed through. Requests like this are not warned about again for this rule.`)
+      return undefined
+    }
+    return new Response(null, { status: m.status, headers: { location: made.location.href } })
+  }
+
+  return async (request) => {
+    const url = new URL(request.url)
+    if (url.pathname.startsWith('/_next/') || url.pathname.startsWith('/api/')) return undefined
+    if (platformUrl && !inFlight && now() - refreshedAt >= intervalMs) void refresh()
+    return answer(matchRedirect(rules, url.pathname + url.search), url)
+  }
+}

package/src/redirects/wire.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod'
+
+/** The most rules a reply may carry. */
+export const MAX_REDIRECT_RULES = 2000
+
+/** What a rule does when it matches. `410` means gone and carries no destination. */
+export const redirectStatusSchema = z.union([z.literal(301), z.literal(302), z.literal(410)])
+export const redirectMatchTypeSchema = z.enum(['exact', 'prefix', 'pattern'])
+
+/** One rule as the platform serves it. `source` is already normalised by `normalisePath` when the platform stores it. */
+export const redirectRuleSchema = z.object({
+  source: z.string().startsWith('/'),
+  /** A same-origin path, or an absolute URL for an off-site move. Empty for `410`. */
+  destination: z.string(),
+  status: redirectStatusSchema,
+  matchType: redirectMatchTypeSchema,
+  preserveQuery: z.boolean(),
+})
+
+/** What `GET /api/u90/v1/redirects` returns. */
+export const redirectsReplySchema = z.object({
+  rules: z.array(redirectRuleSchema).max(MAX_REDIRECT_RULES),
+  /** When the platform generated it. Carried for diagnostics, never used for matching. */
+  generatedAt: z.string(),
+})
+
+export type RedirectStatus = z.infer<typeof redirectStatusSchema>
+export type RedirectMatchType = z.infer<typeof redirectMatchTypeSchema>
+export type RedirectRule = z.infer<typeof redirectRuleSchema>
+export type RedirectsReply = z.infer<typeof redirectsReplySchema>

package/src/seo/jsonLd.ts

@@ -0,0 +1,70 @@
+import type { OpeningHoursDay, OpeningHoursRow, SiteReply } from '../site/wire'
+
+/** A value trimmed, or null when it is blank or absent. */
+const filled = (value: null | string | undefined): null | string => {
+  const trimmed = (value ?? '').trim()
+  return trimmed === '' ? null : trimmed
+}
+
+type OpeningHoursSpec = {
+  '@type': 'OpeningHoursSpecification'
+  closes: string
+  dayOfWeek: OpeningHoursDay[]
+  opens: string
+}
+
+/**
+ * `organisation.openingHours`, as schema.org `OpeningHoursSpecification` entries.
+ *
+ * A closed day, or a day with no `opens`/`closes` pair, has nothing schema.org can use and is
+ * dropped rather than emitted with a null time: Google reports a spec entry with a missing time as
+ * an error, which is worse than saying nothing about that day.
+ *
+ * Days sharing an identical `{opens, closes}` collapse into one entry listing every `dayOfWeek`
+ * that applies, which schema.org allows.
+ */
+const openingHoursSpecification = (rows: readonly OpeningHoursRow[]): OpeningHoursSpec[] => {
+  const groups = new Map<string, OpeningHoursSpec>()
+  for (const row of rows) {
+    if (row.closed || row.opens === null || row.closes === null) continue
+    const key = `${row.opens}|${row.closes}`
+    const existing = groups.get(key)
+    if (existing) existing.dayOfWeek.push(row.day)
+    else groups.set(key, { '@type': 'OpeningHoursSpecification', closes: row.closes, dayOfWeek: [row.day], opens: row.opens })
+  }
+  return [...groups.values()]
+}
+
+/**
+ * The organisation, as schema.org JSON-LD, or null.
+ *
+ * The name is the organisation's `legalName`, else the site name. Without either, or without an
+ * organisation, there is none: a business panel with no name is malformed structured data, and
+ * Google reports it as an error against the site.
+ */
+export const organisationJsonLd = ({ origin, site }: { origin: string; site: SiteReply | null }): Record<string, unknown> | null => {
+  const organisation = site?.organisation
+  const name = filled(organisation?.legalName) ?? filled(site?.siteName)
+  if (!organisation || !name) return null
+
+  const openingHoursSpec = openingHoursSpecification(organisation.openingHours)
+
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'Organization',
+    name,
+    url: origin.replace(/\/$/, ''),
+    ...(organisation.logo?.url ? { logo: organisation.logo.url.startsWith('/') && !organisation.logo.url.startsWith('//') ? new URL(organisation.logo.url, origin).toString() : organisation.logo.url } : {}),
+    ...(filled(organisation.phone) ? { telephone: organisation.phone } : {}),
+    ...(filled(organisation.email) ? { email: organisation.email } : {}),
+    ...(filled(organisation.address) ? { address: organisation.address } : {}),
+    // Structured hours win when there are any. The free-text field is the fallback for a tenant
+    // who has not used the structured editor, emitted as a string.
+    ...(openingHoursSpec.length > 0
+      ? { openingHoursSpecification: openingHoursSpec }
+      : filled(organisation.legacyOpeningHours)
+        ? { openingHours: organisation.legacyOpeningHours }
+        : {}),
+    ...(organisation.sameAs.length > 0 ? { sameAs: organisation.sameAs } : {}),
+  }
+}

package/src/seo/metadata.ts

@@ -0,0 +1,127 @@
+import type { Metadata } from 'next'
+import type { LanguageAlternates } from '../languages/routing'
+import type { ReplySeo, SiteReply } from '../site/wire'
+import { applyTitleTemplate } from './title'
+
+/** A value trimmed, or null when it is blank or absent: an empty field falls back rather than overriding. */
+const filled = (value: string | null | undefined): string | null => {
+  const trimmed = (value ?? '').trim()
+  return trimmed === '' ? null : trimmed
+}
+
+/** A page's SEO as v1's reply gives it (`ReplySeo`), with its `ogImage` media id resolved to the media's URL. */
+export type PageSeoInput = Omit<ReplySeo, 'ogImage'> & { ogImage: { url: string; alt?: string } | null }
+
+export type MetadataInput = {
+  /** The platform's site-wide SEO settings; null for a site with no platform, or when `/site` could not be read. */
+  site: SiteReply | null
+  /** The site code's own `seo` defaults, used field by field where the platform has set nothing: its template, share image and organisation name. */
+  manifest: { titleTemplate?: string; defaultImage?: string; organisation?: { name?: string } } | null
+  page: PageSeoInput | null
+  /** The page's own title: its stored title, else its key or slug. The template is applied to it. */
+  pageTitle: string
+  /** The site's origin. Without one, and with no canonical of the page's own, no canonical is set. */
+  origin?: string
+  /** The path this page answers at, e.g. `/about-us` or `/`. */
+  path: string
+  /** The page's language, when the site has languages: `path` is then that language's own address (`/fr/about`). */
+  language?: LanguageAlternates
+}
+
+/**
+ * A path made absolute against the site's URL, as v1's sitemap lists it and its canonicals name it:
+ * the home page is `https://example.com/`, with its slash.
+ */
+export const siteUrlFor = (origin: string, path: string): string => new URL(path, origin).toString()
+
+/**
+ * v1's indexing rule. A site whose platform turned indexing off is neither indexed nor followed.
+ * A page that asks not to be listed is still followed. A site the platform said nothing about
+ * (no platform, or a `/site` read that failed) sets no robots at all: a failed read must never
+ * take a site out of search.
+ */
+const v1Robots = (site: SiteReply | null, page: PageSeoInput | null): Metadata['robots'] =>
+  site?.allowIndexing === false ? { follow: false, index: false } : page?.noindex === true ? { follow: true, index: false } : undefined
+
+/**
+ * Next metadata for a v1 page: the page's SEO over the platform's site-wide SEO over the manifest's
+ * defaults, with v1's indexing rule. The page's SEO title is the whole title, as the platform's
+ * SEO screen shows it; without one, the platform's template, else the manifest's, is applied to
+ * the page's own title, with the platform's site name, else the manifest's organisation name, as
+ * `%site%`. The platform answers null for a template its tenant never chose, so a site keeps its
+ * manifest's until the tenant sets one. Every string counts as set only when it holds more than
+ * whitespace, so a person who clears a field gets the fallback rather than an empty value, and a
+ * key with no value is left out.
+ */
+/**
+ * A language's Open Graph locale, `language_TERRITORY` as Open Graph requires: a bare language takes its likeliest
+ * territory (`fr` is `fr_FR`), and an id the runtime cannot place keeps its own spelling with `_` for `-`.
+ */
+export function ogLocale(id: string): string {
+  try {
+    const { language, region } = new Intl.Locale(id).maximize()
+    if (region) return `${language}_${region}`
+  } catch {
+    // not a language tag the runtime knows
+  }
+  return id.replace(/-/g, '_')
+}
+
+export function metadataFor(i: MetadataInput): Metadata {
+  const { site, manifest, page } = i
+  const siteName = filled(site?.siteName) ?? filled(manifest?.organisation?.name)
+  const title = filled(page?.title) ?? filled(applyTitleTemplate({ pageTitle: i.pageTitle, siteName, template: filled(site?.titleTemplate) ?? filled(manifest?.titleTemplate) }))
+  const description = filled(page?.description) ?? filled(site?.description)
+  // Social fields fall back to the resolved title and description, never the raw template.
+  const ogTitle = filled(page?.ogTitle) ?? title
+  const ogDescription = filled(page?.ogDescription) ?? description
+  const siteImage = site?.ogImage?.url ? { url: site.ogImage.url, alt: site.ogImage.alt } : null
+  const defaultImage = filled(manifest?.defaultImage)
+  const image = page?.ogImage ?? siteImage ?? (defaultImage ? { url: defaultImage } : null)
+  /** A share image given as a path (kit 1.5 media) is absolute against the site's own origin; a URL, protocol-relative included, is left alone. */
+  const imageUrl = image?.url && image.url.startsWith('/') && !image.url.startsWith('//') && i.origin !== undefined ? siteUrlFor(i.origin, image.url) : image?.url
+  const google = filled(site?.googleVerification)
+  const bing = filled(site?.bingVerification)
+  const verification: Record<string, string> = {}
+  if (google) verification['google-site-verification'] = google
+  if (bing) verification['msvalidate.01'] = bing
+  const handle = filled(site?.twitterHandle)
+  // R9: a page in a language other than the default names itself, never a canonical stored on the shared base document.
+  const own = i.language !== undefined && !i.language.isDefault
+  const locale = own ? ogLocale(i.language!.id) : filled(site?.locale)
+  const self = i.origin !== undefined ? siteUrlFor(i.origin, i.path) : null
+  const stored = own ? null : filled(page?.canonical)
+  const canonical = stored ?? self
+  // hreflang only on a page that is its own canonical (Google ignores it elsewhere), and only on a variant offered to search (ruling R2).
+  const namesItself = stored === null || (self !== null && i.origin !== undefined && siteUrlFor(i.origin, stored) === self)
+  const listed = i.language !== undefined && i.origin !== undefined && i.language.indexable && namesItself
+  // One language alone has no alternate to name, as its sitemap entry names none.
+  const languages = listed && i.language!.alternates.length > 1
+    ? { ...Object.fromEntries(i.language!.alternates.map((a) => [a.id, siteUrlFor(i.origin!, a.path)])), 'x-default': siteUrlFor(i.origin!, i.language!.xDefault) }
+    : null
+  const alternateLocale = listed ? i.language!.alternates.filter((a) => a.id !== i.language!.id).map((a) => ogLocale(a.id)) : []
+  const robots = v1Robots(site, page) ?? (i.language && !i.language.indexable ? { follow: true, index: false } : undefined)
+  return {
+    ...(canonical || languages ? { alternates: { ...(canonical ? { canonical } : {}), ...(languages ? { languages } : {}) } } : {}),
+    ...(description ? { description } : {}),
+    openGraph: {
+      ...(ogDescription ? { description: ogDescription } : {}),
+      ...(imageUrl ? { images: [{ ...(image?.alt !== undefined ? { alt: image.alt } : {}), url: imageUrl }] } : {}),
+      ...(alternateLocale.length ? { alternateLocale } : {}),
+      ...(locale ? { locale } : {}),
+      ...(siteName ? { siteName } : {}),
+      ...(ogTitle ? { title: ogTitle } : {}),
+      type: 'website',
+    },
+    ...(Object.keys(verification).length > 0 ? { other: verification } : {}),
+    ...(robots ? { robots } : {}),
+    ...(title ? { title } : {}),
+    twitter: {
+      card: site?.twitterCard ?? 'summary_large_image',
+      ...(ogDescription ? { description: ogDescription } : {}),
+      ...(imageUrl ? { images: [imageUrl] } : {}),
+      ...(handle ? { site: handle.startsWith('@') ? handle : `@${handle}` } : {}),
+      ...(ogTitle ? { title: ogTitle } : {}),
+    },
+  }
+}

package/src/seo/robots.ts

@@ -0,0 +1,14 @@
+import type { MetadataRoute } from 'next'
+import type { SiteReply } from '../site/wire'
+import { siteUrlFor } from './metadata'
+
+/**
+ * `robots.txt`: every crawler is allowed, and the sitemap named, unless the platform's
+ * `allowIndexing` is off, when everything is disallowed and no sitemap is named. A `/site` read that
+ * failed (`site` null) allows crawling, so a platform hiccup never takes a site out of search. With
+ * no origin there is no absolute sitemap URL to name.
+ */
+export const robotsFor = ({ origin, site }: { origin: string | undefined; site: SiteReply | null }): MetadataRoute.Robots =>
+  site?.allowIndexing === false
+    ? { rules: { userAgent: '*', disallow: '/' } }
+    : { rules: { userAgent: '*', allow: '/' }, ...(origin ? { sitemap: siteUrlFor(origin, '/sitemap.xml') } : {}) }

package/src/seo/sitemap.ts

@@ -0,0 +1,22 @@
+import type { MetadataRoute } from 'next'
+import { addressIn, type SiteLanguages } from '../languages/routing'
+import type { SitemapReply } from '../site/wire'
+import { siteUrlFor } from './metadata'
+
+/**
+ * The platform's sitemap entries as Next's `sitemap.xml` takes them: absolute against the site's origin, or as stored without
+ * one. With languages, each entry is listed at its address in each language the platform lists it in (every active language
+ * when it lists none), in the settings' order. Each url of an entry listed in more than one language names the others and
+ * x-default (plan 4 Task 4 minor).
+ */
+export const sitemapFor = (origin: string | undefined, entries: SitemapReply['entries'], languages?: SiteLanguages | null): MetadataRoute.Sitemap =>
+  entries.flatMap((e) => {
+    const urlOf = (path: string) => (origin ? siteUrlFor(origin, path) : path)
+    const lastModified = e.lastModified ? { lastModified: e.lastModified } : {}
+    if (!languages) return [{ url: urlOf(e.path), ...lastModified }]
+    // The platform lists an entry's languages (ruling R2); a platform from before says nothing, and every active language is listed.
+    const listed = languages.active.filter((language) => e.languages === undefined || e.languages.includes(language.id))
+    const urls = Object.fromEntries(listed.map((language) => [language.id, urlOf(addressIn(languages, language.id, e.path))]))
+    const alternates = listed.length > 1 ? { alternates: { languages: { ...urls, 'x-default': urlOf(e.path) } } } : {}
+    return listed.map((language) => ({ url: urls[language.id]!, ...lastModified, ...alternates }))
+  })

package/src/seo/title.ts

@@ -0,0 +1,22 @@
+/** A value that holds more than whitespace, trimmed; anything else is unset. */
+const filled = (s: string | null): string | null => (s && s.trim() !== '' ? s.trim() : null)
+/** The separators a template puts between the page and the site: `—`, `|`, `·`, `:` and `-`. */
+const SEPARATOR = '[—|·:-]'
+
+/**
+ * A page's title through a template. `%page%` and `%s` are the page title, `%site%` the site name.
+ * With no site name, `%site%` goes and so does the separator beside it. A template with no page
+ * token is used as written. Substitution is one pass, so a title holding `$&` or a token is
+ * inserted as written.
+ */
+export const applyTitleTemplate = ({ pageTitle, siteName, template }: { pageTitle: string | null; siteName: string | null; template: string | null }): string => {
+  const page = filled(pageTitle)
+  const site = filled(siteName)
+  const shape = filled(template)
+  if (!shape) return page ?? site ?? ''
+  if (!page) return site ?? ''
+  const withSite = site
+    ? shape
+    : shape.replace(new RegExp(`\\s*${SEPARATOR}\\s*%site%`), '').replace(new RegExp(`%site%\\s*${SEPARATOR}\\s*`), '').replace('%site%', '')
+  return withSite.replace(/%page%|%site%|%s/g, (token) => (token === '%site%' ? (site ?? '') : page)).trim()
+}

package/src/server/adapters.ts

@@ -0,0 +1,73 @@
+import { cacheLife, cacheTag, revalidateTag } from 'next/cache'
+import { cookies, draftMode } from 'next/headers'
+import { notFound, redirect } from 'next/navigation'
+import { connection } from 'next/server'
+import { cache } from 'react'
+import { PREVIEW_BINDING_COOKIE } from '../test-preview/binding'
+import { isTestPreviewToken } from '../test-preview/protocol.mjs'
+
+export type NextAdapters = {
+  cacheTag(...tags: string[]): void; cacheLife(profile: string): void
+  /** Lightweight draft-mode check, called inside a cache scope; must not read cookies/headers. */
+  draftEnabled?(): Promise<boolean>
+  draft(): Promise<{ enabled: boolean; token: string | null }>
+  /** Entry-only cookie access, after enabling draft; never called by ordinary reads. */
+  draftBinding?(): Promise<{ bypass: string | null; binding: string | null }>
+  enableDraftBinding?(binding: string, maxAge: number): Promise<void>
+  enableDraft(token: string): Promise<void>; disableDraft(): Promise<void>
+  revalidateTag(tag: string): Promise<void>; notFound(): never; redirect(url: string): never
+  /** Cache Components: reading this inside `routes.sitemap` forces per-request evaluation instead of build-time caching (R6). */
+  connection(): Promise<void>
+  /** `fn` called at most once per request, its promise shared by every caller in that request: React's `cache`, which Next scopes to one request across `generateMetadata`, layouts and the page. */
+  perRequest<T>(fn: () => Promise<T>): () => Promise<T>
+}
+export const PREVIEW_COOKIE = 'u90-preview-token'
+/**
+ * `cookies()` is a request-time API: calling it makes the render that called it dynamic, so reading
+ * the preview cookie on every read made every production render dynamic. `draftMode().isEnabled`
+ * is not (Next lets a `'use cache'` scope read it), so it is asked first and the cookie is read
+ * only in draft. The two request APIs are parameters so a test can see which were called.
+ */
+export async function readDraft(
+  mode: () => Promise<{ isEnabled: boolean }>,
+  jar: () => Promise<{ get(name: string): { value: string } | undefined }>,
+): Promise<{ enabled: boolean; token: string | null }> {
+  if (!(await mode()).isEnabled) return { enabled: false, token: null }
+  return { enabled: true, token: (await jar()).get(PREVIEW_COOKIE)?.value ?? null }
+}
+export const nextAdapters: NextAdapters = {
+  cacheTag: (...tags) => cacheTag(...tags),
+  cacheLife: (profile) => cacheLife(profile as never),
+  draftEnabled: async () => (await draftMode()).isEnabled,
+  draft: () => readDraft(draftMode, cookies),
+  enableDraft: (token) => writeDraft(draftMode, cookies, token),
+  draftBinding: async () => { const jar = await cookies(); return { bypass: jar.get('__prerender_bypass')?.value ?? null, binding: jar.get(PREVIEW_BINDING_COOKIE)?.value ?? null } },
+  enableDraftBinding: async (binding, maxAge) => { (await cookies()).set(PREVIEW_BINDING_COOKIE, binding, { httpOnly: true, sameSite: 'none', secure: true, path: '/', maxAge }) },
+  disableDraft: () => clearDraft(draftMode, cookies),
+  revalidateTag: async (tag) => { revalidateTag(tag, { expire: 0 }) },
+  notFound: () => notFound(), redirect: (url) => redirect(url),
+  connection: () => connection(),
+  perRequest: (fn) => cache(fn),
+}
+/** Public-cookie API injection keeps native cookie retention and cleanup testable without Next internals. */
+type DraftCookieOptions = { httpOnly: true; sameSite: 'none'; secure: true; path: '/'; maxAge?: number }
+export async function writeDraft(
+  mode: () => Promise<{ enable(): void }>,
+  jar: () => Promise<{ set(name: string, value: string, options: DraftCookieOptions): void }>,
+  token: string,
+): Promise<void> {
+  (await mode()).enable()
+  const options: DraftCookieOptions = { httpOnly: true, sameSite: 'none', secure: true, path: '/', ...(isTestPreviewToken(token) ? {} : { maxAge: 12 * 3600 }) }
+  // A test token stays as an expired-session tombstone until explicit exit/re-entry or browser-session end.
+  const store = await jar()
+  store.set(PREVIEW_COOKIE, token, options)
+}
+export async function clearDraft(
+  mode: () => Promise<{ disable(): void }>,
+  jar: () => Promise<{ delete(name: string): void }>,
+): Promise<void> {
+  (await mode()).disable()
+  const store = await jar()
+  store.delete(PREVIEW_COOKIE)
+  store.delete(PREVIEW_BINDING_COOKIE)
+}

package/src/server/createU90.ts

@@ -0,0 +1,96 @@
+import { isTestPreviewToken } from '../test-preview/protocol.mjs'
+import { createTestPreviewRuntime, requestPreviewToken, TestPreviewRefused, type TestPreviewOptions } from '../test-preview/runtime'
+import { createSiteFeatures, type SiteFeaturesOptions } from '../features/server/gateway'
+import { failure } from '../features/server/http'
+import { manifestFrom, manifestHash, type Site } from '../site'
+import { nextAdapters, type NextAdapters } from './adapters'
+import { createHandlers } from './handlers'
+import { createRead, type Env } from './read'
+import { createRender } from './render'
+import { createRoutes } from './routes'
+
+export type U90Options = {
+  testPreview?: Pick<TestPreviewOptions, 'now' | 'trustTimeoutMs' | 'buildId'>
+  features?: Pick<SiteFeaturesOptions, 'verifyVisitor' | 'resolveClientIdentity'>
+  fetch?: typeof fetch
+  env?: Env
+  adapters?: Partial<NextAdapters>
+}
+export function createU90(site: Site, options: U90Options = {}) {
+  const env: Env = options.env ?? {
+    PLATFORM_URL: process.env.PLATFORM_URL,
+    PAYLOAD_API_KEY: process.env.PAYLOAD_API_KEY,
+    REVALIDATE_SECRET: process.env.REVALIDATE_SECRET,
+    SITE_URL: process.env.SITE_URL,
+    VERCEL_DEPLOYMENT_ID: process.env.VERCEL_DEPLOYMENT_ID,
+    VERCEL_URL: process.env.VERCEL_URL,
+    U90_TEST_PREVIEW_BUILD_ID: process.env.U90_TEST_PREVIEW_BUILD_ID,
+  }
+  const adapters = {
+    ...nextAdapters, ...options.adapters,
+    // A custom draft adapter must explicitly provide the lightweight check to support tests.
+    draftEnabled: options.adapters?.draftEnabled ?? (options.adapters?.draft ? undefined : nextAdapters.draftEnabled),
+  }
+  const runtime = createTestPreviewRuntime({ env, fetch: options.fetch, ...options.testPreview })
+  const testPreview = {
+    resolve: async (token: string | null) => {
+      if (!adapters.draftEnabled && isTestPreviewToken(token)) throw new TestPreviewRefused()
+      return runtime.resolve(token)
+    },
+  }
+  const manifest = manifestFrom(site) // throws SiteDeclarationError at module evaluation → next build fails
+  const runtimeRead = createRead({
+    site,
+    fetch: options.fetch ?? fetch,
+    env,
+    adapters,
+    running: manifestHash(manifest),
+    testPreview,
+  })
+  // The published-only compatibility reader is private to legacy html root attributes.
+  const { legacyHtmlLanguages: _privateReader, ...read } = runtimeRead
+  const r = createRender(site)
+  const legacy = createHandlers(manifest, env, adapters, options.fetch ?? fetch, testPreview, options.testPreview?.now, options.testPreview?.buildId)
+  const features =
+    env.PLATFORM_URL && env.PAYLOAD_API_KEY && env.SITE_URL
+      ? createSiteFeatures({
+          env: {
+            PLATFORM_URL: env.PLATFORM_URL,
+            PAYLOAD_API_KEY: env.PAYLOAD_API_KEY,
+            SITE_URL: env.SITE_URL,
+          },
+          fetch: options.fetch,
+          ...options.features,
+        })
+      : undefined
+  const reserved = (request: Request) => {
+    try {
+      return /^\/api\/u90\/features(?:\/|$)/.test(decodeURIComponent(new URL(request.url).pathname))
+    } catch {
+      return true
+    }
+  }
+  const featureRequest = async (request: Request) => {
+    try {
+      const context = await testPreview.resolve(requestPreviewToken(request))
+      const gateway = context ? createSiteFeatures({ env: { PLATFORM_URL: context.platformOrigin, PAYLOAD_API_KEY: context.token, SITE_URL: context.siteOrigin }, fetch: options.fetch, ...options.features, visitorCookieName: context.visitorCookieName, testPreview: true }) : features
+      return gateway ? gateway[request.method === 'POST' ? 'POST' : 'GET'](request) : failure('unavailable')
+    } catch { return failure('forbidden') }
+  }
+  const handlers = {
+    GET: (request: Request, ctx: Parameters<typeof legacy.GET>[1]) => reserved(request) ? featureRequest(request) : legacy.GET(request, ctx),
+    POST: (request: Request, ctx: Parameters<typeof legacy.POST>[1]) => reserved(request) ? featureRequest(request) : legacy.POST(request, ctx),
+  }
+  return {
+    read,
+    /** Verified server-only context; never serialize its token into client props. */
+    testPreview: async () => testPreview.resolve((await adapters.draft()).token),
+    routes: createRoutes(site, runtimeRead, r, adapters, env.SITE_URL),
+    handlers,
+    render: r.render,
+    Blocks: r.Blocks,
+    Layout: r.Layout,
+    manifest,
+  }
+}
+export type U90 = ReturnType<typeof createU90>