@michaelthielemann/kestrel 1.7.0 → 2.1.0

package/layers/public/server/utils/llms-full.ts

@@ -0,0 +1,125 @@
+import type { CollectionDef, FieldDef } from '../../../core/server/utils/defineCollection'
+import { fieldIs } from '../../../core/server/utils/defineCollection'
+import { getBlock } from '../../../fields/server/utils/defineBlock'
+import { resolveRichtextLinks } from '../../../fields/app/utils/richtext-links'
+import { escapeMarkdownBlock, richtextToMarkdown } from './richtext-markdown'
+
+/** One published page rendered in full: what `llms.txt` links to, plus the body it links to. */
+export interface LlmsFullPage {
+  title: string
+  url: string
+  description?: string
+  /** Markdown; already heading-shifted to nest under the page's own `###`. */
+  body: string
+}
+
+/** A titled group of pages — one `## heading` block, mirroring `llms.txt`'s sections. */
+export interface LlmsFullSection {
+  heading: string
+  pages: LlmsFullPage[]
+}
+
+/** Pages sit at `###`, so a body's own `<h1>` has to start at `####` to keep the outline valid. */
+export const LLMS_FULL_HEADING_OFFSET = 3
+
+// Same defence as `llms.txt`: a title, heading or description is editor-authored text, and a newline in
+// it would forge a second document line — here, a heading that invents a page.
+const oneLine = (s: string): string => s.replace(/\s+/g, ' ').trim()
+
+/**
+ * Render an `llms-full.txt` (the long form of https://llmstxt.org): the site header, then every
+ * published, indexable page's full Markdown body under its own `###` heading, grouped by collection.
+ * Where `llms.txt` is a map, this is the territory — one document an answer engine can retrieve without
+ * crawling. Pure + deterministic; the route feeds it published, indexable pages only.
+ */
+export function buildLlmsFullTxt(opts: { siteName: string; siteDescription?: string; sections: LlmsFullSection[] }): string {
+  const blocks: string[] = [`# ${oneLine(opts.siteName)}`]
+  // A description is a whole block of its own, so flattening its newlines is not enough — a leading `##`
+  // would still open a section beside the ones this generator writes.
+  if (opts.siteDescription) blocks.push(`> ${escapeMarkdownBlock(oneLine(opts.siteDescription))}`)
+  for (const section of opts.sections) {
+    if (!section.pages.length) continue
+    blocks.push(`## ${oneLine(section.heading)}`)
+    for (const page of section.pages) {
+      blocks.push(`### ${oneLine(page.title)}`)
+      blocks.push(`Source: ${page.url}`)
+      if (page.description) blocks.push(escapeMarkdownBlock(oneLine(page.description)))
+      if (page.body) blocks.push(page.body)
+    }
+  }
+  return `${blocks.join('\n\n')}\n`
+}
+
+export interface RecordMarkdownOptions {
+  /** Push every body heading down by this many levels — see `LLMS_FULL_HEADING_OFFSET`. */
+  headingOffset?: number
+  /** Top-level field keys the caller already rendered (the title it used as the heading). */
+  skipFields?: string[]
+  /** `kestrel:<collection>:<id>` → absolute URL, or null for a target that must not be linked (a draft,
+   *  a noindexed page, a non-routable record). Unresolved links keep their text and lose the anchor. */
+  resolveLink?: (collection: string, id: number) => string | null
+}
+
+/** The prose in one flat value bag (record columns | block props | a repeater entry), in field order.
+ *  Only `text` and `richtext` carry prose; `repeater` recurses. Everything else is data, not content —
+ *  a consumer's own field type is skipped rather than guessed at. */
+function bagMarkdown(fields: Record<string, FieldDef>, bag: Record<string, unknown>, opts: RecordMarkdownOptions, skip?: Set<string>): string[] {
+  const out: string[] = []
+  for (const [key, field] of Object.entries(fields)) {
+    if (skip?.has(key)) continue
+    const value = bag[key]
+    if (field.type === 'text') {
+      // `fieldIs` rather than a switch: the open consumer-type arm makes `type` a non-discriminant, so a
+      // switch would not narrow (the same reason `extract-refs` walks this way).
+      // A text field is raw editor input with no markup to constrain it, so it is the one value that
+      // reaches the document verbatim — it needs the same block-marker escaping converted prose gets.
+      const text = typeof value === 'string' ? value.trim() : ''
+      if (text) out.push(escapeMarkdownBlock(text))
+    } else if (field.type === 'richtext') {
+      // Always run the marker rewrite, resolver or not: an unrewritten `kestrel:<coll>:<id>` href would
+      // ship a private storage token as a link target. With no resolver every marker declines to `#`,
+      // which the converter renders as plain text.
+      const html = typeof value === 'string' ? resolveRichtextLinks(value, opts.resolveLink ?? (() => null)) : ''
+      const md = richtextToMarkdown(html, { headingOffset: opts.headingOffset })
+      if (md) out.push(md)
+    } else if (fieldIs(field, 'repeater')) {
+      if (Array.isArray(value)) {
+        for (const entry of value) {
+          if (entry && typeof entry === 'object') out.push(...bagMarkdown(field.options.fields, entry as Record<string, unknown>, opts))
+        }
+      }
+    }
+  }
+  return out
+}
+
+/** The prose in a block `content` array, recursing slots — the same walk `extract-refs` does for refs. */
+function blockMarkdown(content: unknown, opts: RecordMarkdownOptions): string[] {
+  const out: string[] = []
+  const walk = (nodes: unknown): void => {
+    if (!Array.isArray(nodes)) return
+    for (const node of nodes) {
+      if (!node || typeof node !== 'object') continue
+      const n = node as { type?: string; props?: Record<string, unknown>; slots?: Record<string, unknown> }
+      // An unregistered block type has no field defs, so there is no way to tell its prose from its
+      // configuration — emitting every string prop would put layout tokens into the document.
+      const def = n.type ? getBlock(n.type) : undefined
+      if (def && n.props && typeof n.props === 'object') out.push(...bagMarkdown(def.fields, n.props, opts))
+      if (n.slots && typeof n.slots === 'object') for (const slotNodes of Object.values(n.slots)) walk(slotNodes)
+    }
+  }
+  walk(content)
+  return out
+}
+
+/**
+ * A record's readable content as Markdown: its own text/richtext fields (in declaration order), then its
+ * block tree if the collection enables blocks. Pure apart from the block registry — the same dependency
+ * `extractRecordRefs` has, and for the same reason: a block's prose is only identifiable through its
+ * registered field defs.
+ */
+export function recordMarkdown(def: CollectionDef, row: Record<string, unknown>, opts: RecordMarkdownOptions = {}): string {
+  const blocks = bagMarkdown(def.fields, row, opts, opts.skipFields?.length ? new Set(opts.skipFields) : undefined)
+  if (def.blocks?.enabled) blocks.push(...blockMarkdown(row.content, opts))
+  return blocks.join('\n\n')
+}

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

