@michaelthielemann/kestrel 1.2.1

package/layers/public/server/utils/publish/publisher.ts

@@ -0,0 +1,291 @@
+import { readdir, readFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+import { getTableColumns } from 'drizzle-orm'
+import type { StorageDriver } from '../../../../core/server/utils/storage'
+import { createLocalDriver } from '../../../../core/server/utils/storage.local'
+import { createS3Driver } from '../../../../core/server/utils/storage.s3'
+import { contentTypeFor, cacheControlFor, precompressedEncoding } from '../../../modules/deploy-output/deploy-output'
+import { localePath } from '../../../../core/app/utils/locale-path'
+import { pageRowHref } from '../../../../core/server/utils/page-route'
+import { withReadCapture } from '../../../../core/server/utils/read-capture'
+import { withResolveScope } from '../../../../core/server/utils/resolve-scope'
+import { runAsRenderer } from '../../../../access/server/utils/render-context'
+import { htmlKeyForRoute } from './route-keys'
+import { staleRoutes, type DepsStore } from './deps'
+import { recordPublishStatus, clearPublishStatus, renderOutcome } from './publish-status'
+import { routesToPrune, type Invalidation } from './invalidation'
+
+/**
+ * The runtime static publisher: renders public routes from the LIVE server (`localFetch`, the same
+ * handler `nuxt generate` uses) and writes them — plus the built `_nuxt` bundle + assets — through the
+ * configured output StorageDriver (local dir or S3). This is the engine the manual `publish:run` task
+ * and (later) the auto-trigger queue both drive. NOT unit-tested (needs a running build); the pure
+ * pieces it composes (route-keys, invalidation, deps, queue) are.
+ */
+
+interface OutputRc {
+  driver: 'local' | 's3'
+  dir: string
+  publicDir: string
+  auto: boolean
+  reconcileMinutes: number
+  verbose: boolean
+  s3: { bucket: string; region: string; endpoint: string; prefix: string; accessKeyId: string; secretAccessKey: string; sessionToken: string }
+}
+
+export function outputConfig(): OutputRc {
+  return (useRuntimeConfig().kestrel as { output: OutputRc }).output
+}
+
+/** Build the output driver from runtimeConfig (local dir or S3 bucket) — separate from the media driver. */
+export function outputDriver(cfg: OutputRc = outputConfig()): StorageDriver {
+  if (cfg.driver === 's3') {
+    return createS3Driver({
+      bucket: cfg.s3.bucket, region: cfg.s3.region, endpoint: cfg.s3.endpoint || undefined, prefix: cfg.s3.prefix,
+      publicBaseUrl: '', accessKeyId: cfg.s3.accessKeyId, secretAccessKey: cfg.s3.secretAccessKey, sessionToken: cfg.s3.sessionToken || undefined,
+    })
+  }
+  return createLocalDriver({ dir: cfg.dir, baseUrl: '/' })
+}
+
+/** Render a public route via the in-process server, returning its HTML buffer (200) or a null body with the
+ *  HTTP status, so the caller can tell a broken page (5xx — a server-error RESPONSE, not a throw) from an
+ *  expected non-200 (a draft / unpublish race → 404 / redirect). */
+export async function renderRoute(route: string): Promise<{ body: Buffer | null; status: number }> {
+  // Run as the renderer principal so the nested $fetch('/api/route') passes the access guard (it is not a
+  // public endpoint). The ALS context propagates through localFetch → the page render → the nested fetch.
+  // useNitroApp is imported LAZILY (not via the Nitro auto-import) on purpose: a static import gives this
+  // module an edge to nitropack's app.mjs, which both defines useNitroApp AND loads the plugin registry
+  // that reaches this file (via zz.publish) — a build-time circular dependency. A dynamic import is a chunk
+  // boundary, so that cycle disappears from the build graph; it's the same nitroApp singleton either way
+  // (Rollup bundles the literal specifier; useNitroApp is only CALLED here at publish time, long after boot).
+  const { useNitroApp } = await import('nitropack/runtime')
+  const res = await runAsRenderer(() => useNitroApp().localFetch(route, { method: 'GET', headers: { 'x-kestrel-publish': '1' } }))
+  if (res.status !== 200) return { body: null, status: res.status }
+  return { body: Buffer.from(await res.arrayBuffer()), status: res.status }
+}
+
+/** The enumerated published routes plus the collections whose query failed. `failed` is non-empty ⇒ the
+ *  route set is INCOMPLETE, so it must never be used as the authority for what to delete. */
+export interface PublishedRoutes {
+  routes: string[]
+  /** Names of collections whose route query threw (drifted schema, locked DB) — routes are missing. */
+  failed: string[]
+}
+
+/** Every published, publicly-readable page-like route (across collections) + the site root — the
+ *  runtime analogue of the prerender/sitemap route enumeration. noindex pages ARE published (real
+ *  reachable pages); only the sitemap omits them. */
+export function allPublishedRoutes(): PublishedRoutes {
+  const db = useDb()
+  const primary = primaryLocale()
+  const prefixPrimary = prefixPrimaryLocale()
+  const pub = publicReadableResources()
+  const routes = new Set<string>([localePath('/', primary, primary, prefixPrimary)]) // `/` or `/<primary>`
+  const failed: string[] = []
+  for (const c of allCollections()) {
+    if (!c.def.pageLike || !isPubliclyReadable(c.def.name, pub)) continue
+    // Project ONLY the columns the route rule + status gate need — never SELECT *, which would pull every
+    // row's block-content JSON (and every other field) into memory on each full publish just to read `path`.
+    // `locale` exists ONLY on a translatable collection (buildTable adds no locale column otherwise); a bare
+    // `cols.locale` would be undefined and make the select throw, dropping every one of this NON-translatable
+    // collection's live pages (then pruning them). Guard it exactly like findRouteConflict does.
+    const cols = getTableColumns(c.table) as Record<string, never>
+    const proj: Record<string, unknown> = { path: cols.path }
+    if (c.def.translatable) proj.locale = cols.locale
+    if (c.def.status) proj.status = cols.status
+    let rows: Record<string, unknown>[]
+    try { rows = db.select(proj as never).from(c.table).all() as Record<string, unknown>[] }
+    catch (error) {
+      // Report the gap instead of contributing zero routes: an unreadable collection is NOT an empty one,
+      // and a caller that can't tell them apart would treat every live page of it as stale.
+      failed.push(c.def.name)
+      console.error(`[kestrel] allPublishedRoutes: skipped collection ${c.def.name}:`, (error as Error)?.message ?? error)
+      continue
+    }
+    for (const row of rows) {
+      if (c.def.status && row.status !== 'published') continue
+      const route = pageRowHref(row, primary, prefixPrimary) // the shared (path, locale) → route rule
+      if (route) routes.add(route)
+    }
+  }
+  return { routes: [...routes], failed }
+}
+
+/** Render + write the given routes (skips non-200). When `deps` is given, each render is wrapped in a
+ *  read-capture and its data tags recorded, so a later write maps back to the routes it affects. */
+export async function publishRoutes(routes: string[], driver: StorageDriver, deps?: DepsStore): Promise<string[]> {
+  // One UNBUDGETED resolve scope for the whole run: a media/link/relation shared across pages resolves
+  // once per publish instead of once per embedding page (the runtime analogue of the generate build's
+  // memoDuringPrerender). Memo hits replay their read-tags, so each page's dep capture stays complete.
+  return withResolveScope(() => publishRoutesInScope(routes, driver, deps))
+}
+
+async function publishRoutesInScope(routes: string[], driver: StorageDriver, deps?: DepsStore): Promise<string[]> {
+  const written: string[] = []
+  const db = useDb()
+  const target = outputConfig().driver
+  for (const route of routes) {
+    try {
+      const { result, tags } = await withReadCapture(() => renderRoute(route))
+      const outcome = renderOutcome(result.status, !!result.body)
+      if (outcome === 'success') {
+        deps?.record(route, tags)
+        const key = htmlKeyForRoute(route)
+        await driver.put(key, result.body!, contentTypeFor(key), { cacheControl: cacheControlFor(key) })
+        written.push(route)
+        recordPublishStatus(db, route, { status: 'success', target })
+      } else if (outcome === 'error') {
+        // The page itself rendered to a server error (5xx) — a non-200 RESPONSE, not a thrown exception, so
+        // it never reaches the catch below. Record it so the editor ampel shows the failure; the
+        // previously-written file (if any) stays in place.
+        const message = `Render failed with HTTP ${result.status}`
+        recordPublishStatus(db, route, { status: 'error', error: message, target })
+        console.error(`[kestrel] publish failed for ${route}: ${message}`)
+      }
+      // outcome === 'skip': an expected non-200 (a draft / unpublish race) — leave the status untouched.
+    } catch (error) {
+      // Render or write (incl. S3 put) THREW for THIS route: record the outcome and carry on so one bad
+      // route doesn't abort the whole publish. The failure stays visible in the logs and the editor ampel.
+      const message = (error as Error)?.message ?? String(error)
+      recordPublishStatus(db, route, { status: 'error', error: message, target })
+      console.error(`[kestrel] publish failed for ${route}:`, message)
+    }
+  }
+  return written
+}
+
+/** Delete the given routes' static files (idempotent) — unpublish / delete / old-path prune. */
+export async function prunePages(routes: string[], driver: StorageDriver): Promise<void> {
+  // pruneEmptyDirs: a page is `<path>/index.html`, so removing it must also clear the now-empty `<path>/`.
+  const db = useDb()
+  for (const route of routes) {
+    await driver.delete(htmlKeyForRoute(route), { pruneEmptyDirs: true })
+    clearPublishStatus(db, route) // the file is gone → no live status (after the delete, so a failed delete keeps the row)
+  }
+}
+
+/** Render + write sitemap.xml, robots.txt and llms.txt (served at literal keys, not `<path>/index.html`). */
+async function publishMeta(driver: StorageDriver): Promise<void> {
+  for (const key of ['sitemap.xml', 'robots.txt', 'llms.txt']) {
+    const { body } = await renderRoute(`/${key}`)
+    if (body) await driver.put(key, body, contentTypeFor(key), { cacheControl: cacheControlFor(key) })
+  }
+}
+
+/** Mirror the built client bundle + static assets (`_nuxt/**`, favicon, fonts) into the output, but
+ *  NOT the build's stale `*.html`/sitemap/robots — those are rendered fresh from the live DB. */
+async function syncStaticAssets(driver: StorageDriver, publicDir: string): Promise<void> {
+  const walk = async (dir: string, prefix: string): Promise<void> => {
+    let entries
+    try { entries = await readdir(dir, { withFileTypes: true }) }
+    catch (error) {
+      // The root directory failing is a misconfig (missing/unreadable output.publicDir), not an empty
+      // tree — silently returning here means zero assets get synced while the render below still
+      // uploads fresh HTML referencing hashed `_nuxt/*` chunks that were never uploaded. A nested
+      // directory disappearing mid-walk is comparatively benign and stays silent.
+      if (!prefix) {
+        console.error(`[kestrel] output.publicDir "${dir}" is unreadable — publishing HTML without syncing _nuxt/assets: ${(error as Error)?.message ?? error}`)
+      }
+      return
+    }
+    const names = entries.map((s) => s.name)
+    for (const e of entries) {
+      const rel = prefix ? `${prefix}/${e.name}` : e.name
+      if (e.isDirectory()) { await walk(resolve(dir, e.name), rel); continue }
+      // Strip a precompressed `.br`/`.gz` suffix before the skip test: `index.html.br` is still the
+      // build's stale HTML (only content-negotiable, not literally named `*.html`) and must be excluded
+      // exactly like its uncompressed sibling, or it ships as a live sidecar for the fresh HTML rendered
+      // below — served to any Accept-Encoding-negotiating client instead of the page just published.
+      const base = rel.replace(/\.(?:br|gz)$/i, '')
+      if (!e.isFile() || base.endsWith('.html') || base === 'sitemap.xml' || base === 'robots.txt' || base === 'llms.txt') continue
+      const bytes = await readFile(resolve(dir, e.name))
+      // Tag a precompressed sibling (`.br`/`.gz` beside its base) with Content-Encoding so a proxy over S3
+      // serves it directly; a standalone archive stays unencoded so browsers don't decode + corrupt it.
+      const contentEncoding = precompressedEncoding(e.name, names)
+      await driver.put(rel, bytes, contentTypeFor(rel, !!contentEncoding), { cacheControl: cacheControlFor(rel), contentEncoding })
+    }
+  }
+  await walk(publicDir, '')
+}
+
+/** Full publish: sync `_nuxt`/assets first (so HTML never references not-yet-uploaded chunks), render
+ *  every published route + sitemap/robots, and prune routes that left the published set (unpublish /
+ *  delete / slug change) — tracked via the now-durable deps index, so a page unpublished/deleted while the
+ *  server was down is pruned on the next boot too. Targeted (only ever deletes routes this publisher wrote),
+ *  and skipped entirely when the published set could not be enumerated in full.
+ *
+ *  Deliberately NOT single-flighted: each caller brings its own driver and DepsStore, and folding a later
+ *  caller into a run already in progress would hand it that run's older route snapshot — an edit made
+ *  after the snapshot would never render and its deps would never be recorded. Serializing overlapping
+ *  triggers is the publish queue's job. */
+export async function publishFull(driver: StorageDriver = outputDriver(), deps?: DepsStore): Promise<{ rendered: number; pruned: number }> {
+  const cfg = outputConfig()
+  // Keep the registry read (`allPublishedRoutes` → `allCollections()`) AFTER this first `await`: on a
+  // boot publish it lets the synchronous Nitro plugin loop — including collections/01.register, which
+  // runs late (layer-then-filename order) — finish populating the registry first. Moving the read before
+  // an await would silently render an empty registry. See docs/architecture.md → "Server plugins".
+  await syncStaticAssets(driver, cfg.publicDir)
+  const { routes, failed } = allPublishedRoutes()
+  if (failed.length) {
+    // Keep on doubt: with a collection missing from the enumeration, every one of its live pages looks
+    // stale, so a prune would wipe it from the output. Rendering still proceeds — a stale extra file is
+    // recoverable, a deleted site is not.
+    console.error(`[kestrel] publish: prune skipped — routes of ${failed.join(', ')} could not be enumerated; existing files kept`)
+  }
+
+  // Targeted prune: a route we previously published that is no longer in the published set — a page
+  // unpublished, deleted, or whose slug changed — must lose its static file. Safe because it only deletes
+  // files this publisher wrote (tracked in deps, durable across restarts). Output ≡ DB; no opt-in toggle.
+  let pruned = 0
+  if (deps && !failed.length) {
+    const stale = staleRoutes(deps.routes(), routes)
+    if (stale.length) {
+      await prunePages(stale, driver)
+      for (const route of stale) deps.forget(route)
+      pruned = stale.length
+    }
+  }
+
+  // Reset the discovery accumulator so this full run reconciles ONLY what it actually renders — an earlier
+  // incremental (tag) publish also feeds the accumulator, and a variant it recorded whose usage was later
+  // removed would otherwise survive and be re-registered here (defeating usage-driven narrowing).
+  clearVariants()
+  const written = await publishRoutes(routes, driver, deps)
+  const rendered = written.length
+  await publishMeta(driver)
+  // Auto-discovery: a FULL render just visited every published route, so the capture accumulator now holds
+  // the complete set of variants actually used — reconcile it into the media_settings registry (scan entries
+  // replaced, manual/pinned kept). A partial (tag) publish must NOT do this: it would drop variants used only
+  // by the un-rendered routes. ONLY narrow when EVERY route rendered: a partial failure leaves the accumulator
+  // incomplete, so reconciling would deregister variants still referenced by the stale (kept) published HTML,
+  // which a later backfill would then delete out from under the live page. An un-enumerated collection is
+  // the same partial-coverage case: its pages were never visited, so their variants are missing too.
+  if (!failed.length && rendered === routes.length) saveDiscoveredVariants(useDb())
+  return { rendered, pruned }
+}
+
+/** Dispatch a coalesced invalidation from the queue: `full` → full publish; `tags` → re-render exactly
+ *  the affected routes (deps-matched ∪ explicit `render`) + prune the `prune` routes + regen sitemap/robots
+ *  (their `<lastmod>` may have changed). */
+export interface PublishResult { rendered: string[]; pruned: string[]; counts: { rendered: number; pruned: number } }
+
+export async function publishInvalidation(inv: Invalidation, driver: StorageDriver = outputDriver(), deps?: DepsStore): Promise<PublishResult> {
+  if (inv.type === 'noop') return { rendered: [], pruned: [], counts: { rendered: 0, pruned: 0 } }
+  if (inv.type === 'full') {
+    const r = await publishFull(driver, deps) // full: counts only (don't list every route)
+    return { rendered: [], pruned: [], counts: { rendered: r.rendered, pruned: r.pruned } }
+  }
+  const routes = [...new Set([...(deps?.routesForTags(inv.tags) ?? []), ...inv.render])]
+  const rendered = await publishRoutes(routes, driver, deps)
+  let pruned: string[] = []
+  // Never prune a route we just wrote live — render wins a coalesced render+prune collision (see routesToPrune).
+  const toPrune = routesToPrune(inv.prune, rendered)
+  if (toPrune.length) {
+    await prunePages(toPrune, driver)
+    for (const route of toPrune) deps?.forget(route)
+    pruned = toPrune
+  }
+  await publishMeta(driver)
+  return { rendered, pruned, counts: { rendered: rendered.length, pruned: pruned.length } }
+}

package/layers/public/server/utils/publish/queue.ts

@@ -0,0 +1,67 @@
+import type { Invalidation } from './invalidation'
+import { coalesce } from './coalesce'
+
+export interface PublishQueueOptions {
+  /** Dispatch a coalesced invalidation (full or tags). Rejections are caught + re-queued. */
+  run: (inv: Invalidation) => Promise<void>
+  /** Quiet window before a pending batch fires (default 3000ms). */
+  debounceMs?: number
+  /** Cap on how long a steady stream of writes can defer the flush (default 60000ms). */
+  maxWaitMs?: number
+  onError?: (error: unknown) => void
+}
+
+export interface PublishQueue {
+  /** Record an invalidation; a coalesced run fires after the quiet window. noop is ignored. */
+  enqueue: (inv: Invalidation) => void
+}
+
+/**
+ * Debounce + coalesce + single-flight queue for publish invalidations. A burst of content writes
+ * collapses to ONE run after a quiet window (capped by maxWait); only one run is in flight at a time,
+ * and anything enqueued mid-run defers to the next pass — so a publish always reflects the CURRENT DB
+ * state and converges (idempotent). A failed run re-queues its batch (never silently drops writes).
+ */
+export function createPublishQueue(opts: PublishQueueOptions): PublishQueue {
+  const debounceMs = opts.debounceMs ?? 3000
+  const maxWaitMs = opts.maxWaitMs ?? 60000
+  let pending: Invalidation[] = []
+  let timer: ReturnType<typeof setTimeout> | null = null
+  let firstAt = 0
+  let running = false
+
+  function arm() {
+    if (timer) clearTimeout(timer)
+    const now = Date.now()
+    if (!firstAt) firstAt = now
+    const wait = Math.max(0, Math.min(debounceMs, firstAt + maxWaitMs - now))
+    timer = setTimeout(flush, wait)
+  }
+
+  function flush() {
+    timer = null
+    firstAt = 0
+    if (running || pending.length === 0) return // a run is in flight; its finally() re-arms
+    const inv = coalesce(pending)
+    pending = []
+    if (inv.type === 'noop') return
+    running = true
+    void opts.run(inv)
+      .catch((error) => {
+        opts.onError?.(error)
+        pending.unshift(inv) // never drop a batch on failure — retry on the next pass
+      })
+      .finally(() => {
+        running = false
+        if (pending.length) arm()
+      })
+  }
+
+  function enqueue(inv: Invalidation) {
+    if (inv.type === 'noop') return
+    pending.push(inv)
+    if (!running) arm() // mid-run enqueues are collected; finally() re-arms once the run settles
+  }
+
+  return { enqueue }
+}

package/layers/public/server/utils/publish/route-for-record.ts

@@ -0,0 +1,16 @@
+import { pageRowHref } from '../../../../core/server/utils/page-route'
+
+/**
+ * The static route a page-like record publishes to, or null when it has none — a non-pageLike collection,
+ * or a row with no `path` (a blank slug, or no row at all). Adds the `pageLike` gate on top of the shared
+ * `pageRowHref` rule (the publish-status endpoint's null cases); the locale falls back to the primary for
+ * a row without one (non-translatable).
+ */
+export function routeForRecord(
+  row: { path?: unknown; locale?: unknown } | null | undefined,
+  pageLike: boolean,
+  primaryLocale: string,
+  prefixPrimary: boolean,
+): string | null {
+  return pageLike ? pageRowHref(row, primaryLocale, prefixPrimary) : null
+}

package/layers/public/server/utils/publish/route-keys.ts

@@ -0,0 +1,13 @@
+/**
+ * Map a public route to its static HTML file key, mirroring Nitro's prerender layout:
+ * `/` → `index.html`, `/about` → `about/index.html`, `/de/x` → `de/x/index.html`.
+ * Throws on a route that can't be a safe relative key (traversal `..`, query `?`, fragment `#`,
+ * or a backslash) so a bad path can never escape the output dir / S3 prefix.
+ */
+export function htmlKeyForRoute(route: string): string {
+  if (/[?#\\]/.test(route) || route.split('/').some((seg) => seg === '..')) {
+    throw new Error(`unsafe route for a static key: ${JSON.stringify(route)}`)
+  }
+  const trimmed = route.replace(/^\/+/, '').replace(/\/+$/, '')
+  return trimmed === '' ? 'index.html' : `${trimmed}/index.html`
+}

package/layers/public/server/utils/site-url.ts

@@ -0,0 +1,32 @@
+import { resolveServerKestrel, serverRuntimeConfig } from '../../../core/server/utils/server-config'
+import { normalizeBase } from './sitemap'
+
+/**
+ * Absolute site origin for emitted artifacts (sitemap `<loc>`, robots `Sitemap:`).
+ * Configured via `kestrel.siteUrl` (or `KESTREL_SITE_URL`); empty when unset, in which case callers
+ * fall back to relative paths and omit the robots `Sitemap:` directive.
+ */
+export function siteBaseUrl(): string {
+  // Prefer the siteUrl the kestrel module resolved from the consumer's `kestrel: {}` (via runtimeConfig);
+  // fall back to Kestrel's own config file + env for non-Nitro callers. Mirrors `useDb`'s db-path handling.
+  const fromRc = serverRuntimeConfig()?.kestrel as { siteUrl?: string } | undefined
+  return normalizeBase(fromRc?.siteUrl ?? resolveServerKestrel().siteUrl)
+}
+
+/** Human site name for `llms.txt` — config/env, else the siteUrl host, else 'Website'. */
+export function siteName(): string {
+  const fromRc = serverRuntimeConfig()?.kestrel as { siteName?: string } | undefined
+  const name = (fromRc?.siteName ?? resolveServerKestrel().siteName)?.trim()
+  if (name) return name
+  const base = siteBaseUrl()
+  if (base) {
+    try { return new URL(base).host } catch { /* not a parseable URL — fall through */ }
+  }
+  return 'Website'
+}
+
+/** One-line site description for `llms.txt` (empty when unset). */
+export function siteDescription(): string {
+  const fromRc = serverRuntimeConfig()?.kestrel as { siteDescription?: string } | undefined
+  return (fromRc?.siteDescription ?? resolveServerKestrel().siteDescription ?? '').trim()
+}

package/layers/public/server/utils/sitemap.ts

@@ -0,0 +1,97 @@
+export interface SitemapAlternate {
+  hreflang: string
+  href: string
+}
+
+export interface SitemapEntry {
+  loc: string
+  lastmod?: string
+  alternates?: SitemapAlternate[]
+}
+
+/** A page-like row reduced to what the sitemap needs, before grouping translations into hreflang sets. */
+export interface SitemapCandidate {
+  loc: string
+  lastmod?: string
+  locale: string
+  /** The translation-group key, or null/undefined for rows that have no localized siblings. */
+  group?: string | null
+}
+
+/** Drop any trailing slashes from a site base URL so `base + path` never doubles up. */
+export function normalizeBase(base: string): string {
+  return base.replace(/\/+$/, '')
+}
+
+function xmlEscape(value: string): string {
+  return value
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;')
+}
+
+/**
+ * Group page-like candidates into `<url>` entries, attaching the hreflang alternate set to every
+ * member of a multi-locale translation group. Pure: the route feeds it published+indexable rows only,
+ * so alternates never advertise a draft/noindex variant. Order is preserved (the route sorts after).
+ * A group of one (or a row with no group) gets no alternates — hreflang is meaningless for a lone page.
+ * `x-default` points at the primary-locale variant when that variant is part of the group.
+ */
+export function withHreflang(candidates: SitemapCandidate[], primaryLocale: string): SitemapEntry[] {
+  const groups = new Map<string, SitemapCandidate[]>()
+  for (const c of candidates) {
+    if (c.group == null) continue
+    const arr = groups.get(c.group)
+    if (arr) arr.push(c)
+    else groups.set(c.group, [c])
+  }
+
+  return candidates.map((c) => {
+    const entry: SitemapEntry = { loc: c.loc }
+    if (c.lastmod) entry.lastmod = c.lastmod
+    const variants = c.group != null ? groups.get(c.group)! : []
+    if (variants.length >= 2) entry.alternates = buildAlternates(variants, primaryLocale)
+    return entry
+  })
+}
+
+/** Sorted-by-locale alternate links for a group, plus an `x-default` to the primary variant if present. */
+function buildAlternates(variants: SitemapCandidate[], primaryLocale: string): SitemapAlternate[] {
+  const sorted = [...variants].sort((a, b) => a.locale.localeCompare(b.locale))
+  const seen = new Set<string>()
+  const alternates: SitemapAlternate[] = []
+  for (const v of sorted) {
+    if (seen.has(v.locale)) continue
+    seen.add(v.locale)
+    alternates.push({ hreflang: v.locale, href: v.loc })
+  }
+  const primary = sorted.find((v) => v.locale === primaryLocale)
+  if (primary) alternates.push({ hreflang: 'x-default', href: primary.loc })
+  return alternates
+}
+
+export function buildSitemap(entries: SitemapEntry[]): string {
+  const hasAlternates = entries.some((e) => e.alternates && e.alternates.length > 0)
+  const xhtmlNs = hasAlternates ? ' xmlns:xhtml="http://www.w3.org/1999/xhtml"' : ''
+  const urls = entries
+    .map((e) => {
+      const lastmod = e.lastmod ? `<lastmod>${xmlEscape(e.lastmod)}</lastmod>` : ''
+      const links = (e.alternates ?? [])
+        .map((a) => `<xhtml:link rel="alternate" hreflang="${xmlEscape(a.hreflang)}" href="${xmlEscape(a.href)}"/>`)
+        .join('')
+      return `<url><loc>${xmlEscape(e.loc)}</loc>${lastmod}${links}</url>`
+    })
+    .join('')
+  return `<?xml version="1.0" encoding="UTF-8"?><urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"${xhtmlNs}>${urls}</urlset>`
+}
+
+export function buildRobots(opts: { sitemapUrl?: string; llmsUrl?: string } = {}): string {
+  const lines = ['User-agent: *', 'Allow: /']
+  // A comment (robots.txt has no standard llms directive) so crawlers that read robots also find the
+  // agent-oriented site map at /llms.txt. Kept above the blank-line-separated Sitemap directive.
+  if (opts.llmsUrl) lines.push(`# llms.txt: ${opts.llmsUrl}`)
+  if (opts.sitemapUrl) lines.push('', `Sitemap: ${opts.sitemapUrl}`)
+  return `${lines.join('\n')}\n`
+}

package/layers/ui/app/assets/scss/_base.scss

@@ -0,0 +1,16 @@
+body {
+  font-family: var(--font-sans);
+  font-size: var(--text-base);
+  color: var(--color-text);
+  background: var(--color-bg);
+}
+
+a {
+  color: var(--color-primary);
+}
+
+/* Opt-in reading measure for form-heavy pages inside the now full-bleed admin shell. */
+.u-measure {
+  max-width: var(--content-measure);
+  margin-inline: auto;
+}

package/layers/ui/app/assets/scss/_datepicker.scss

@@ -0,0 +1,82 @@
+@use 'mixins' as *;
+
+// Shared chrome for the date pickers. The calendar popover is teleported to <body> by Reka, so these
+// must stay GLOBAL (non-scoped) — a `scoped` block would silently drop them. Both DatePicker and
+// DateRangePicker @include this so neither silently borrows the other's styles (`__sep` is only used
+// by the range variant, the rest by both).
+@mixin ui-datepicker {
+  .ui-datepicker {
+    &__field {
+      display: inline-flex;
+      align-items: center;
+      gap: 1px;
+      padding: var(--space-2) var(--space-3);
+      border: 1px solid var(--color-control-border, var(--color-border));
+      border-radius: var(--radius-md);
+      background: var(--color-surface);
+
+      &[aria-invalid='true'] { border-color: var(--color-danger); }
+    }
+    &__segment {
+      @include focus-ring;
+      padding: 0 1px;
+      border-radius: var(--radius-sm);
+
+      &[data-placeholder] { color: var(--color-text-muted); }
+      // The fill alone can't tell a keyboard user which segment the arrow keys will change (reka hides
+      // the caret), so the ring has to survive it — only pointer focus drops the outline.
+      &:focus { background: var(--color-active); color: var(--color-text); }
+      &:focus:not(:focus-visible) { outline: none; }
+    }
+    &__sep { margin: 0 var(--space-2); color: var(--color-text-muted); }
+    &__trigger {
+      @include focus-ring;
+      margin-inline-start: var(--space-2);
+      border: 0;
+      background: transparent;
+      cursor: pointer;
+    }
+    &__content {
+      background: var(--color-surface);
+      border: 1px solid var(--color-border);
+      border-radius: var(--radius-md);
+      box-shadow: var(--shadow-md);
+      padding: var(--space-3);
+      z-index: var(--z-dropdown);
+    }
+    &__header {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      margin-bottom: var(--space-2);
+    }
+    &__nav {
+      @include focus-ring;
+      border: 0;
+      background: transparent;
+      cursor: pointer;
+      font-size: var(--text-lg);
+      padding: 0 var(--space-2);
+    }
+    &__heading { font-weight: var(--weight-medium); font-size: var(--text-sm); }
+    &__weekday { font-size: var(--text-sm); color: var(--color-text-muted); padding: var(--space-1); font-weight: var(--weight-normal); }
+    &__cell {
+      @include focus-ring;
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      width: 2rem;
+      height: 2rem;
+      border: 0;
+      border-radius: var(--radius-sm);
+      background: transparent;
+      color: var(--color-text);
+      cursor: pointer;
+
+      &[data-today] { font-weight: var(--weight-bold); }
+      &[data-selected] { background: var(--color-primary); color: var(--color-on-primary); }
+      &[data-outside-view] { color: var(--color-text-muted); }
+      &[data-disabled] { opacity: 0.4; cursor: not-allowed; }
+    }
+  }
+}