@michaelthielemann/kestrel 1.7.0 → 2.1.0

package/layers/media/server/utils/ai-signal-detect.ts

@@ -0,0 +1,155 @@
+/**
+ * Upload-time scan for signals that a file was AI-generated or -manipulated (EU AI Act Art. 50).
+ *
+ * **This produces EVIDENCE, never a classification.** Everything it finds is quoted into the free-text
+ * `aiNote`; the legal `aiSourceType` stays a deliberate human decision, because a signal is neither proof
+ * nor its absence a disproof: metadata survives no re-save, screenshot or re-encode, and an upstream file
+ * can be mislabeled or forged. In particular a C2PA manifest is reported as PRESENT only — verifying its
+ * signature needs the full C2PA SDK plus a trust list, which Kestrel deliberately does not ship.
+ *
+ * Pure (no DB, no Nitro) so it stays unit-testable, and never throws: an unreadable file is simply no
+ * evidence, which must not fail the upload it came with.
+ */
+
+/** Tools that name themselves in EXIF `Software`. Matched case-insensitively as whole phrases, so an
+ *  ordinary "Adobe Photoshop" is not caught by the "Adobe Firefly" entry. */
+const KNOWN_GENERATORS = [
+  'midjourney', 'dall-e', 'dall·e', 'adobe firefly', 'stable diffusion', 'leonardo.ai',
+  'nightcafe', 'bing image creator', 'google imagefx', 'imagen', 'flux.1', 'ideogram',
+]
+
+/** PNG text-chunk keywords the Stable-Diffusion / ComfyUI families write their generation graph under. */
+const GENERATION_KEYWORDS = ['parameters', 'prompt', 'workflow']
+
+export interface AiSignal {
+  /** One human-readable line per signal found, in a stable order. Never empty (the result is null instead). */
+  evidence: string[]
+}
+
+/** Walk PNG chunks after the 8-byte signature, yielding `[type, data]`. Bails out on any malformed length. */
+function* pngChunks(bytes: Buffer): Generator<[string, Buffer]> {
+  if (bytes.length < 8 || bytes.readUInt32BE(0) !== 0x89504E47) return
+  let at = 8
+  while (at + 8 <= bytes.length) {
+    const len = bytes.readUInt32BE(at)
+    const end = at + 8 + len
+    if (len > bytes.length || end + 4 > bytes.length) return
+    yield [bytes.toString('latin1', at + 4, at + 8), bytes.subarray(at + 8, end)]
+    at = end + 4 // skip the trailing CRC
+  }
+}
+
+/** Walk JPEG marker segments after SOI, yielding `[marker, payload]`. Stops at SOS (entropy-coded data). */
+function* jpegSegments(bytes: Buffer): Generator<[number, Buffer]> {
+  if (bytes.length < 4 || bytes[0] !== 0xFF || bytes[1] !== 0xD8) return
+  let at = 2
+  while (at + 4 <= bytes.length) {
+    if (bytes[at] !== 0xFF) return
+    const marker = bytes[at + 1]!
+    if (marker === 0xDA || marker === 0xD9) return
+    const len = bytes.readUInt16BE(at + 2)
+    if (len < 2 || at + 2 + len > bytes.length) return
+    yield [marker, bytes.subarray(at + 4, at + 2 + len)]
+    at += 2 + len
+  }
+}
+
+/** Walk RIFF/WebP chunks, yielding `[fourcc, data]`. Chunks are padded to an even length. */
+function* riffChunks(bytes: Buffer): Generator<[string, Buffer]> {
+  if (bytes.length < 12 || bytes.toString('latin1', 0, 4) !== 'RIFF') return
+  let at = 12
+  while (at + 8 <= bytes.length) {
+    const len = bytes.readUInt32LE(at + 4)
+    const end = at + 8 + len
+    if (len > bytes.length || end > bytes.length) return
+    yield [bytes.toString('latin1', at, at + 4), bytes.subarray(at + 8, end)]
+    at = end + (len % 2)
+  }
+}
+
+/**
+ * The IPTC Digital Source Type a generator self-declared, read straight out of the embedded XMP packet.
+ * Deliberately a byte-level scan rather than a metadata library: XMP is the same XML in every container,
+ * so this also covers the ones exifr cannot open (WebP), and it costs one `indexOf` when absent.
+ */
+function findDigitalSourceType(bytes: Buffer): string | null {
+  const at = bytes.indexOf('DigitalSourceType', 0, 'latin1')
+  if (at < 0) return null
+  const window = bytes.toString('latin1', at, Math.min(at + 512, bytes.length))
+  // Both XMP serializations: as an rdf:Description attribute, or as its own element.
+  const value = /^DigitalSourceType\s*=\s*"([^"]*)"/.exec(window)?.[1]
+    ?? /^DigitalSourceType[^>]*>([^<]*)</.exec(window)?.[1]
+  const trimmed = value?.trim()
+  return trimmed ? trimmed : null
+}
+
+/** True when the file structurally carries a C2PA/JUMBF manifest store. Presence only — never verified. */
+function hasC2paManifest(bytes: Buffer): boolean {
+  for (const [type] of pngChunks(bytes)) if (type === 'caBX') return true
+  // C2PA-in-JPEG lives in APP11 segments whose payload starts with the JUMBF "JP" identifier.
+  for (const [marker, payload] of jpegSegments(bytes)) {
+    if (marker === 0xEB && payload.length >= 2 && payload.toString('latin1', 0, 2) === 'JP') return true
+  }
+  for (const [fourcc] of riffChunks(bytes)) if (fourcc === 'C2PA') return true
+  return false
+}
+
+/** The generation-parameter keyword a PNG text chunk is stored under, or null. Covers tEXt/zTXt/iTXt —
+ *  in all three the keyword is the leading null-terminated string, so a compressed payload needs no
+ *  inflating to be recognised (exifr only decodes the uncompressed tEXt form). */
+function findPngGenerationChunk(bytes: Buffer): string | null {
+  for (const [type, data] of pngChunks(bytes)) {
+    if (type !== 'tEXt' && type !== 'zTXt' && type !== 'iTXt') continue
+    const nul = data.indexOf(0)
+    const keyword = data.toString('latin1', 0, nul < 0 ? data.length : nul).toLowerCase()
+    if (GENERATION_KEYWORDS.includes(keyword)) return keyword
+  }
+  return null
+}
+
+/** The EXIF `Software`/`ProcessingSoftware` value, when it names a tool on the known-generator list. */
+async function findGeneratorSoftware(bytes: Buffer): Promise<string | null> {
+  let tags: Record<string, unknown> | undefined
+  try {
+    // Loaded lazily: consumers who never turn the feature on never pay the module's parse cost.
+    const exifr = (await import('exifr')).default
+    tags = await exifr.parse(bytes, { tiff: true, exif: true, mergeOutput: true }) as Record<string, unknown> | undefined
+  } catch {
+    return null // an unsupported container or a corrupt header is simply no evidence
+  }
+  for (const key of ['Software', 'ProcessingSoftware']) {
+    const value = tags?.[key]
+    if (typeof value !== 'string' || !value.trim()) continue
+    const haystack = value.toLowerCase()
+    if (KNOWN_GENERATORS.some((g) => haystack.includes(g))) return value.trim()
+  }
+  return null
+}
+
+/**
+ * Scan an uploaded file for AI-origin signals. Returns null when nothing matched — which is NOT evidence
+ * of non-AI origin, only the absence of a declaration.
+ */
+export async function detectAiSignal(bytes: Buffer, _mime: string): Promise<AiSignal | null> {
+  const evidence: string[] = []
+
+  const sourceType = findDigitalSourceType(bytes)
+  if (sourceType) evidence.push(`IPTC/XMP Digital Source Type: ${sourceType}`)
+
+  const software = await findGeneratorSoftware(bytes)
+  if (software) evidence.push(`EXIF Software: ${software}`)
+
+  if (hasC2paManifest(bytes)) {
+    evidence.push('C2PA content-credentials manifest present (unverified — presence only, no signature check)')
+  }
+
+  const keyword = findPngGenerationChunk(bytes)
+  if (keyword) evidence.push(`PNG text chunk "${keyword}" present (Stable-Diffusion-style generation parameters)`)
+
+  return evidence.length ? { evidence } : null
+}
+
+/** How the scan's findings are worded into `aiNote`. Kept here so the wording has one home. */
+export function aiSignalNote(signal: AiSignal): string {
+  return `Detected at upload: ${signal.evidence.join('; ')}`
+}

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