@@ -24,6 +24,19 @@ const oneLine = (s: string): string => s.replace(/\s+/g, ' ').trim()
 // Additionally escape the brackets that would otherwise break the `[title](url)` markdown link.
 const linkText = (s: string): string => oneLine(s).replace(/[[\]]/g, '\\$&')
 
+/** The `## heading` for a collection's section: its plural label in the primary locale, else any locale's,
+ *  else its capitalised name. Shared by `llms.txt` and `llms-full.txt` so the two never disagree. */
+export function collectionHeading(def: { name: string; label?: { plural?: unknown } }, primaryLocale: string): string {
+  const cap = (s: string) => (s ? s[0]!.toUpperCase() + s.slice(1) : s)
+  const plural = def.label?.plural
+  if (typeof plural === 'string') return plural
+  if (plural && typeof plural === 'object') {
+    const byLocale = plural as Record<string, string>
+    return byLocale[primaryLocale] ?? Object.values(byLocale)[0] ?? cap(def.name)
+  }
+  return cap(def.name)
+}
+
 export function buildLlmsTxt(opts: { siteName: string; siteDescription?: string; sections: LlmsSection[] }): string {
   const lines: string[] = [`# ${oneLine(opts.siteName)}`]
   if (opts.siteDescription) lines.push('', `> ${oneLine(opts.siteDescription)}`)

package/layers/public/server/utils/page-resolve.ts

@@ -1,12 +1,26 @@
-import { asc, eq, getTableColumns } from 'drizzle-orm'
+import { and, asc, eq, getTableColumns } from 'drizzle-orm'
 import { list } from '../../../core/server/utils/crud'
 import { captureRead } from '../../../core/server/utils/read-capture'
-import { translationGroupTag } from './publish/invalidation'
+import { pagePathTag, translationGroupTag } from './publish/invalidation'
 import type { BuiltCollection } from '../../../core/server/utils/collection-types'
 import type { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3'
 
 export interface PageAlternate { locale: string; path: string }
-export interface ResolvedPage { collection: string; page: Record<string, unknown>; alternates: PageAlternate[] }
+/** One published page above this one in the path hierarchy — a real, linkable breadcrumb step. */
+export interface PageAncestor {
+  path: string
+  title?: string
+  /** The ancestor's OWN locale, so the crumb builds the URL that was actually published. Absent for a
+   *  non-translatable collection, whose rows have a single unprefixed (primary-locale) URL — prefixing
+   *  one of those with the reader's locale would link a page `nuxt generate` never wrote. */
+  locale?: string
+}
+export interface ResolvedPage {
+  collection: string
+  page: Record<string, unknown>
+  alternates: PageAlternate[]
+  ancestors: PageAncestor[]
+}
 
 /** The matched page (or null) plus the collections whose lookup threw. `failed` is non-empty ⇒ the scan
  *  was INCOMPLETE, so `page: null` must never be treated as an authoritative "no such page". */
@@ -63,6 +77,92 @@ function publishedAlternates(db: BetterSQLite3Database, c: BuiltCollection, page
   return alternates.length >= 2 ? alternates : []
 }
 
+/** Every strict path prefix of a page's path, outermost first: `/blog/hello` → `['/', '/blog']`. The
+ *  site root is an ancestor of everything except itself. */
+function ancestorPaths(path: string): string[] {
+  if (path === '/' || !path.startsWith('/')) return []
+  const segments = path.split('/').filter(Boolean)
+  const paths = ['/']
+  for (let i = 1; i < segments.length; i += 1) paths.push(`/${segments.slice(0, i).join('/')}`)
+  return paths
+}
+
+/**
+ * The page's breadcrumb trail: the published, INDEXABLE page at each ancestor path, in the page's own
+ * locale. A path segment with no page behind it is SKIPPED rather than synthesised — schema.org
+ * breadcrumb items are links, and a trail that points at a 404 is a worse signal than a shorter trail.
+ * The filters mirror the sitemap's, so a breadcrumb never advertises what the sitemap withholds.
+ *
+ * TWO dependency edges are captured per ancestor, because neither covers the other:
+ *  - the PATH (`pagePathTag`), for every path looked in — including those with no page at all and those
+ *    whose lookup threw. Kestrel has no parent/child relation between pages, so an ancestor is a
+ *    path-prefix match, and a page CREATED at `/blog` after `/blog/hello` was published has no id anything
+ *    could have captured beforehand. A path is knowable before its page exists.
+ *  - the RECORD (`<coll>:<id>`) of whatever row sits there, captured before the filters below so a
+ *    currently-invisible one counts too — the edge that carries a rename, a `noindex` or an unpublish,
+ *    none of which `crumbTags` can see (see the comment at that capture).
+ * `publishedAlternates` pairs a group tag with a record tag for exactly the same reason.
+ */
+function publishedAncestors(
+  db: BetterSQLite3Database,
+  collections: BuiltCollection[],
+  path: string,
+  locale: string | undefined,
+  publishedOnly: boolean,
+): PageAncestor[] {
+  const out: PageAncestor[] = []
+  for (const ancestorPath of ancestorPaths(path)) {
+    // Before the scan, so the edge exists whatever the scan finds — no page, a draft, a noindexed one, or
+    // a collection whose table could not be read. A write at this path emits the same tag (`crumbTags` in
+    // classifyWrite), which is what repairs this page's trail.
+    captureRead(pagePathTag(ancestorPath))
+    for (const c of collections) {
+      if (!c.def.pageLike) continue
+      // Project only what a crumb needs — never the row: this runs once per path segment per render, and
+      // pulling every page's block JSON to read a title would multiply the cost of a full publish.
+      const cols = getTableColumns(c.table) as Record<string, never>
+      const hasStatus = Object.hasOwn(cols, 'status')
+      const proj: Record<string, unknown> = { id: cols.id, path: cols.path }
+      if (hasStatus) proj.status = cols.status
+      if (c.def.seo) proj.seo = cols.seo
+      if (c.def.translatable) proj.locale = cols.locale
+      if (Object.hasOwn(cols, 'title')) proj.title = cols.title
+      const scoped = c.def.translatable && locale ? and(eq(cols.path, ancestorPath), eq(cols.locale, locale)) : eq(cols.path, ancestorPath)
+      let row: { id: number; status?: string; seo?: { title?: string; noindex?: boolean } | null; title?: unknown; locale?: string } | undefined
+      try {
+        // Order by locale so an unscoped lookup (no locale requested) still answers deterministically
+        // rather than with whatever row the table happens to yield first.
+        const q = db.select(proj as never).from(c.table).where(scoped)
+        row = (c.def.translatable ? q.orderBy(asc(cols.locale)) : q).limit(1).get() as typeof row
+      } catch (error) {
+        // Same isolation rule as the main scan: a drifted collection loses its crumbs, loudly, instead of
+        // failing the whole render.
+        console.error(`[kestrel] resolvePage: skipped ancestor lookup in ${c.def.name}:`, (error as Error)?.message ?? error)
+        continue
+      }
+      if (!row) continue
+      // BOTH edges are needed, and neither subsumes the other — the same pairing `publishedAlternates`
+      // uses. The record tag covers every change to the row sitting here, INCLUDING the ones that make it
+      // stop being a crumb: the explicit publish action classifies its write as `before === after` (the
+      // record's current state), so a rename, a `noindex` or an unpublish is invisible in `crumbTags`,
+      // which only ever names where the record is NOW. `<coll>:<id>` is in that write's tag list whatever
+      // the row looks like, so it is what repairs the trail. Captured BEFORE the filters below, so a
+      // draft/noindexed/shadowing row — one that is currently NOT the crumb — still carries the edge that
+      // fires when it goes away.
+      captureRead(c.def.name, row.id)
+      if (publishedOnly && hasStatus && row.status !== 'published') break
+      if (row.seo?.noindex) break
+      const ancestor: PageAncestor = { path: ancestorPath }
+      const title = row.seo?.title || (typeof row.title === 'string' ? row.title : undefined)
+      if (title) ancestor.title = title
+      if (c.def.translatable && row.locale) ancestor.locale = row.locale
+      out.push(ancestor)
+      break
+    }
+  }
+  return out
+}
+
 /**
  * The first page-like record (across all collections, in registration order) whose `path` matches,
  * populated at depth 1 — or null, alongside the collections that could not be read at all. Reuses the
@@ -93,7 +193,15 @@ export function resolvePage(db: BetterSQLite3Database, collections: BuiltCollect
     const { data } = result
     if (data.length) {
       captureRead(c.def.name, (data[0] as { id?: number }).id ?? null)
-      return { page: { collection: c.def.name, page: data[0]!, alternates: publishedAlternates(db, c, data[0]!) }, failed }
+      return {
+        page: {
+          collection: c.def.name,
+          page: data[0]!,
+          alternates: publishedAlternates(db, c, data[0]!),
+          ancestors: publishedAncestors(db, collections, path, locale, publishedOnly),
+        },
+        failed,
+      }
     }
   }
   return { page: null, failed }

package/layers/public/server/utils/preview-token.ts

@@ -0,0 +1,109 @@
+import { randomBytes } from 'node:crypto'
+import type { H3Event } from 'h3'
+
+/**
+ * Short-lived tickets carrying the editor's UNSAVED form state to a real page render. The editor's own
+ * iframe gets unsaved content over postMessage, but an external tab has no parent window to talk to — so
+ * instead of saving (which would publish intent the user never expressed) it mints a ticket and opens
+ * `<url>?kestrel-preview-token=…`. Nothing is written to the DB; the ticket lives in this process only.
+ *
+ * The admin session is the actual gate (both endpoints are admin-only under the default-deny API guard).
+ * The owner binding on top is NOT per-session isolation today: Kestrel has one shared admin credential and
+ * `derivePrincipal` (access layer) never mints more than one admin identity, so every caller that reaches
+ * this store has already been narrowed by `requireAdmin` to the same principal, and `previewOwner()`
+ * resolves to the literal string `'admin'` every time — `t.owner === owner` cannot currently be false for
+ * an admin caller. The binding is kept because it is the seam that makes the check meaningful the moment
+ * (if ever) a per-user identity is added upstream; until then it costs nothing and documents the intent.
+ * Tickets stay readable until they expire — a preview tab may be reloaded — and the store bounds itself in
+ * both directions: a sweep on every mint, and a hard cap that evicts the oldest ticket.
+ *
+ * In-memory by design: previewing is a per-editor, per-minute affair, and a second server instance would
+ * simply re-mint. Nothing durable depends on it.
+ */
+export interface PreviewPayload {
+  collection: string
+  /** The record being previewed, or null for one that has never been saved. */
+  id: number | null
+  locale?: string
+  /** The editor's populated values — the same tree the live-preview bridge posts into the iframe. */
+  values: Record<string, unknown>
+}
+
+export interface PreviewTicket {
+  token: string
+  expiresAt: number
+}
+
+export interface PreviewStore {
+  mint: (owner: string, payload: PreviewPayload) => PreviewTicket
+  read: (token: string, owner: string) => PreviewPayload | null
+  size: () => number
+}
+
+export interface PreviewStoreOptions {
+  ttlMs?: number
+  max?: number
+  now?: () => number
+  randomToken?: () => string
+}
+
+const TTL_MS = 10 * 60 * 1000
+const MAX_TICKETS = 32
+
+export function createPreviewStore(opts: PreviewStoreOptions = {}): PreviewStore {
+  const ttlMs = opts.ttlMs ?? TTL_MS
+  const max = opts.max ?? MAX_TICKETS
+  const now = opts.now ?? Date.now
+  const randomToken = opts.randomToken ?? (() => randomBytes(24).toString('base64url'))
+  // Insertion-ordered, which is what makes "evict the oldest" a single `keys().next()`.
+  const tickets = new Map<string, { owner: string; payload: PreviewPayload; expiresAt: number }>()
+
+  function sweep(at: number): void {
+    for (const [token, t] of tickets) if (t.expiresAt <= at) tickets.delete(token)
+  }
+
+  return {
+    mint(owner, payload) {
+      const at = now()
+      sweep(at)
+      while (tickets.size >= max) tickets.delete(tickets.keys().next().value as string)
+      const token = randomToken()
+      const expiresAt = at + ttlMs
+      tickets.set(token, { owner, payload, expiresAt })
+      return { token, expiresAt }
+    },
+    read(token, owner) {
+      const t = tickets.get(token)
+      if (!t) return null
+      if (t.expiresAt <= now()) {
+        tickets.delete(token)
+        return null
+      }
+      // Bound to the minting owner rather than trusted on token possession alone — inert while every admin
+      // caller resolves to the same owner (see the module docstring), but the check a future per-user
+      // identity would need is already the one being run, not one that would need to be added later.
+      return t.owner === owner ? t.payload : null
+    },
+    size: () => tickets.size,
+  }
+}
+
+/**
+ * Who a ticket belongs to. In production this only ever runs after `requireAdmin(event)` has already
+ * thrown for anyone but the admin principal, and `derivePrincipal` (access layer) always gives that
+ * principal a fixed `userId: 'admin'` — so the first branch always wins and this always returns the
+ * literal `'admin'`. The `role` / `'anonymous'` fallbacks are unreached by any principal shape
+ * `derivePrincipal` produces today; kept as a defensive default rather than a non-null assertion, since
+ * this function has no way to enforce that invariant itself.
+ */
+export function previewOwner(event: H3Event): string {
+  const principal = event.context.principal as { userId?: string | null; role?: string } | undefined
+  return principal?.userId ?? principal?.role ?? 'anonymous'
+}
+
+/** The process-wide store the two `/api/preview` handlers share. */
+let shared: PreviewStore | null = null
+export function usePreviewStore(): PreviewStore {
+  shared ??= createPreviewStore()
+  return shared
+}

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

@@ -28,6 +28,9 @@ export interface WriteClassification {
    *  static file must be pruned on a slug change / unpublish / delete (symmetric to `selfRoute`). */
   oldRoute: string | null
   groupTag: string | null
+  /** Page-path tags for the breadcrumb edge — this record's own path before and/or after the write (both,
+   *  on a rename); empty when it is nobody's crumb step on either side. See `pagePathTag`. */
+  crumbTags: string[]
 }
 
 /** The data tag naming a translation group. `#` keeps it clear of the `<coll>:<id>` record namespace. */
@@ -35,6 +38,27 @@ export function translationGroupTag(coll: string, group: string): string {
   return `${coll}#group:${group}`
 }
 
+/**
+ * The data tag naming a page-like PATH rather than a record — the edge a DESCENDANT's breadcrumb hangs on.
+ *
+ * It has to be the path, because Kestrel has no parent/child relation between pages: `path` is a plain
+ * column, a slug is flat unless an editor types slashes into it, and "descendant" is nothing but a
+ * path-prefix match. So the case that matters most — a page CREATED at `/blog` after `/blog/hello` was
+ * already published — has no record id that anything could have captured beforehand. A path, by contrast,
+ * is knowable before its page exists, so a descendant subscribes to the path it looked in.
+ *
+ * Deliberately locale-LESS: a non-translatable record has no locale to name, and a descendant looking up
+ * `/blog` in its own locale must still be reached when the page that appears there is a locale-less one.
+ * It therefore over-approximates across locales (an `en` `/blog` write also re-renders a `de` descendant
+ * of the same spelling) — extra renders, never a stale page.
+ *
+ * The leading `#` keeps it clear of the `<coll>` and `<coll>:<id>` namespaces (a collection name never
+ * starts with one).
+ */
+export function pagePathTag(path: string): string {
+  return `#path:${path}`
+}
+
 /** What to republish for a write. Routes are resolved from `tags` against the captured deps index. */
 export type Invalidation =
   | { type: 'full' }
@@ -59,6 +83,18 @@ function isPublic(def: WriteCollection, row: Row): boolean {
   return !!row && row.status === 'published'
 }
 
+/**
+ * The path this record contributes as a breadcrumb step, or null when it contributes none. Mirrors
+ * `publishedAncestors` exactly — that lookup skips anything unpublished, `noindex`ed or path-less, so a
+ * record in one of those states is in nobody's trail and its writes owe nobody a re-render.
+ */
+function crumbPath(def: WriteCollection, row: Row): string | null {
+  if (!def.pageLike || !row) return null
+  if (!isPublic(def, row)) return null
+  if ((row.seo as { noindex?: boolean } | null | undefined)?.noindex) return null
+  return typeof row.path === 'string' && row.path ? row.path : null
+}
+
 /** Reduce a before/after row pair (either may be null) to a `WriteClassification`. Pure (routes via the shared `pageRowHref`). */
 export function classifyWrite(def: WriteCollection, before: Row, after: Row, primaryLocale: string, prefixPrimary = false): WriteClassification {
   const status: WriteClassification['status'] = before === null ? 'created' : after === null ? 'deleted' : 'updated'
@@ -81,7 +117,38 @@ export function classifyWrite(def: WriteCollection, before: Row, after: Row, pri
   const group = row?.translationGroup
   const groupTag = typeof group === 'string' && group ? translationGroupTag(def.name, group) : null
 
-  return { collection: def.name, pageLike, status, id, pathChanged, statusChanged, isPublished, wasPublished, selfRoute, oldRoute, groupTag }
+  // Both sides, so a rename repairs the descendants of the OLD path as well as the new one. Deliberately
+  // NOT narrowed to "did the crumb's label actually change": the explicit publish action classifies its
+  // write as before === after (`publish.post.ts` — a re-render of the record's current state), so a diff
+  // would see nothing on the very publish that makes the crumb appear.
+  const crumbTags = [...new Set([crumbPath(def, before), crumbPath(def, after)].filter((p): p is string => p !== null))]
+    .map(pagePathTag)
+
+  return { collection: def.name, pageLike, status, id, pathChanged, statusChanged, isPublished, wasPublished, selfRoute, oldRoute, groupTag, crumbTags }
+}
+
+/**
+ * What the write listener enqueues for a content write. `publishOnSave` (`output.publishOnSave`) is the
+ * documented way back to the pre-2.0 model where a save WAS a publish: with it on, a write plans exactly
+ * what it always did. Off (the default), only removals pass — see `planSaveInvalidation`.
+ */
+export function planWrite(ev: WriteClassification, publishOnSave: boolean): Invalidation {
+  return publishOnSave ? planInvalidation(ev) : planSaveInvalidation(ev)
+}
+
+/**
+ * What a plain SAVE may do to the static output. Saving persists to the DB; writing a page's file is the
+ * explicit publish action's job (`planInvalidation`, driven by `POST /api/publish`), so a save renders
+ * nothing — the live site keeps serving the last published version while the editor works on the next one.
+ *
+ * REMOVAL is the asymmetry, and it is deliberate: an unpublished or deleted record must not keep a live
+ * page, so those two branches act immediately. Their referrer/listing re-renders come along, because a
+ * baked link to a page that just went offline is stale the moment it goes — the same "availability" rule
+ * `planInvalidation` documents, minus everything that would put NEW content on the live site.
+ */
+export function planSaveInvalidation(ev: WriteClassification): Invalidation {
+  const removal = ev.status === 'deleted' || (ev.statusChanged && !ev.isPublished)
+  return removal ? planInvalidation(ev) : { type: 'noop' }
 }
 
 /**
@@ -109,7 +176,9 @@ export function planInvalidation(ev: WriteClassification): Invalidation {
   // Unlike recordTag (dropped on create — no referrer can target a brand-new id), groupTag is included even
   // there: a new sibling still changes every existing member's hreflang set.
   const groupTags = ev.groupTag ? [ev.groupTag] : []
-  const tags = recordTag ? [coll, recordTag, ...groupTags] : [coll, ...groupTags]
+  // Like groupTag, the crumb tags ride EVERY branch including create — a page appearing at an ancestor
+  // path is exactly what a descendant's breadcrumb was waiting for.
+  const tags = recordTag ? [coll, recordTag, ...groupTags, ...ev.crumbTags] : [coll, ...groupTags, ...ev.crumbTags]
   const selfRender = ev.pageLike && ev.selfRoute ? [ev.selfRoute] : []
 
   // DELETE — leaves the collection. Listings re-render, referrers too (their baked link/hreflang now points
@@ -123,7 +192,7 @@ export function planInvalidation(ev: WriteClassification): Invalidation {
   // record re-renders listings + its own route. No referrer can point at a brand-new id, so no `coll:id`.
   if (ev.status === 'created') {
     if (!ev.isPublished) return { type: 'noop' }
-    return { type: 'tags', tags: [coll, ...groupTags], render: selfRender, prune: [] }
+    return { type: 'tags', tags: [coll, ...groupTags, ...ev.crumbTags], render: selfRender, prune: [] }
   }
 
   // UNPUBLISH — leaves the published set. Listings re-render; referrers re-render so their link falls back to

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

@@ -0,0 +1,74 @@
+/**
+ * "Saved but not published": the state a deferred-publish model needs to name. Saving writes the DB,
+ * publishing writes the static file, so the two stamps drift apart on purpose — a record edited after its
+ * page was last published keeps serving the published version until someone publishes again.
+ *
+ * The tolerance is not cosmetic: `publish_status.updated_at` is stored in whole seconds while a record's
+ * `updatedAt` is milliseconds, so the publish that directly followed a save can carry a stamp up to a
+ * second BEHIND it. Without the slack every freshly published page would report unpublished changes.
+ */
+const TOLERANCE_MS = 1000
+
+export function hasPendingChanges(savedAtMs: number | null | undefined, publishedAtMs: number | null | undefined, toleranceMs = TOLERANCE_MS): boolean {
+  // Never published (no status row) → nothing to protect: there is no older artifact this edit could
+  // overtake, so the route is a normal render candidate, not a pending change.
+  if (savedAtMs == null || publishedAtMs == null) return false
+  return savedAtMs > publishedAtMs + toleranceMs
+}
+
+/** The subset of `savedAt` routes whose record moved on after the route's last publish. Pure. */
+export function pendingRoutes(savedAt: Map<string, number>, publishedAt: Map<string, number>): string[] {
+  const out: string[] = []
+  for (const [route, saved] of savedAt) {
+    if (hasPendingChanges(saved, publishedAt.get(route) ?? null)) out.push(route)
+  }
+  return out
+}
+
+export interface HeldRoutes {
+  /** Routes to leave un-rendered: their record is serving an older published version somewhere. */
+  hold: Set<string>
+  /** Previously-published routes that are still the live artifact of a held record — never prune these. */
+  keep: Set<string>
+}
+
+/**
+ * Withholding by RECORD rather than by route string, which is what a rename needs. `pendingRoutes` compares
+ * a route against its own publish stamp, so a renamed record — whose new route has no stamp at all — falls
+ * through the "never published, nothing to protect" carve-out: the unpublished rename gets rendered and the
+ * old route, still the live one, is left looking abandoned to the prune. The carve-out is about a FIRST
+ * deploy having no older version; a rename has one, at the previous route.
+ *
+ * So a record's prior published routes are consulted too: if the record has moved on since the newest of
+ * them, the new route is held back and those prior routes are protected from the prune. A record with no
+ * prior published route keeps the carve-out — otherwise a first deploy would produce an empty site.
+ *
+ * Pure: `routesForTag` is the deps index's lookup, passed in.
+ */
+export function heldRoutes(
+  savedAt: Map<string, number>,
+  publishedAt: Map<string, number>,
+  recordTag: Map<string, string>,
+  routesForTag: (tag: string) => Iterable<string>,
+  toleranceMs = TOLERANCE_MS,
+): HeldRoutes {
+  const hold = new Set<string>()
+  const keep = new Set<string>()
+  for (const [route, saved] of savedAt) {
+    const own = publishedAt.get(route) ?? null
+    if (own != null) {
+      if (hasPendingChanges(saved, own, toleranceMs)) hold.add(route)
+      continue
+    }
+    // No stamp of its own: either genuinely never published, or published under a previous route.
+    const tag = recordTag.get(route)
+    if (!tag) continue
+    const priors = [...routesForTag(tag)].filter((r) => r !== route && publishedAt.has(r))
+    if (!priors.length) continue // first publish of this record — nothing to protect
+    const newest = Math.max(...priors.map((r) => publishedAt.get(r)!))
+    if (!hasPendingChanges(saved, newest, toleranceMs)) continue
+    hold.add(route)
+    for (const prior of priors) keep.add(prior)
+  }
+  return { hold, keep }
+}

package/layers/public/server/utils/publish/publish-runtime.ts

@@ -0,0 +1,28 @@
+import type { PublishQueue } from './queue'
+import type { DepsStore } from './deps'
+
+/**
+ * The process-wide handle on the running publish machinery. The `zz.publish` Nitro plugin owns the queue
+ * and the deps index (it builds the output driver and does the logging), but the explicit publish action —
+ * `POST /api/publish` — has to reach both from inside a request: the queue to enqueue the run, the deps
+ * index to find the routes this record was baked into. Mirrors core's `write-events` registry: module
+ * state, set once at boot.
+ *
+ * `null` wherever the runtime publisher does not run at all (dev, or `output.auto` off). That is not an
+ * error — it is what the endpoint reports back so the editor can say "nothing is generated here" instead
+ * of pretending a publish happened.
+ */
+export interface PublishRuntime {
+  queue: PublishQueue
+  deps: DepsStore
+}
+
+let runtime: PublishRuntime | null = null
+
+export function setPublishRuntime(next: PublishRuntime | null): void {
+  runtime = next
+}
+
+export function usePublishRuntime(): PublishRuntime | null {
+  return runtime
+}

package/layers/public/server/utils/publish/publish-status.ts

@@ -43,6 +43,24 @@ export function renderOutcome(status: number, hasBody: boolean): 'success' | 'er
   return 'skip'
 }
 
+/**
+ * Every route's last successful-or-failed publish time, in ms — the "last published" half of the
+ * saved-vs-published comparison a deferred publish needs. Same missing-table resilience as the writers:
+ * an unmigrated deploy yields an empty map, which reads as "nothing was ever published here" and so
+ * holds nothing back.
+ */
+export function lastPublishedAt(db: BetterSQLite3Database): Map<string, number> {
+  const out = new Map<string, number>()
+  try {
+    for (const row of db.select({ route: publishStatus.route, updatedAt: publishStatus.updatedAt }).from(publishStatus).all()) {
+      if (row.updatedAt instanceof Date) out.set(row.route, row.updatedAt.getTime())
+    }
+  } catch (error) {
+    console.warn('[kestrel] could not read publish status:', (error as Error).message)
+  }
+  return out
+}
+
 /** Clear a route's status row — its static file was pruned (unpublish / delete / slug change), so it is no
  *  longer live. Idempotent; same missing-table resilience as `recordPublishStatus`. */
 export function clearPublishStatus(db: BetterSQLite3Database, route: string): void {