@michaelthielemann/kestrel 1.6.0 → 2.0.0

package/layers/fields/server/field-registry/sanitize.ts

@@ -1,16 +1,19 @@
 import sanitizeHtml from 'sanitize-html'
 import { RICHTEXT_LINK_SCHEME } from '../../app/utils/richtext-links'
 
+// Kept deliberately in step with the editor's schema (`ui/Richtext.vue`): a tag allowed here that no
+// extension can parse is not "supported", it is a delayed deletion — the editor drops it on load and the
+// next save persists the loss. `richtext.dom.test.ts` asserts the two lists agree, so widening this one
+// means teaching the editor the tag in the same change. Images belong in a media field or an image
+// block, not in flow text; tables await an editor that can hold them.
 export const RICHTEXT_ALLOWLIST: sanitizeHtml.IOptions = {
   allowedTags: [
     'p', 'br', 'span', 'strong', 'b', 'em', 'i', 'u', 's', 'sub', 'sup', 'mark',
     'blockquote', 'pre', 'code', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
-    'ul', 'ol', 'li', 'a', 'img', 'figure', 'figcaption', 'hr',
-    'table', 'thead', 'tbody', 'tfoot', 'tr', 'th', 'td',
+    'ul', 'ol', 'li', 'a', 'hr',
   ],
   allowedAttributes: {
     a: ['href', 'title', 'target', 'rel'],
-    img: ['src', 'alt', 'title', 'width', 'height', 'loading'],
     '*': ['class', 'style'],
   },
   allowedStyles: {

package/layers/media/app/components/MediaLibrary.vue

@@ -82,7 +82,8 @@ function onSelect(item: LibraryItem, mods: { toggle: boolean; range: boolean })
   if (props.pick && props.multiple) {
     if (item.type !== 'file') return
     const s = new Set(picked.value)
-    s.has(item.file.id) ? s.delete(item.file.id) : s.add(item.file.id)
+    if (s.has(item.file.id)) s.delete(item.file.id)
+    else s.add(item.file.id)
     picked.value = s
     return
   }
@@ -288,6 +289,7 @@ const localizedMenu = computed(() => menuItems.value.map((s) => ({
 </script>
 
 <template>
+  <!-- eslint-disable-next-line vuejs-accessibility/click-events-have-key-events, vuejs-accessibility/no-static-element-interactions -- @click.self clears selection as a mouse-only bulk convenience; Space-toggle on each MediaGrid/MediaTable item already gives keyboard users the same end state -->
   <section class="media-library" @click.self="lib.clear()" @dragenter="onDragEnter" @dragover="onDragOver" @dragleave="onDragLeave" @drop="onDrop">
     <MediaPathBar :folder="folder" @navigate="lib.navigate" />
     <MediaToolbar
@@ -301,6 +303,7 @@ const localizedMenu = computed(() => menuItems.value.map((s) => ({
     />
     <UiMenu :items="localizedMenu" @select="onMenuSelect">
       <!-- @contextmenu.capture sets the menu target before Reka's own handler opens the menu, so menuItems is correct when the menu renders -->
+      <!-- eslint-disable-next-line vuejs-accessibility/no-static-element-interactions -- contextmenu fires natively via Shift+F10/the Menu key when a MediaGrid/MediaTable item has focus, so this capture handler is already keyboard-reachable -->
       <div class="media-library__items" @contextmenu.capture="onContextMenu">
         <UiAlert v-if="error" variant="error">{{ error }}</UiAlert>
         <p v-else-if="!loading && !items.length" class="media-library__empty">{{ t('media.folderEmpty') }}</p>

package/layers/media/app/components/MediaToolbar.vue

@@ -47,7 +47,7 @@ function onFiles(e: Event) {
     <div class="media-toolbar__actions">
       <UiButtonGroup v-model="viewModel" :options="VIEW_OPTIONS" :aria-label="t('mediaToolbar.viewAriaLabel')" />
       <span class="media-toolbar__divider" aria-hidden="true"></span>
-      <input ref="fileInput" type="file" multiple class="media-toolbar__file" @change="onFiles" />
+      <input ref="fileInput" type="file" multiple class="media-toolbar__file" :aria-label="t('mediaToolbar.upload')" @change="onFiles" />
       <UiButton :disabled="disabled" @click="fileInput?.click()"><UiIcon name="upload" :size="16" /> {{ t('mediaToolbar.upload') }}</UiButton>
       <UiButton :disabled="disabled" @click="emit('new-folder')"><UiIcon name="folder-plus" :size="16" /> {{ t('mediaToolbar.newFolder') }}</UiButton>
     </div>

package/layers/media/app/components/field/Media.vue

@@ -117,7 +117,9 @@ defineExpose({ onConfirm, removeId, onDragStart, onDrop, moveItem })
   <UiField :id="id" :label="name" :error="error" :required="required">
     <template #default="f">
       <div class="field-media">
+        <!-- eslint-disable-next-line vuejs-accessibility/no-static-element-interactions -- @dragleave is a mouse-only progressive enhancement; the move-earlier/move-later buttons below give the same reorder fully keyboard access -->
         <ul v-if="resolved.length" ref="itemsEl" class="field-media__items" @dragleave="onDragLeave">
+          <!-- eslint-disable-next-line vuejs-accessibility/no-static-element-interactions -- drag handlers are a mouse-only progressive enhancement; the move-earlier/move-later buttons below give the same reorder fully keyboard access -->
           <li
             v-for="(r, i) in resolved"
             :key="r.id"

package/layers/media/app/composables/useMediaLibrary.ts

@@ -119,7 +119,8 @@ export function useMediaLibrary(opts: { urlSync?: boolean; accept?: 'image' | 'a
   function select(item: LibraryItem) { const k = itemKey(item); selected.value = new Set([k]); anchorKey = k }
   function toggle(item: LibraryItem) {
     const k = itemKey(item); const s = new Set(selected.value)
-    s.has(k) ? s.delete(k) : s.add(k)
+    if (s.has(k)) s.delete(k)
+    else s.add(k)
     selected.value = s; anchorKey = k
   }
   function range(item: LibraryItem) { selected.value = computeRange(orderedKeys.value, anchorKey ?? itemKey(item), itemKey(item), selected.value) }

package/layers/media/server/utils/backfill.ts

@@ -5,7 +5,7 @@ import type { StorageDriver } from '../../../core/server/utils/storage'
 import { media } from '../collections/media'
 import { deriveImage, RASTER } from './derive'
 import { derivativeKey, type DerivativeManifest } from './record'
-import { activeVariants } from './variants'
+import { readVariantRegistry, resolveActiveVariants } from './variants'
 import { withLock, mediaLockKey } from '../../../core/server/utils/key-lock'
 import { emitMediaWrite } from './media-write'
 
@@ -16,7 +16,8 @@ const MEDIA_CACHE_CONTROL = 'public, max-age=31536000'
 export interface BackfillPlan {
   /** Specs, each carrying ONLY its missing formats, to derive + add. */
   missing: ResolvedVariant[]
-  /** Object keys of manifest entries no longer in the active set (deregistered) — to prune. */
+  /** Object keys of manifest entries no longer in the active set (deregistered) — to prune. Always empty
+   *  when the caller passes `prune: false`, i.e. the active set is a fallback rather than the registry. */
   orphanKeys: string[]
 }
 
@@ -26,7 +27,9 @@ export interface BackfillPlan {
  * never be satisfied). Orphans are keyed per `<name>.<format>`, so a deregistered FORMAT of a still-active
  * name is pruned too.
  */
-export function planBackfill(row: { width: number | null; derivatives: DerivativeManifest | null }, specs: ResolvedVariant[]): BackfillPlan {
+export function planBackfill(
+  row: { width: number | null; derivatives: DerivativeManifest | null }, specs: ResolvedVariant[], prune = true,
+): BackfillPlan {
   const manifest = row.derivatives ?? {}
   const activeKeys = new Set<string>()
   const missing: ResolvedVariant[] = []
@@ -40,7 +43,7 @@ export function planBackfill(row: { width: number | null; derivatives: Derivativ
     if (missingFormats.length) missing.push({ ...spec, formats: missingFormats })
   }
   const orphanKeys: string[] = []
-  for (const [k, entry] of Object.entries(manifest)) if (!activeKeys.has(k) && entry.key) orphanKeys.push(entry.key)
+  if (prune) for (const [k, entry] of Object.entries(manifest)) if (!activeKeys.has(k) && entry.key) orphanKeys.push(entry.key)
   return { missing, orphanKeys }
 }
 
@@ -53,9 +56,9 @@ interface BackfillRow { id: number; storageKey: string; mime: string; width: num
  * (that is Slice 9's published-media GC, a different concern).
  */
 export async function backfillRow(
-  db: BetterSQLite3Database, driver: StorageDriver, row: BackfillRow, specs: ResolvedVariant[], policy: ResolvedImagePolicy,
+  db: BetterSQLite3Database, driver: StorageDriver, row: BackfillRow, specs: ResolvedVariant[], policy: ResolvedImagePolicy, prune = true,
 ): Promise<{ generated: number; pruned: number }> {
-  const plan = planBackfill(row, specs)
+  const plan = planBackfill(row, specs, prune)
   if (!plan.missing.length && !plan.orphanKeys.length) return { generated: 0, pruned: 0 }
 
   const orphaned = new Set(plan.orphanKeys)
@@ -84,7 +87,12 @@ export async function backfillRow(
   return { generated, pruned: plan.orphanKeys.length }
 }
 
-export interface BackfillReport { rows: number; rowsChanged: number; generated: number; pruned: number; check: boolean }
+export interface BackfillReport {
+  rows: number; rowsChanged: number; generated: number; pruned: number; check: boolean
+  /** The run declined to prune because the active set is the config fallback, not the registry — so a
+   *  `pruned: 0` here means "could not tell what is registered", not "nothing was deregistered". */
+  pruneWithheld: boolean
+}
 
 /**
  * Iterate every raster media row, reconciling each to the active variant set. Sequential (sharp CPU + a
@@ -94,14 +102,18 @@ export interface BackfillReport { rows: number; rowsChanged: number; generated:
 export async function runBackfill(
   db: BetterSQLite3Database, driver: StorageDriver, policy: ResolvedImagePolicy, opts: { check?: boolean } = {},
 ): Promise<BackfillReport> {
-  const specs = activeVariants(db, policy.variants, policy.presets)
+  // Deriving a superset is harmless, deleting against one is not, so the prune follows the resolver's own
+  // verdict: an unmigrated, unreadable, empty or wholly-rejected registry resolves to the CONFIG fallback,
+  // under which every registered variant of every row looks deregistered.
+  const { specs, fromRegistry: prune } = resolveActiveVariants(readVariantRegistry(db), policy.variants, policy.presets)
+  if (!prune) console.warn('[kestrel] backfill: no usable variant registry — generating against the config fallback and withholding the prune. Run a full publish so the prerender scan populates media_settings.')
   const rows = db.select().from(media).all() as BackfillRow[]
-  const report: BackfillReport = { rows: rows.length, rowsChanged: 0, generated: 0, pruned: 0, check: !!opts.check }
+  const report: BackfillReport = { rows: rows.length, rowsChanged: 0, generated: 0, pruned: 0, check: !!opts.check, pruneWithheld: !prune }
   for (const snapshot of rows) {
     if (!RASTER.has(snapshot.mime)) continue
     if (opts.check) {
       // Dry-run reads only (against the snapshot) — no mutation, so no lock.
-      const plan = planBackfill(snapshot, specs)
+      const plan = planBackfill(snapshot, specs, prune)
       const toGenerate = plan.missing.reduce((n, s) => n + s.formats.length, 0)
       if (!toGenerate && !plan.orphanKeys.length) continue
       report.rowsChanged++
@@ -116,11 +128,11 @@ export async function runBackfill(
       const cols = getTableColumns(media) as Record<string, never>
       const row = db.select().from(media).where(eq(cols.id, snapshot.id)).get() as BackfillRow | undefined
       if (!row || !RASTER.has(row.mime)) return
-      const plan = planBackfill(row, specs)
+      const plan = planBackfill(row, specs, prune)
       if (!plan.missing.length && !plan.orphanKeys.length) return
       report.rowsChanged++
       try {
-        const r = await backfillRow(db, driver, row, specs, policy)
+        const r = await backfillRow(db, driver, row, specs, policy, prune)
         report.generated += r.generated
         report.pruned += r.pruned
       } catch (error) {

package/layers/media/server/utils/variants.ts

@@ -28,11 +28,16 @@ const rank = (v: StoredVariant): number => (v.pinned || v.source === 'manual' ?
  * config policy variants) when the registry is empty/absent. `presets` are config-authored named variants
  * (`image.variants`): explicit, name-referenced declarations that are never scan-discovered, so they stay
  * active through usage-driven narrowing (unioned into a non-empty registry, winning any name collision).
+ *
+ * `fromRegistry` is the verdict a DELETING caller (the backfill prune) must gate on: true only when at least
+ * one stored entry SURVIVED validation, so the set really is the registered one. Absent, unread, empty and
+ * wholly-rejected registries all resolve to the same superset fallback, under which every registered
+ * derivative looks deregistered — the row count alone cannot tell those apart from a narrowed set.
  * Pure — the load-bearing logic, unit-tested without a DB.
  */
 export function resolveActiveVariants(
   stored: StoredVariant[] | null | undefined, fallback: ResolvedVariant[], presets: ResolvedVariant[] = [],
-): ResolvedVariant[] {
+): { specs: ResolvedVariant[]; fromRegistry: boolean } {
   // A registry row is hand-authorable via the media_settings JSON PATCH; reject a name outside the
   // derivative-key charset ([A-Za-z0-9_-]) — an out-of-charset char breaks the URL / the prune-media
   // referencedKeys regex (its derivative is pruned though pages reference it) and a `/` nests a pseudo-folder.
@@ -41,7 +46,7 @@ export function resolveActiveVariants(
     (v): v is StoredVariant => !!v && safeName(v.name) && Number.isFinite(v.width) && v.width >= 1,
   )
   // Empty registry ⇒ the fallback already contains the presets (resolveVariants unions them), so return it as-is.
-  if (!list.length) return fallback
+  if (!list.length) return { specs: fallback, fromRegistry: false }
   const byName = new Map<string, StoredVariant>()
   for (const v of list) {
     const prev = byName.get(v.name)
@@ -50,7 +55,7 @@ export function resolveActiveVariants(
   for (const p of presets) {
     if (p && typeof p.name === 'string' && p.name !== '' && Number.isFinite(p.width) && p.width >= 1) byName.set(p.name, { ...p, source: 'manual' })
   }
-  return [...byName.values()].map((v): ResolvedVariant => ({
+  const specs = [...byName.values()].map((v): ResolvedVariant => ({
     name: v.name,
     width: Math.floor(v.width),
     // coerce a garbage/stale height to null so it never reaches sharp's crop resize and 500s the upload
@@ -62,6 +67,7 @@ export function resolveActiveVariants(
     position: typeof v.position === 'string' && SHARP_POSITIONS.has(v.position) ? v.position : 'centre',
     formats: v.formats?.length ? v.formats : ['webp'],
   }))
+  return { specs, fromRegistry: true }
 }
 
 /**
@@ -87,12 +93,12 @@ export function reconcileVariants(existing: StoredVariant[], discovered: Resolve
 }
 
 /**
- * Read the persisted variant registry (the `media_settings` singleton) and resolve the active set,
- * falling back to `fallback` (the resolved config policy variants) when nothing is stored yet. `presets`
- * (config-authored named variants) stay active regardless of the stored set. The upload path calls this
- * so it derives exactly the currently-registered set + presets (narrow generation).
+ * The raw stored registry rows (the `media_settings` singleton), or `null` when there are none to resolve
+ * from — the read threw (media_settings not migrated) or nothing is stored. Whether the resolved set may be
+ * DELETED against is not decidable here: that is `resolveActiveVariants`' `fromRegistry` verdict, which only
+ * a validation pass over these rows can give.
  */
-export function activeVariants(db: BetterSQLite3Database, fallback: ResolvedVariant[], presets: ResolvedVariant[] = []): ResolvedVariant[] {
+export function readVariantRegistry(db: BetterSQLite3Database): StoredVariant[] | null {
   const cols = getTableColumns(mediaSettings) as Record<string, never>
   let row: { variants?: StoredVariant[] | null } | undefined
   try {
@@ -100,9 +106,18 @@ export function activeVariants(db: BetterSQLite3Database, fallback: ResolvedVari
       | { variants?: StoredVariant[] | null }
       | undefined
   } catch {
-    // media_settings not migrated yet (a DB provisioned by committed migrations alone) — degrade to the
-    // config fallback rather than 500 the upload. Mirrors attachDeadRefs tolerating a missing record_refs.
-    row = undefined
+    return null
   }
-  return resolveActiveVariants(row?.variants ?? null, fallback, presets)
+  const stored = row?.variants
+  return Array.isArray(stored) ? stored : null
+}
+
+/**
+ * Resolves the active variant set for the upload path (narrow generation: registered set + presets).
+ * Deliberately forgiving: an unreadable registry degrades to the config fallback rather than 500 the
+ * upload (mirrors attachDeadRefs tolerating a missing record_refs). Discards `fromRegistry` — never use
+ * this to decide what may be pruned; a deleting caller needs `resolveActiveVariants` directly.
+ */
+export function activeVariants(db: BetterSQLite3Database, fallback: ResolvedVariant[], presets: ResolvedVariant[] = []): ResolvedVariant[] {
+  return resolveActiveVariants(readVariantRegistry(db), fallback, presets).specs
 }

package/layers/public/app/pages/[...slug].vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import type { LayoutKey } from 'nuxt/app'
+import type { LayoutKey } from '#app'
 import type { SiteHead } from '../utils/site-head'
 
 // The record decides its own layout, so route-meta resolution is opted out of and this page renders the
@@ -35,7 +35,7 @@ const { locale, path } = resolvePublicRoute(route.path.split('/').filter(Boolean
 // `/api/route` and a draft renders at its real URL (the live preview); anonymous + the static render
 // stay published-only (the handler enforces it).
 const requestFetch = useRequestFetch()
-const { data: resolved } = await useAsyncData(`page:${locale}:${path}`, () =>
+const { data: resolved, error: resolveError } = await useAsyncData(`page:${locale}:${path}`, () =>
   requestFetch('/api/route', {
     query: { path, locale },
   }).then((r) => r as {
@@ -45,7 +45,20 @@ const { data: resolved } = await useAsyncData(`page:${locale}:${path}`, () =>
     site?: SiteHead | null
   }),
 )
-const page = computed(() => resolved.value?.page ?? null)
+// Ticket preview (ADR-0008): `?kestrel-preview-token=…` carries the editor's UNSAVED state, so an external
+// tab can show work in progress without a save and without publishing. The ticket is admin-only and
+// session-bound server-side; an expired/foreign/unknown one reads as null and the saved record renders.
+const previewToken = route.query[PREVIEW_TOKEN_QUERY]
+const { data: ticket } = typeof previewToken === 'string' && previewToken
+  ? await useAsyncData(`kestrel-preview-ticket:${previewToken}`, () =>
+      requestFetch('/api/preview', { query: { token: previewToken } })
+        .then((r) => r as { payload?: { values?: Record<string, unknown> } } | null)
+        .catch(() => null))
+  : { data: ref<{ payload?: { values?: Record<string, unknown> } } | null>(null) }
+const previewValues = computed(() => ticket.value?.payload?.values ?? null)
+const previewingTicket = computed(() => previewValues.value !== null)
+
+const page = computed(() => previewPage(resolved.value?.page ?? null, previewValues.value) as (RenderedPage & Record<string, unknown>) | null)
 // `fallback` below only rescues a truthy name that is missing from the layout map, so the empty cases have
 // to be coalesced here — see resolvePageLayout. The cast is the one honest bridge in this file: the stored
 // name is arbitrary editor data, while `NuxtLayout` types `name` as the union of layouts that existed at
@@ -60,7 +73,7 @@ const pageState = usePublicPageState()
 watchEffect(() => {
   pageState.value = {
     collection: resolved.value?.collection ?? null,
-    page: resolved.value?.page ?? null,
+    page: page.value,
   }
 })
 
@@ -68,6 +81,13 @@ watchEffect(() => {
 // published-only), so its presence is an unambiguous "you are previewing an unpublished page" signal.
 const isDraftPreview = computed(() => page.value?.status === 'draft')
 
+// What this tab is actually showing, when it is not the live page. A ticket outranks the draft notice: the
+// content on screen was never saved at all, which is the stronger caveat.
+const previewNotice = computed(() => {
+  if (previewingTicket.value) return 'Preview — unsaved changes, not published'
+  return isDraftPreview.value ? 'Draft preview — not published' : ''
+})
+
 // Editor live-preview mode: `?kestrel-preview=1` AND an authenticated admin session. The session is
 // checked server-side (cookies forwarded, same seam as the draft fetch above) so SSR and hydration
 // agree on which branch renders; an anonymous visitor with the query param gets the normal page.
@@ -79,6 +99,13 @@ const { data: previewSession } = previewRequested
   : { data: ref<{ authenticated: boolean } | null>(null) }
 const previewActive = computed(() => previewRequested && previewSession.value?.authenticated === true)
 
+// `useAsyncData` resolves even when the fetch threw, so the resolver's own failure has to be re-raised here
+// or the root's empty document (a 200 WITH a body) reads as a successful render and the publisher bakes it
+// over the live page. Unconditional on purpose, not just for `/`: on any other path the failure would fall
+// through to the 404 below, which asserts "no such page" from a lookup that never completed — a claim
+// crawlers and caches act on, and one the publisher files as a skip instead of the error the editor shows.
+if (resolveError.value) throw resolveError.value
+
 // The site root stays reachable (empty document) before a home page is published;
 // any other unmatched path is a genuine 404.
 if (!page.value && path !== '/') throw createError({ statusCode: 404, statusMessage: 'Page not found' })
@@ -122,7 +149,8 @@ useHead({
 useSeoMeta({
   title: documentTitle,
   description: fallbacks.description,
-  robots: seo.noindex ? 'noindex, nofollow' : undefined,
+  // A ticket preview is unsaved content at a real URL — never indexable, whatever the record's own SEO says.
+  robots: previewingTicket.value || seo.noindex ? 'noindex, nofollow' : undefined,
   ogTitle: head.meta.ogTitle,
   ogDescription: head.meta.ogDescription,
   ogUrl: head.meta.ogUrl,
@@ -141,9 +169,9 @@ useSeoMeta({
       <!-- Only ever shown to an authenticated admin previewing an unpublished page (drafts never resolve
            for anonymous visitors or the static render), so it never ships to the public/static site.
            Suppressed inside the editor preview iframe — the editor's own status ampel covers it. -->
-      <div v-if="isDraftPreview && !previewActive" class="kestrel-draft-badge" role="status">
+      <div v-if="previewNotice && !previewActive" class="kestrel-draft-badge" role="status">
         <span class="kestrel-draft-badge__dot" aria-hidden="true" />
-        Draft preview — not published
+        {{ previewNotice }}
       </div>
       <!-- Editor preview: the bridge swaps in the editor's live (unsaved) tree over postMessage and makes
            blocks selectable; the saved content renders until the first message. Normal path unchanged. -->

package/layers/public/app/pages/__kestrel/preview.vue

@@ -3,8 +3,10 @@
  * Dedicated editor live-preview page for records WITHOUT a public URL — a new/unsaved record, a blank
  * slug, or a blocks-enabled non-pageLike collection. It renders the real public app (default layout,
  * the consumer's CSS/fonts/breakpoints) around an empty BlockRenderer that the editor fills over the
- * postMessage bridge. Saved pageLike records preview at their REAL URL instead (higher fidelity);
- * this page is the graceful fallback so previews never regress to "save first".
+ * postMessage bridge — or, when opened in a separate tab with `?kestrel-preview-token=…`, around the
+ * ticket's unsaved content (ADR-0008), since a tab with no parent window has no bridge to listen to.
+ * Saved pageLike records preview at their REAL URL instead (higher fidelity); this page is the graceful
+ * fallback so previews never regress to "save first".
  *
  * Admin-gated server-side: `useRequestFetch` forwards the incoming cookies to `/api/auth/session`
  * (the same seam the catch-all uses for draft rendering), and anonymous requests get a 404 — the
@@ -20,6 +22,16 @@ if (!session.value?.authenticated) throw createError({ statusCode: 404, statusMe
 // Content locale from the editor (drives <html lang> for faithful per-locale rendering).
 const route = useRoute()
 const lang = typeof route.query.locale === 'string' && route.query.locale ? route.query.locale : undefined
+
+// Ticket content for the external-tab case; null (→ the bridge's own empty tree) without one.
+const token = route.query[PREVIEW_TOKEN_QUERY]
+const { data: ticket } = typeof token === 'string' && token
+  ? await useAsyncData(`kestrel-preview-ticket:${token}`, () =>
+      requestFetch('/api/preview', { query: { token } })
+        .then((r) => r as { payload?: { values?: Record<string, unknown> } } | null)
+        .catch(() => null))
+  : { data: ref<{ payload?: { values?: Record<string, unknown> } } | null>(null) }
+const ticketBlocks = computed(() => (ticket.value?.payload?.values?.content as unknown[] | undefined) ?? [])
 useHead({
   title: 'Preview',
   meta: [{ name: 'robots', content: 'noindex, nofollow' }],
@@ -28,7 +40,7 @@ useHead({
 </script>
 
 <template>
-  <KestrelPreviewBridge v-slot="{ blocks }">
+  <KestrelPreviewBridge :blocks="ticketBlocks" v-slot="{ blocks }">
     <BlockRenderer :blocks="(blocks as any[])" />
   </KestrelPreviewBridge>
 </template>

package/layers/public/app/utils/preview-protocol.ts

@@ -13,6 +13,8 @@
 
 /** Query flag that switches the public page into preview mode (value `1`). */
 export const PREVIEW_QUERY = 'kestrel-preview'
+/** Query carrying a preview TICKET — the editor's unsaved state, rendered in a normal tab (ADR-0008). */
+export const PREVIEW_TOKEN_QUERY = 'kestrel-preview-token'
 /** Dedicated preview page for records without a public URL (new/unsaved, non-pageLike). Admin-gated. */
 export const PREVIEW_FALLBACK_PATH = '/__kestrel/preview'
 
@@ -74,6 +76,40 @@ export function parseFrameMessage(data: unknown): FrameToEditorMessage | null {
  * pageLike record — server-populated first paint, drafts included for the admin session), else the
  * dedicated fallback page (new/unsaved records, non-pageLike collections). Both carry the preview flag.
  */
+/**
+ * The record a ticket preview renders: the saved row with the editor's unsaved values laid over it. Both
+ * halves are column-keyed (the editor sends what a save would send), so this is a shallow override — a
+ * field the editor did not touch keeps the stored value, and a page that does not exist yet (an unsaved
+ * slug) renders from the payload alone. Pure.
+ *
+ * One override is not shallow: a single-valued relation/media field is column-keyed `<name>Id` (the
+ * `resolveColumnName`/`isSingleRefColumn` convention — many-relations and multi-media stay bare-keyed, so
+ * they're untouched by this), while its populated sidecar sits ALONGSIDE the id, not under it — `$<name>`
+ * for a relation (`buildRelationFieldPopulator`), `$media.<name>` for media (`populate.ts`'s `attach`).
+ * `values` here is raw unsaved editor state, never itself populated, so clearing such a field to null
+ * leaves `saved`'s old sidecar with nothing to overwrite it — a plain spread would let a removed
+ * author/cover keep rendering. Drop it explicitly for every `<name>Id` key the editor cleared.
+ */
+export function previewPage(
+  saved: Record<string, unknown> | null,
+  values: Record<string, unknown> | null | undefined,
+): Record<string, unknown> | null {
+  if (!values) return saved
+  const merged: Record<string, unknown> = { ...(saved ?? {}), ...values }
+  for (const key of Object.keys(values)) {
+    if (values[key] !== null || !key.endsWith('Id')) continue
+    const name = key.slice(0, -2)
+    if (!name) continue
+    if (Object.hasOwn(merged, `$${name}`)) delete merged[`$${name}`]
+    const media = merged.$media as Record<string, unknown> | undefined
+    if (media && Object.hasOwn(media, name)) {
+      const { [name]: _dropped, ...rest } = media
+      merged.$media = rest
+    }
+  }
+  return merged
+}
+
 export function previewSrc(publicUrl: string | null, locale: string): string {
   if (publicUrl) return `${publicUrl}?${PREVIEW_QUERY}=1`
   const loc = locale ? `&locale=${encodeURIComponent(locale)}` : ''

package/layers/public/server/api/preview.get.ts

@@ -0,0 +1,28 @@
+import { usePreviewStore, previewOwner } from '../utils/preview-token'
+
+/**
+ * Read back a preview ticket (ADR-0008) — the public page fetches it during SSR when the URL carries
+ * `?kestrel-preview-token=…` and renders the editor's unsaved state instead of the stored record. Admin-
+ * only and session-bound; an expired, foreign or unknown token is `null`, which the page treats as
+ * "nothing to preview" and falls back to the saved content rather than failing the render.
+ */
+export default defineEventHandler((event) => {
+  requireAdmin(event) // write-authorization backstop (defense-in-depth; see require-admin.ts)
+  const token = getQuery(event).token
+  if (typeof token !== 'string' || !token) return null
+  const payload = usePreviewStore().read(token, previewOwner(event))
+  if (!payload) return null
+
+  // The editor sends what a SAVE would send — raw ids for media and relations — so the ticket goes through
+  // the same read population a stored record does. Without it the preview would render a page with the
+  // images and internal links stripped, which is worse than useless for judging a layout.
+  const c = getCollection(payload.collection)
+  if (!c) return { payload }
+  const locale = payload.locale || primaryLocale()
+  const values = withResolveScope(
+    () => populateRow({ ...payload.values }, { depth: 1, locale, def: c.def }),
+    resolveBudgetFor(1),
+    `preview ${payload.collection}`,
+  )
+  return { payload: { ...payload, values } }
+})

package/layers/public/server/api/preview.post.ts

@@ -0,0 +1,93 @@
+import { usePreviewStore, previewOwner, type PreviewPayload } from '../utils/preview-token'
+import type { BuiltCollection } from '../../../core/server/utils/collection-types'
+import { fieldIs, type FieldDef } from '../../../core/server/utils/defineCollection'
+import { resolveColumnName } from '../../../fields/server/field-registry/naming'
+import { sanitizeRichtext } from '../../../fields/server/field-registry/sanitize'
+import { getBlock } from '../../../fields/server/utils/defineBlock'
+
+/** Editor payloads are form state, not uploads — a block tree with populated media is far below this. */
+const MAX_PAYLOAD_BYTES = 2_000_000
+
+/**
+ * Sanitize every richtext leaf reachable from `scope` (top-level fields + nested repeater entries), in
+ * place. Mirrors the WALK shape of crud.ts's `applyFieldTransforms`/`transformNested`, but not the
+ * mechanism: richtext's sanitizer is wired into the Zod validator (`z.string().transform(sanitizeRichtext)`
+ * in field-registry/index.ts), not the field-type's `transform` hook that walk calls — and running the
+ * collection's Zod schema here isn't an option anyway, see `sanitizePreviewValues` below. So this calls
+ * `sanitizeRichtext` directly wherever a `richtext` field is present, and only there; every other field
+ * passes through untouched.
+ */
+function sanitizeRichtextFields(fields: Record<string, FieldDef>, scope: Record<string, unknown>): void {
+  for (const [key, fieldDef] of Object.entries(fields)) {
+    const { jsKey } = resolveColumnName(key, fieldDef)
+    if (!Object.hasOwn(scope, jsKey)) continue
+    if (fieldIs(fieldDef, 'richtext')) {
+      if (typeof scope[jsKey] === 'string') scope[jsKey] = sanitizeRichtext(scope[jsKey] as string)
+    } else if (fieldIs(fieldDef, 'repeater')) {
+      const entries = scope[jsKey]
+      if (Array.isArray(entries)) {
+        for (const entry of entries) if (entry && typeof entry === 'object') sanitizeRichtextFields(fieldDef.options.fields, entry as Record<string, unknown>)
+      }
+    }
+  }
+}
+
+/** Same walk as `transformBlocks` in crud.ts: each block's props (by its registered field defs) + its
+ *  slots' nested blocks, recursively. An unregistered block type is left as-is (matches crud.ts). */
+function sanitizeRichtextInBlocks(blocks: unknown): void {
+  if (!Array.isArray(blocks)) return
+  for (const block of blocks) {
+    if (!block || typeof block !== 'object') continue
+    const b = block as { type?: string; props?: unknown; slots?: unknown }
+    const def = typeof b.type === 'string' ? getBlock(b.type) : undefined
+    if (def && b.props && typeof b.props === 'object') sanitizeRichtextFields(def.fields, b.props as Record<string, unknown>)
+    if (b.slots && typeof b.slots === 'object') for (const sub of Object.values(b.slots as Record<string, unknown>)) sanitizeRichtextInBlocks(sub)
+  }
+}
+
+/**
+ * Apply the richtext sanitizer to a preview ticket's `values` — the fix for the ticket bypassing it
+ * entirely (it normally runs as a Zod `.transform()` on WRITE, `create`/`update`/`putSingleton` in
+ * crud.ts; a ticket never reaches those). Deliberately NOT a schema parse: `values` is the editor's
+ * in-progress, possibly-invalid draft (a missing required field, an out-of-range number, …), and a preview
+ * exists precisely so a draft can be inspected BEFORE it would pass a save — a strict or even a `.partial()`
+ * parse would legitimately reject some of what it must accept. Sanitizing is not a validity constraint
+ * though (it only narrows stored bytes, the same way a save would), so a direct field-tree walk gets the
+ * safety without the rejection risk. Walks top-level fields, repeater entries, and (when the collection
+ * uses the block editor) block props + nested slots — everywhere a richtext leaf can live.
+ */
+function sanitizePreviewValues(collection: BuiltCollection, values: Record<string, unknown>): void {
+  sanitizeRichtextFields(collection.def.fields, values)
+  if (collection.def.blocks?.enabled && Object.hasOwn(values, 'content')) sanitizeRichtextInBlocks(values.content)
+}
+
+/**
+ * Mint a preview ticket for the editor's UNSAVED state (ADR-0008). The editor posts what it currently
+ * holds and opens the page at `?kestrel-preview-token=<token>` in a new tab; nothing is written to the DB,
+ * so previewing never doubles as an unasked-for save. Admin-only (default-deny API guard + the backstop),
+ * and the ticket is bound to this session.
+ *
+ *   body: { collection, id: number | null, locale?, values }
+ *   200:  { token, expiresAt }
+ */
+export default defineEventHandler(async (event) => {
+  requireAdmin(event) // write-authorization backstop (defense-in-depth; see require-admin.ts)
+  const body = (await readBody(event)) as Partial<PreviewPayload> | null
+
+  const name = typeof body?.collection === 'string' ? body.collection : ''
+  const collection = getCollection(name) as BuiltCollection | undefined
+  if (!collection) throw createError({ statusCode: 404, statusMessage: `Unknown collection: ${name}` })
+
+  const values = body?.values
+  if (!values || typeof values !== 'object' || Array.isArray(values)) {
+    throw createError({ statusCode: 400, statusMessage: 'preview requires a `values` object' })
+  }
+  if (JSON.stringify(values).length > MAX_PAYLOAD_BYTES) {
+    throw createError({ statusCode: 413, statusMessage: 'Preview payload too large' })
+  }
+  sanitizePreviewValues(collection, values as Record<string, unknown>)
+
+  const id = typeof body?.id === 'number' && Number.isInteger(body.id) ? body.id : null
+  const locale = typeof body?.locale === 'string' ? body.locale : undefined
+  return usePreviewStore().mint(previewOwner(event), { collection: name, id, locale, values })
+})