@@ -56,7 +56,8 @@ export function listLibrary(db: BetterSQLite3Database, q: LibraryQuery, publicUr
     return {
       id: m.id, filename: r.filename as string, mime: m.mime, folder: r.folder as string,
       size: r.size as number, width: m.width, height: m.height, thumbhash: m.thumbhash,
-      src: m.src, srcset, alt: m.alt, createdAt: r.createdAt as Date, updatedAt: r.updatedAt as Date,
+      src: m.src, srcset, alt: m.alt, aiDisclosure: m.aiDisclosure,
+      createdAt: r.createdAt as Date, updatedAt: r.updatedAt as Date,
     }
   })
 

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

@@ -14,6 +14,10 @@ export interface MediaInput {
   checksum: string
   derived?: DerivedImage
   translations?: Record<string, { alt?: string; title?: string; description?: string }>
+  /** EU AI Act disclosure to write. Omitted/null ⇒ the column is left out of the values entirely, which is
+   *  what keeps an overwrite from wiping a disclosure the re-upload did not re-send. */
+  aiSourceType?: string | null
+  aiNote?: string | null
 }
 
 /**
@@ -46,6 +50,10 @@ export function buildMediaValues(input: MediaInput): Record<string, unknown> {
     thumbhash: input.derived?.thumbhash ?? null,
     derivatives: manifest,
     translations: input.translations ?? {},
+    // Written only when there is something to write: the overwrite path feeds these same values to an
+    // UPDATE, and a null here would silently clear a disclosure an editor set on the existing row.
+    ...(input.aiSourceType != null ? { aiSourceType: input.aiSourceType } : {}),
+    ...(input.aiNote != null ? { aiNote: input.aiNote } : {}),
   }
 }
 

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

@@ -7,6 +7,9 @@ import type { DerivativeManifest } from './record'
 /** One derivative, tagged with its parsed name + format so `<picture>` rendering can group by format. */
 export interface MediaVariant { name: string; format: string; url: string; width: number; height: number }
 
+/** The disclosure-relevant subset of the IPTC Digital Source Type vocabulary (EU AI Act Art. 50). */
+export type AiSourceType = 'trainedAlgorithmicMedia' | 'compositeWithTrainedAlgorithmicMedia' | 'algorithmicallyEnhanced'
+
 export interface ResolvedMedia {
   id: number
   /** The media's storage folder ('' at the media root) — lets the field open the picker there. */
@@ -23,6 +26,10 @@ export interface ResolvedMedia {
   srcset: { url: string; width: number }[]
   /** Every derivative, name+format-tagged — the source `KestrelImg`/`useMediaVariant` build `<picture>` from. */
   variants: MediaVariant[]
+  /** EU AI Act Art. 50 disclosure, set by an editor — null when unset. Always resolved regardless of
+   *  `kestrel.config.ts`'s `aiDisclosure.enabled` (that flag only gates the admin UI). Kestrel never
+   *  renders this automatically; read it directly or opt into `KestrelImg`'s `aiBadge` prop. */
+  aiDisclosure: { sourceType: AiSourceType; note: string | null } | null
 }
 
 interface MediaRow {
@@ -35,6 +42,8 @@ interface MediaRow {
   thumbhash: string | null
   derivatives: DerivativeManifest | null
   translations: Record<string, { alt?: string; title?: string; description?: string }> | null
+  aiSourceType: string | null
+  aiNote: string | null
 }
 
 export function resolveMedia(row: MediaRow, locale: string, publicUrl: (key: string) => string): ResolvedMedia {
@@ -69,6 +78,9 @@ export function resolveMedia(row: MediaRow, locale: string, publicUrl: (key: str
     src: publicUrl(row.storageKey),
     srcset,
     variants,
+    // A note without a source type is only evidence (e.g. the upload scan's pre-fill), not a disclosure —
+    // never emit a half-filled object a consumer might render as one.
+    aiDisclosure: row.aiSourceType ? { sourceType: row.aiSourceType as AiSourceType, note: row.aiNote ?? null } : null,
   }
 }
 

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
@@ -15,6 +15,9 @@ interface RenderedPage {
     description?: string
     noindex?: boolean
     $media?: { image?: { src: string; width: number | null; height: number | null } | null }
+    author?: string
+    publishedDate?: string
+    keywords?: string
   }
   content?: unknown[]
   status?: string
@@ -42,10 +45,24 @@ const { data: resolved, error: resolveError } = await useAsyncData(`page:${local
     collection: string | null
     page: (RenderedPage & Record<string, unknown>) | null
     alternates?: Array<{ locale: string; path: string }>
+    ancestors?: Array<{ path: string; title?: string; locale?: string }>
     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 +77,7 @@ const pageState = usePublicPageState()
 watchEffect(() => {
   pageState.value = {
     collection: resolved.value?.collection ?? null,
-    page: resolved.value?.page ?? null,
+    page: page.value,
   }
 })
 
@@ -68,6 +85,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.
@@ -93,7 +117,7 @@ if (!page.value && path !== '/') throw createError({ statusCode: 404, statusMess
 // Canonical / Open Graph / twitter card / hreflang: pure model (`buildPageHead`) fed from the resolved
 // page + the public runtime config. Absolute-URL emissions (canonical, og:url, hreflang, relative
 // og:image) require a configured siteUrl and degrade away without one.
-const publicRc = useRuntimeConfig().public as { siteUrl?: string; siteName?: string }
+const publicRc = useRuntimeConfig().public as { siteUrl?: string; siteName?: string; seoArticleMeta?: boolean }
 const seo = page.value?.seo ?? {}
 const siteHead = resolved.value?.site ?? null
 const fallbacks = siteHeadFallbacks(seo, siteHead)
@@ -113,11 +137,36 @@ const head = buildPageHead({
   alternates: resolved.value?.alternates ?? [],
 })
 
+// schema.org JSON-LD — the one grounding signal every major answer engine documents. Same inputs as the
+// head above, so the two can never disagree; it degrades away without a siteUrl and is suppressed for a
+// noindex page or an unsaved ticket preview. Article metadata is published ONLY with `seo.articleMeta`
+// on: the fields may hold values (the column always round-trips them) that this installation must not
+// disclose, so the flag gates emission, not storage.
+const jsonLd = buildJsonLd({
+  siteUrl: typeof publicRc.siteUrl === 'string' ? publicRc.siteUrl : '',
+  siteName: typeof publicRc.siteName === 'string' ? publicRc.siteName : '',
+  canonical: head.canonical,
+  locale,
+  primary,
+  prefixPrimary,
+  title: pageTitle,
+  description: fallbacks.description,
+  imageUrl: head.meta.ogImage,
+  noindex: previewingTicket.value || seo.noindex,
+  ancestors: resolved.value?.ancestors ?? [],
+  article: publicRc.seoArticleMeta === true
+    ? { author: seo.author, publishedDate: seo.publishedDate, keywords: seo.keywords }
+    : null,
+})
+
 // Set the document language from the resolved locale so prerendered /de pages ship <html lang="de">
 // (WCAG 2.2 SC 3.1.1); without this every page would carry the build-default language.
 // Point AI agents at the generated llms.txt (alongside the robots.txt comment + sitemap) on every page.
 useHead({
   htmlAttrs: { lang: locale },
+  // `textContent` (not innerHTML) is unhead's XSS-safe arm for a data script: it takes the object and
+  // serializes it itself, so editor-authored strings can never close the <script>.
+  script: jsonLd ? [{ type: 'application/ld+json' as const, textContent: jsonLd }] : [],
   link: [
     // `rel` needs the literal type: unhead keys its link union on it, and inside an array literal that
     // reaches `link:` through a spread there is no contextual type to stop TS widening it to `string`.
@@ -129,7 +178,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,
@@ -148,9 +198,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/json-ld.ts

@@ -0,0 +1,139 @@
+import { localePath } from '../../../core/app/utils/locale-path'
+
+/** One published ancestor of the rendered page, outermost first — the breadcrumb trail. */
+export interface JsonLdAncestor {
+  /** The ancestor's own path, unprefixed (the emitter locale-prefixes it, as `buildPageHead` does). */
+  path: string
+  title?: string
+  /** The ancestor's OWN locale. Absent for a record in a non-translatable collection, whose single
+   *  published URL is the primary-locale one — the same `row.locale ?? primary` rule the sitemap uses. */
+  locale?: string
+}
+
+/** The opt-in article metadata (`kestrel.seo.articleMeta`). Absent ⇒ the page stays a plain `WebPage`
+ *  and no authorship or date is published — the default, and the only behaviour a consumer who never
+ *  turns the flag on can get. */
+export interface JsonLdArticle {
+  author?: string
+  /** ISO date (`YYYY-MM-DD`) or ISO datetime; anything else is dropped rather than emitted invalid. */
+  publishedDate?: string
+  /** Free-form comma-separated list — schema.org accepts that spelling for `keywords` verbatim. */
+  keywords?: string
+}
+
+export interface JsonLdInput {
+  /** Absolute site origin ('' when unconfigured). */
+  siteUrl: string
+  siteName?: string
+  /** The page's absolute canonical URL (from `buildPageHead`); absent ⇒ nothing is emitted. */
+  canonical?: string
+  locale: string
+  primary: string
+  prefixPrimary: boolean
+  title?: string
+  description?: string
+  /** The already-absolute og:image URL, so the image-resolution rules live in one place. */
+  imageUrl?: string
+  /** Excluded from the graph entirely — see `buildJsonLd`. */
+  noindex?: boolean
+  ancestors?: JsonLdAncestor[]
+  article?: JsonLdArticle | null
+}
+
+/** A type alias, not an interface, for the same reason as `PageHeadLink`: unhead's `script` entry types
+ *  `textContent` as `string | Record<string, unknown>`, and TS derives the implicit index signature that
+ *  needs for an alias but never for an interface. */
+export type JsonLd = {
+  '@context': 'https://schema.org'
+  '@graph': Record<string, unknown>[]
+}
+
+const trimmed = (v: unknown): string | undefined => {
+  const s = typeof v === 'string' ? v.trim() : ''
+  return s || undefined
+}
+
+// schema.org dates are ISO 8601; an editor free-text value that is not one would be published as a
+// broken `datePublished`, which is worse for a consuming engine than no date at all.
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}([T ]|$)/
+
+/**
+ * The JSON-LD graph for a rendered public page: a site-wide `WebSite`, the page itself as a `WebPage`
+ * (or an `Article`, when the consumer opted into article metadata AND the record carries some), and a
+ * `BreadcrumbList` built from the page's real published ancestors. Pure, like `buildPageHead`, and fed
+ * the same already-resolved values — the precedence chain stays outside (ADR-0007).
+ *
+ * Two whole-graph veto rules, both because the alternative is a false signal rather than a missing one:
+ * without an absolute canonical every `@id`/`url` would be a relative path that resolves against
+ * whatever host fetched it, and a `noindex` page asking to be excluded from search has no business
+ * shipping structured data that exists to be indexed.
+ *
+ * Breadcrumb items are REAL pages only (the resolver hands over the published ancestors it found), so a
+ * trail never advertises an intermediate URL that 404s; a trail of one is dropped, since "you are here"
+ * carries no information.
+ */
+export function buildJsonLd(input: JsonLdInput): JsonLd | null {
+  const canonical = trimmed(input.canonical)
+  if (!canonical || input.noindex) return null
+  const base = input.siteUrl.replace(/\/+$/, '')
+  const abs = (path: string, locale: string) => `${base}${localePath(path, locale, input.primary, input.prefixPrimary)}`
+
+  const graph: Record<string, unknown>[] = []
+  const siteName = trimmed(input.siteName)
+  // A nameless WebSite node is an empty assertion — omit it, and with it the isPartOf edge that would
+  // otherwise dangle at an @id nothing defines.
+  const websiteId = siteName ? `${base}/#website` : undefined
+  if (websiteId) graph.push({ '@type': 'WebSite', '@id': websiteId, url: `${base}/`, name: siteName })
+
+  const article = usableArticle(input.article)
+  const page: Record<string, unknown> = {
+    '@type': article ? 'Article' : 'WebPage',
+    '@id': `${canonical}#webpage`,
+    url: canonical,
+  }
+  const title = trimmed(input.title)
+  // `headline` is the Article spelling of the same value; keeping them apart avoids a node that claims
+  // both and matches what validators expect per type.
+  if (title) page[article ? 'headline' : 'name'] = title
+  const description = trimmed(input.description)
+  if (description) page.description = description
+  page.inLanguage = input.locale
+  if (websiteId) page.isPartOf = { '@id': websiteId }
+  const imageUrl = trimmed(input.imageUrl)
+  if (imageUrl) page.image = imageUrl
+  if (article) {
+    if (article.author) page.author = { '@type': 'Person', name: article.author }
+    if (article.publishedDate) page.datePublished = article.publishedDate
+    if (article.keywords) page.keywords = article.keywords
+  }
+
+  const crumbs = [
+    ...(input.ancestors ?? []).map((a) => ({ name: trimmed(a.title) ?? a.path, item: abs(a.path, a.locale ?? input.primary) })),
+    { name: title ?? canonical, item: canonical },
+  ]
+  if (crumbs.length >= 2) {
+    const breadcrumbId = `${canonical}#breadcrumb`
+    page.breadcrumb = { '@id': breadcrumbId }
+    graph.push(page, {
+      '@type': 'BreadcrumbList',
+      '@id': breadcrumbId,
+      itemListElement: crumbs.map((c, i) => ({ '@type': 'ListItem', position: i + 1, name: c.name, item: c.item })),
+    })
+  } else {
+    graph.push(page)
+  }
+
+  return { '@context': 'https://schema.org', '@graph': graph }
+}
+
+/** The article bag reduced to the values worth publishing, or null — which keeps the node a `WebPage`.
+ *  A bag of blanks (an editor who opened the fields and typed nothing) must not upgrade the type. */
+function usableArticle(article: JsonLdArticle | null | undefined): Required<JsonLdArticle> | null {
+  if (!article) return null
+  const author = trimmed(article.author) ?? ''
+  const rawDate = trimmed(article.publishedDate) ?? ''
+  const publishedDate = ISO_DATE.test(rawDate) ? rawDate : ''
+  const keywords = trimmed(article.keywords) ?? ''
+  // An unparseable date alone must not upgrade the type either — nothing would be emitted from it.
+  return author || publishedDate || keywords ? { author, publishedDate, keywords } : null
+}

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/modules/deploy-output/deploy-output.ts

@@ -69,12 +69,26 @@ export function precompressedEncoding(filename: string, siblingNames: string[]):
 const IMMUTABLE_CACHE = 'public, max-age=31536000, immutable'
 const REVALIDATE_CACHE = 'public, max-age=0, must-revalidate'
 
+/** Artifacts served at a LITERAL key (not `<path>/index.html`) and rendered from the live DB rather than
+ *  copied from the build. One list, because each of them has to be handled the same way in four places:
+ *  re-rendered on every publish, excluded from the build-asset mirror (a stale copy must never overwrite
+ *  a fresh one), seeded into the prerender routes, and cached as revalidate-always below.
+ *  `llms-full.txt` is opt-in (`kestrel.seo.llmsFull`) and simply renders to a 404 when off — it stays in
+ *  this list either way, so the rules that are about the FILENAME hold regardless of the flag; only the
+ *  prerender seeding, which asks for the ROUTE, has to consult it. */
+export const META_KEYS = ['sitemap.xml', 'robots.txt', 'llms.txt', 'llms-full.txt', 'redirects.json'] as const
+
+export function isMetaKey(key: string): boolean {
+  return (META_KEYS as readonly string[]).includes(key)
+}
+
 /**
  * `Cache-Control` for a static-output key, or `undefined` for no explicit policy. Content-hashed
- * `_nuxt/` assets get a year + `immutable` (the hash is the cache key — new content ⇒ new URL). HTML,
- * the sitemap and `robots.txt` live at *stable* URLs whose content changes on any deploy, so they get
- * `max-age=0, must-revalidate` (cacheable but always revalidated). Everything else (favicons, fonts,
- * un-hashed media) is left to the host default.
+ * `_nuxt/` assets get a year + `immutable` (the hash is the cache key — new content ⇒ new URL). HTML and
+ * the `META_KEYS` artifacts live at *stable* URLs whose content changes on any deploy, so they get
+ * `max-age=0, must-revalidate` (cacheable but always revalidated) — `redirects.json` especially, since a
+ * cached copy keeps serving withdrawn redirects. Everything else (favicons, fonts, un-hashed media) is
+ * left to the host default.
  */
 export function cacheControlFor(key: string): string | undefined {
   // Nuxt's app manifest lives at a STABLE _nuxt URL but its content (the buildId) changes every build, so it
@@ -82,7 +96,7 @@ export function cacheControlFor(key: string): string | undefined {
   if (key === '_nuxt/builds/latest.json') return REVALIDATE_CACHE
   if (key === '_nuxt' || key.startsWith('_nuxt/')) return IMMUTABLE_CACHE
   const base = key.split('/').pop() ?? key
-  if (base.endsWith('.html') || base === 'sitemap.xml' || base === 'robots.txt' || base === 'llms.txt') return REVALIDATE_CACHE
+  if (base.endsWith('.html') || isMetaKey(base)) return REVALIDATE_CACHE
   return undefined
 }
 

package/layers/public/modules/prerender-routes/index.ts

@@ -4,7 +4,7 @@ import { defineNuxtModule } from '@nuxt/kit'
 import Database from 'better-sqlite3'
 import { collectPageRoutes, pageLikeTables } from './discover'
 import { localePath } from '../../../core/app/utils/locale-path'
-import { recordRouteDiscovery, type RouteDiscovery } from '../deploy-output/deploy-output'
+import { recordRouteDiscovery, META_KEYS, type RouteDiscovery } from '../deploy-output/deploy-output'
 import { resolveKestrel, type KestrelConfig } from '../../../core/server/utils/kestrel-config'
 
 // Read published paths from EVERY page-like collection straight from the DB at build time so
@@ -73,7 +73,10 @@ export default defineNuxtModule({
       // Hand the deploy module the completeness of THIS enumeration — the only step that knows it.
       recordRouteDiscovery(nuxt, discovery)
       nitro.prerender ||= {}
-      nitro.prerender.routes = [...new Set([...(nitro.prerender.routes ?? []), ...discovery.routes, '/sitemap.xml', '/robots.txt', '/llms.txt'])]
+      // Every meta artifact EXCEPT `llms-full.txt`, which is seeded only when the consumer opted in — the
+      // route 404s otherwise, and a prerender error fails the whole `nuxt generate`.
+      const meta = META_KEYS.filter((k) => k !== 'llms-full.txt' || c.seo.llmsFull).map((k) => `/${k}`)
+      nitro.prerender.routes = [...new Set([...(nitro.prerender.routes ?? []), ...discovery.routes, ...meta])]
       // Render pages in parallel — the dominant lever on `nuxt generate` wall-clock as page count grows.
       // Safe: page reads are synchronous better-sqlite3 (WAL + busy_timeout, can't interleave mid-statement);
       // the one WRITE on this path — the variant-registry capture — is an IMMEDIATE transaction, so