@michaelthielemann/kestrel 1.2.1

package/layers/auth/server/utils/session.ts

@@ -0,0 +1,85 @@
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto'
+import { currentSessionEpoch } from './session-epoch'
+
+export function deriveSigningKey(rawSecret: string, passwordHash?: string, epoch = 0): string {
+  // The `epoch` is a server-side revocation counter: bumping it (on logout / force-logout) changes the key
+  // so every previously-issued token fails verification immediately — the stateless model's "hard logout".
+  return createHmac('sha256', rawSecret).update('kestrel-session-v1').update(passwordHash ?? '').update(`e${epoch}`).digest('base64url')
+}
+
+export function signSession(secret: string, expMs: number): string {
+  const payload = Buffer.from(JSON.stringify({ exp: expMs })).toString('base64url')
+  const sig = createHmac('sha256', secret).update(payload).digest('base64url')
+  return `${payload}.${sig}`
+}
+
+export function verifySession(secret: string, value: string | undefined, nowMs: number): { valid: boolean; exp?: number } {
+  if (!value || typeof value !== 'string') return { valid: false }
+  const dot = value.indexOf('.')
+  if (dot <= 0 || dot === value.length - 1) return { valid: false }
+  const payload = value.slice(0, dot)
+  const sig = value.slice(dot + 1)
+  const expected = createHmac('sha256', secret).update(payload).digest('base64url')
+  const sigBuf = Buffer.from(sig)
+  const expBuf = Buffer.from(expected)
+  if (sigBuf.length !== expBuf.length || !timingSafeEqual(sigBuf, expBuf)) return { valid: false }
+  let exp: unknown
+  try {
+    exp = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8')).exp
+  } catch {
+    return { valid: false }
+  }
+  if (typeof exp !== 'number' || exp <= nowMs) return { valid: false }
+  return { valid: true, exp }
+}
+
+/**
+ * Sliding-expiry decision: refresh the session cookie once its remaining lifetime drops below HALF the
+ * idle window. Activity within the window keeps the session alive (each refresh resets exp to now+maxAge);
+ * inactivity longer than the window lets it expire → the admin must log in again. The halfway threshold
+ * bounds Set-Cookie churn to at most once per half-window instead of on every request.
+ */
+export function shouldRefreshSession(exp: number, nowMs: number, maxAgeMs: number): boolean {
+  return exp - nowMs < maxAgeMs / 2
+}
+
+let devSecret: string | undefined
+
+export interface SessionSettings {
+  secret: string
+  maxAge: number
+  secureCookies: boolean
+  cookieName: string
+}
+
+export function sessionSettings(): SessionSettings {
+  // Treat anything that isn't an EXPLICIT dev signal as production for these safeguards, so a deployment
+  // that simply omits NODE_ENV (a common slip when launching `.output/server/index.mjs`) is hardened —
+  // not silently downgraded to dev, which would tolerate a missing secret + non-Secure cookies. Vitest
+  // sets NODE_ENV=test; KESTREL_DEV=1 is an explicit escape hatch for other dev contexts.
+  const explicitDev = process.env.NODE_ENV === 'development' || process.env.NODE_ENV === 'test' || process.env.KESTREL_DEV === '1'
+  const isProd = !explicitDev
+  const secureCookies = process.env.KESTREL_SECURE_COOKIES !== 'false'
+  if (isProd && !secureCookies) {
+    throw new Error('KESTREL_SECURE_COOKIES=false is not allowed in production')
+  }
+  const rawMaxAge = Number(process.env.KESTREL_SESSION_MAX_AGE)
+  const maxAge = Number.isFinite(rawMaxAge) && rawMaxAge > 0 ? rawMaxAge : 604800
+  let secret = process.env.KESTREL_SESSION_SECRET
+  if (!secret) {
+    if (isProd) throw new Error('KESTREL_SESSION_SECRET is required in production')
+    if (!devSecret) {
+      devSecret = randomBytes(32).toString('base64url')
+      console.warn('[kestrel auth] KESTREL_SESSION_SECRET not set — using a random per-process dev secret; sessions reset on restart')
+    }
+    secret = devSecret
+  } else if (isProd && Buffer.byteLength(secret) < 32) {
+    throw new Error('KESTREL_SESSION_SECRET must be at least 32 bytes in production')
+  }
+  return {
+    secret: deriveSigningKey(secret, process.env.KESTREL_ADMIN_PASSWORD_HASH, currentSessionEpoch()),
+    maxAge,
+    secureCookies,
+    cookieName: secureCookies ? '__Host-kestrel_session' : 'kestrel_session',
+  }
+}

package/layers/collections/nuxt.config.ts

@@ -0,0 +1 @@
+export default defineNuxtConfig({})

package/layers/collections/server/collections/pages.ts

@@ -0,0 +1,19 @@
+import { buildCollection } from '../../../fields/server/utils/buildCollection'
+import { defineCollection } from '../../../core/server/utils/defineCollection'
+
+const built = buildCollection(defineCollection({
+  name: 'pages',
+  mode: 'multi',
+  translatable: true,
+  pageLike: true,
+  seo: true,
+  blocks: { enabled: true },
+  status: true,
+  builtin: true,
+  label: { singular: { en: 'Page', de: 'Seite' }, plural: { en: 'Pages', de: 'Seiten' }, new: { en: 'New Page', de: 'Neue Seite' } },
+  icon: 'file-text',
+  fields: { title: { type: 'text', required: true } },
+}))
+
+export const pages = built.table
+export default built

package/layers/collections/server/plugins/01.register.ts

@@ -0,0 +1,32 @@
+import collections from '#kestrel/collections'
+import blocks from '#kestrel/blocks'
+import { registerBlock, type BlockDef } from '../../../fields/server/utils/defineBlock'
+import { ensureBuilt } from '../../../fields/server/utils/buildCollection'
+import { resolveServerKestrel, serverRuntimeConfig } from '../../../core/server/utils/server-config'
+import { collectionEnabled } from '../../../core/server/schema/bootstrap'
+import type { CollectionDef } from '../../../core/server/utils/defineCollection'
+import type { BuiltCollection } from '../../../core/server/utils/collection-types'
+
+// Auto-discovered collection files default-export either a plain CollectionDef (the common consumer
+// form, `export default defineCollection(…)`) or an already-built collection (advanced). `ensureBuilt`
+// normalizes both so the registry only ever holds BuiltCollections.
+//
+// NOTE on ordering: the `01.` prefix sorts only WITHIN this (collections) layer. Nitro runs plugins by
+// layer-then-filename, so this plugin does NOT run second — in-repo it runs LAST (after core's
+// 00.migrate/02.schema-sync/03.record-refs), and the cross-layer order differs again for an
+// `extends: ['@michaelthielemann/kestrel']` consumer. That is safe ONLY because nothing reads the registry at plugin init:
+// migrate/schema-sync read the `#kestrel/collections` virtual directly, and the ref/cleanup/publish
+// plugins register deferred listeners. Keep that invariant — do not add an init-time allCollections() read.
+export default defineNitroPlugin(() => {
+  for (const block of blocks as BlockDef[]) registerBlock(block)
+  // Built-in collections (`pages`, `media`) register by default but can be disabled per consumer via
+  // `kestrel: { collections: { <name>: false } }`. Prefer the value the kestrel module put on runtimeConfig
+  // (the consumer's `kestrel: {}`); fall back to Kestrel's own resolved config for non-Nitro / dev callers.
+  const toggles = (serverRuntimeConfig()?.kestrel?.collections ?? resolveServerKestrel().collections) as Record<string, boolean>
+  for (const collection of collections as (CollectionDef | BuiltCollection)[]) {
+    const built = ensureBuilt(collection)
+    // The shared predicate (schema/bootstrap) — the schema engine gates on exactly the same rule.
+    if (!collectionEnabled(built.def, toggles)) continue
+    registerCollection(built)
+  }
+})

package/layers/collections/server/plugins/02.register-relation-populate.ts

@@ -0,0 +1,17 @@
+import { registerFieldPopulator } from '../../../core/server/utils/populate'
+import { buildRelationFieldPopulator, skipMissing } from '../utils/populate-relations'
+import { getCollection } from '../../../core/server/utils/registry'
+import { getOne } from '../../../core/server/utils/crud'
+
+// Expand relation fields to the fully-populated related record(s) under `$<name>` at read time (depth ≥ 1).
+// The related read is published-only (a draft target is skipped, never leaked to a public read), tolerates a
+// stale/deleted id (getOne 404 → null via `skipMissing`, other errors propagate — fail-loud), and runs at
+// `depth - 1`, so `populateRow` bails at 0 and cycles terminate. Registered per-type; the shared field-tree
+// walker (fields layer) dispatches it.
+export default defineNitroPlugin(() => {
+  registerFieldPopulator('relation', buildRelationFieldPopulator((collection, id, depth, locale) => {
+    const built = getCollection(collection)
+    if (!built) return null
+    return skipMissing(() => getOne(useDb(), built, id, depth, locale, true) as Record<string, unknown>)
+  }))
+})

package/layers/collections/server/utils/populate-relations.ts

@@ -0,0 +1,66 @@
+import { fieldIs } from '../../../core/server/utils/defineCollection'
+import type { FieldPopulator } from '../../../core/server/utils/populate'
+import { memoDuringPrerender } from '../../../core/server/utils/prerender-memo'
+import { memoResolver } from '../../../core/server/utils/resolve-scope'
+
+/** Fetches a related record FULLY populated (its own media / links / nested relations resolved), or null
+ *  when the id is stale / deleted / draft. Injected so the populator stays pure + unit-testable; the plugin
+ *  wires the real `getOne`. `depth` is the ALREADY-decremented depth for the related read (the cycle guard). */
+export type ResolveRecord = (
+  collection: string,
+  id: number,
+  depth: number,
+  locale: string,
+) => Record<string, unknown> | null
+
+/**
+ * Run a related-record fetch, mapping `getOne`'s 404 (a stale / deleted / draft target — the intended
+ * "skip this reference" signal) to `null`, but letting ANY OTHER error propagate. Swallowing every error
+ * here would drop a relation on a real fault (a DB error, a downstream populator throwing on malformed
+ * stored data) while the page still renders + records `success` — violating fail-loud. Pure + testable.
+ */
+export function skipMissing(fetch: () => Record<string, unknown>): Record<string, unknown> | null {
+  try {
+    return fetch()
+  } catch (e) {
+    if ((e as { statusCode?: number })?.statusCode === 404) return null
+    throw e
+  }
+}
+
+/**
+ * The `relation` field populator: expands a relation id (single, `${name}Id` in columns / bare in props)
+ * or id array (many, always bare) into the fully-populated related record(s) under a `$<name>` sibling,
+ * leaving the raw id column intact — so write round-trips and the admin relation-picker keep working.
+ * Stale / deleted / draft ids are skipped (single → null, many → filtered out) so one bad reference never
+ * fails the whole read. The related read passes `ctx.depth - 1`; `populateRow` bails at depth 0, so a
+ * relation cycle terminates. Registered per-type via `registerFieldPopulator('relation', …)`; the shared
+ * field-tree walker drives it over top-level fields, block props, slots, and repeater entries.
+ */
+export function buildRelationFieldPopulator(resolveRecord: ResolveRecord): FieldPopulator {
+  // The same target (collection+id+depth+locale) is resolved once — build-wide during a generate run
+  // (memoDuringPrerender), request-/publish-run-wide via the resolve scope (which also budgets the
+  // distinct fan-out of one live request and replays read-tags on hits, so publish deps stay complete).
+  // memoResolver OUTERMOST: the per-scope budget verdict must stay scope-local. If memoDuringPrerender
+  // wrapped memoResolver, a build-wide memoize would cache a budget-skip `null` and poison every later
+  // page of a `nuxt generate`. With this order the build-wide memo only ever caches REAL resolver results.
+  const key = (collection: string, id: number, depth: number, locale: string) => `rel:${collection}:${id}:${depth}:${locale}`
+  const resolve = memoResolver(memoDuringPrerender(resolveRecord, key), key)
+  return (bag, key, field, ctx, keyMode) => {
+    if (!fieldIs(field, 'relation')) return
+    const collection = field.relation.collection
+    const depth = ctx.depth - 1
+    if (field.relation.many) {
+      const ids = bag[key]
+      if (Array.isArray(ids)) {
+        bag['$' + key] = ids
+          .filter((n): n is number => typeof n === 'number')
+          .map((id) => resolve(collection, id, depth, ctx.locale))
+          .filter((r): r is Record<string, unknown> => r != null)
+      }
+    } else {
+      const id = bag[keyMode === 'columns' ? `${key}Id` : key]
+      if (typeof id === 'number') bag['$' + key] = resolve(collection, id, depth, ctx.locale)
+    }
+  }
+}

package/layers/core/app/utils/bulk-actions.ts

@@ -0,0 +1,9 @@
+// The batch operations the bulk endpoint accepts — the single source of truth shared by the server
+// handler (`bulk.post.ts`) and any client that builds a bulk request. Pure, so the allow-list is
+// unit-testable without a Nitro context.
+export const BULK_ACTIONS = ['delete', 'publish', 'unpublish', 'duplicate'] as const
+export type BulkAction = typeof BULK_ACTIONS[number]
+
+export function isBulkAction(value: unknown): value is BulkAction {
+  return typeof value === 'string' && (BULK_ACTIONS as readonly string[]).includes(value)
+}

package/layers/core/app/utils/filter-ops.ts

@@ -0,0 +1,98 @@
+import type { SerializedField } from '../../server/utils/serialize-collection' // type-only, erased client-side
+
+/**
+ * The single shared source of truth for list filtering: which normalized "kind" a field/meta column maps
+ * to, and which operators that kind allows. Both the server (validation + predicate building) and the admin
+ * UI (operator select + typed value control) import this — so the allowed-operators-per-field-type table is
+ * defined exactly once. Kept in `core/app/utils` (the server-and-client shared home) and free of any DB or
+ * column-naming detail: each side maps its own column keys.
+ */
+
+export type FilterOp = 'eq' | 'ne' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'notContains'
+
+/**
+ * A field's storage/semantics bucket for filtering. `text`/`richtext` do substring LIKE; `stringSet`/`idSet`
+ * are JSON-array membership (multi choice / many relation+media); `ref` is a single FK id (eq/ne only);
+ * `enum`/`boolean` are equality-only; `number`/`datetime` support the full comparison set.
+ */
+export type FilterKind = 'number' | 'text' | 'datetime' | 'boolean' | 'enum' | 'ref' | 'richtext' | 'stringSet' | 'idSet'
+
+const CMP = ['eq', 'ne', 'lt', 'lte', 'gt', 'gte'] as const
+
+export const OPS_BY_KIND: Record<FilterKind, readonly FilterOp[]> = {
+  number: CMP,
+  datetime: CMP,
+  text: ['eq', 'ne', 'contains'],
+  richtext: ['contains'], // `contains` matches the stored HTML SOURCE (searching 'p' can hit a '<p>' tag) —
+  //                          a stripped shadow column / FTS index is a later enhancement (documented caveat).
+  boolean: ['eq', 'ne'],
+  enum: ['eq', 'ne'],
+  ref: ['eq', 'ne'], // a single relation/media FK id — lt/gt on an id is meaningless.
+  stringSet: ['contains', 'notContains'],
+  idSet: ['contains', 'notContains'],
+}
+
+/** The operator a column's filter row defaults to in the admin UI. `datetime` defaults to `gte` ("on or
+ *  after") — `eq` on a millisecond timestamp practically never matches, so it made the filter useless. The
+ *  admin always emits the operator explicitly, so this does NOT change the wire parser's separate
+ *  absent-operator default (a bare `filter[field]` still parses as `eq`, URLs round-trip unchanged). */
+export const DEFAULT_OP: Record<FilterKind, FilterOp> = {
+  number: 'eq', datetime: 'gte', text: 'eq', boolean: 'eq', enum: 'eq', ref: 'eq',
+  richtext: 'contains', stringSet: 'contains', idSet: 'contains',
+}
+
+const ALL_OPS = new Set<string>(['eq', 'ne', 'lt', 'lte', 'gt', 'gte', 'contains', 'notContains'])
+
+/** Whether a raw wire token is a known operator at all (parse-time guard → a clean 400 for garbage). */
+export const isFilterOp = (s: string): s is FilterOp => ALL_OPS.has(s)
+
+/** Whether `op` is allowed for a column of this kind (list-time guard → a clean 400, never a 500). */
+export const opAllowed = (kind: FilterKind, op: FilterOp): boolean => OPS_BY_KIND[kind].includes(op)
+
+/**
+ * The wire key for a filter clause: `filter[field]` or `filter[field][op]`. `[^\]]+` keeps the field/op
+ * tokens bracket-free; the optional second group is the operator (absent → `eq`, so a bare
+ * `filter[status]=x` stays backward compatible). Defined ONCE here (the shared client+server home) so the
+ * admin URL parser (`parseListQuery`) and the server wire parser (`parseFilter`) use exactly one regex.
+ */
+export const FILTER_RE = /^filter\[([^\]]+)\](?:\[([^\]]+)\])?$/
+
+/**
+ * The FilterKind for a field, or `null` when it is not filterable (link / json / repeater / range-datetime).
+ * Unknown consumer types fall back to the conservative `text` (equality + substring on their scalar column).
+ */
+export function fieldFilterKind(f: SerializedField): FilterKind | null {
+  switch (f.type) {
+    case 'text':
+    case 'slug':
+      return 'text'
+    case 'richtext':
+      return 'richtext'
+    case 'number':
+      return 'number'
+    case 'boolean':
+      return 'boolean'
+    case 'datetime':
+      return f.options?.range ? null : 'datetime'
+    case 'choice':
+      return f.options?.multiple ? 'stringSet' : 'enum'
+    case 'relation':
+    case 'media':
+      return f.single ? 'ref' : 'idSet'
+    case 'link':
+    case 'json':
+    case 'repeater':
+      return null
+    default:
+      return 'text'
+  }
+}
+
+/** The FilterKind of each filterable meta/system column (keyed by its wire key). */
+export const META_FILTER_KIND: Record<string, FilterKind> = {
+  id: 'number',
+  path: 'text',
+  status: 'enum',
+  createdAt: 'datetime',
+  updatedAt: 'datetime',
+}

package/layers/core/app/utils/list-limits.ts

@@ -0,0 +1,27 @@
+// The single source of truth for collection-list page sizes and, derived from them, the bulk-operation id
+// cap. Lives in `core/app/utils` (the established server+client shared home — same as `filter-ops.ts`) so
+// the admin list UI, the `list()` query engine, and the `bulk` endpoint all agree on ONE set of limits
+// instead of each hardcoding its own.
+
+/** The page sizes offered in the list's per-page selector. */
+export const PER_PAGE_OPTIONS = [25, 50, 100, 250, 500] as const
+
+/** The page size a list falls back to when none (or a garbage value) is supplied. */
+export const DEFAULT_PER_PAGE = 25
+
+/** The largest page a single list request may return — also the ceiling `clampPerPage` clamps to. */
+export const MAX_PER_PAGE = 500
+
+/** Coerce an untrusted page size to a sane integer: a non-finite input (undefined / NaN / Infinity / a
+ *  non-numeric string) falls back to `DEFAULT_PER_PAGE`; anything else is floored and clamped to
+ *  `[1, MAX_PER_PAGE]`. Guards against `LIMIT NaN` (which SQLite binds as "no limit") — an unauthenticated
+ *  cap-bypass / DoS lever. */
+export function clampPerPage(n: unknown): number {
+  const v = Number(n)
+  if (!Number.isFinite(v)) return DEFAULT_PER_PAGE
+  return Math.min(MAX_PER_PAGE, Math.max(1, Math.floor(v)))
+}
+
+/** A bulk op can never carry more ids than one page can show (you select what you can see), so the id cap
+ *  is DERIVED from the max page size, not guessed. */
+export const MAX_BULK_IDS = MAX_PER_PAGE

package/layers/core/app/utils/locale-path.ts

@@ -0,0 +1,12 @@
+/**
+ * The public route path for a page row: other locales are prefixed with `/<locale>`; the primary locale
+ * is unprefixed unless `prefixPrimary` is set (then it is prefixed too, root `/` → `/<primary>`). Single
+ * source of truth for the URL scheme shared by the prerender routes, the sitemap, `populate-links`, the
+ * `[...slug].vue` resolution, the slug-uniqueness check, and the admin SEO preview. Pure, so it is
+ * unit-testable and safe to import from both server and app code.
+ */
+export function localePath(path: string, locale: string, primaryLocale: string, prefixPrimary = false): string {
+  const p = path.startsWith('/') ? path : `/${path}`
+  if (locale === primaryLocale && !prefixPrimary) return p
+  return p === '/' ? `/${locale}` : `/${locale}${p}`
+}

package/layers/core/app/utils/slugify.ts

@@ -0,0 +1,16 @@
+/**
+ * Turn arbitrary text (a record title) into a url-safe slug: lowercase, fold diacritics to ASCII
+ * (`Über` → `uber`, `Café` → `cafe`) via NFKD + combining-mark removal, then collapse every run of
+ * non-`[a-z0-9]` into a single hyphen and trim the ends. Letters with no ASCII fold (ß, CJK, …) act as
+ * separators — Kestrel does NO language-specific transliteration, so the result is predictable. Returns
+ * `''` for blank / symbol-only input (the caller decides: fall back to the manual slug, or reject). Pure.
+ */
+export function slugify(input: string): string {
+  if (typeof input !== 'string') return ''
+  return input
+    .normalize('NFKD')
+    .replace(/\p{M}/gu, '') // strip combining diacritical marks left by NFKD (é → e, ü → u)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}

package/layers/core/modules/auto-discovery/extract-block.ts

@@ -0,0 +1,176 @@
+import { readFileSync } from 'node:fs'
+import { basename } from 'node:path'
+import { parse } from '@babel/parser'
+import type { FieldDef } from '../../server/utils/defineCollection'
+import * as factoryModule from '../../../fields/app/utils/field-factories'
+import { KESTREL_FIELD } from '../../../fields/app/utils/field-factories'
+
+/** The extracted block definition (shape mirrors `BlockDef`, kept structural so this build-time module
+ *  needs no `layers/fields` runtime import). */
+export interface ExtractedBlock {
+  name: string
+  fields: Record<string, FieldDef>
+  slots?: string[]
+  label?: unknown
+  icon?: string
+  image?: string
+}
+
+// Only the callable factories are injected into the schema-eval scope (exclude the KESTREL_FIELD symbol).
+const FACTORIES: Record<string, unknown> = Object.fromEntries(
+  Object.entries(factoryModule).filter(([, v]) => typeof v === 'function'),
+)
+// The factory functions themselves, to catch an uncalled factory (`heading: textField` vs `textField()`).
+const FACTORY_SET = new Set(Object.values(FACTORIES))
+
+/** `Hero.vue` → `hero`, `BoxedContainer.vue` → `boxedContainer` (camel-case; `BlockRenderer` pascal-cases it
+ *  back to the `Blocks<Name>` component). */
+export function blockNameFromFile(fileBase: string): string {
+  const name = fileBase.replace(/\.vue$/, '')
+  return name.charAt(0).toLowerCase() + name.slice(1)
+}
+
+/** The raw `<script setup>` source. `setup` is matched in ANY attribute position (`<script setup lang="ts">`
+ *  and `<script lang="ts" setup>` are both valid), so a plain `<script>` block (no `setup` word) is skipped.
+ *  (A real Vite build could use `@vue/compiler-sfc parse` for full robustness — e.g. a `</script>` inside a
+ *  string literal; a scoped match is adequate + dependency-light here.) */
+function scriptSetup(sfc: string, where: string): string {
+  const m = sfc.match(/<script\b[^>]*\bsetup\b[^>]*>([\s\S]*?)<\/script>/)
+  if (!m) throw new Error(`${where}: a Kestrel block SFC must have a <script setup> block`)
+  return m[1]
+}
+
+interface Node { type: string; start: number; end: number; [k: string]: unknown }
+
+/** Peel the wrappers a macro call is commonly written behind so the CallExpression underneath is reached:
+ *  a TS as-cast / satisfies (`defineProps({…}) as T`), a non-null assertion (`defineProps({…})!`), and
+ *  parentheses. */
+function unwrapExpr(node: unknown): Record<string, unknown> | undefined {
+  let n = node as Record<string, unknown> | undefined
+  while (n && (n.type === 'TSAsExpression' || n.type === 'TSSatisfiesExpression' || n.type === 'TSNonNullExpression' || n.type === 'ParenthesizedExpression')) {
+    n = n.expression as Record<string, unknown> | undefined
+  }
+  return n
+}
+
+/** If `call` resolves to `<macro>(…)`, its first arg node + whether it carried a type parameter
+ *  (`defineProps<T>()`, unsupported — no runtime schema). Also looks INSIDE `withDefaults(defineProps(…), …)`
+ *  — the most common props idiom — so that form is not silently extracted as an empty schema. */
+function macroInCall(call: unknown, macro: string): { arg?: Node; hasTypeParam: boolean } | undefined {
+  const n = unwrapExpr(call)
+  if (n?.type !== 'CallExpression') return undefined
+  const callee = n.callee as Record<string, unknown> | undefined
+  if (callee?.type === 'Identifier' && callee.name === macro) {
+    return { arg: (n.arguments as Node[])[0], hasTypeParam: !!(n.typeParameters || n.typeArguments) }
+  }
+  // withDefaults(defineProps(…), { … }) — recurse into its arguments to find the wrapped macro call.
+  if (callee?.type === 'Identifier' && callee.name === 'withDefaults') {
+    for (const a of (n.arguments as unknown[]) ?? []) {
+      const hit = macroInCall(a, macro)
+      if (hit) return hit
+    }
+  }
+  return undefined
+}
+
+/** The FIRST TOP-LEVEL `<macro>(…)` call — a bare `defineBlock({…})` (ExpressionStatement), a
+ *  `const props = defineProps({…})` (VariableDeclaration init, incl. `export const` and wrapper forms).
+ *  Vue's macros are top-level by contract, so scanning only `program.body` (not a deep DFS) means a call
+ *  nested in a helper function can't shadow it. */
+function macroCall(ast: unknown, macro: string): { arg?: Node; hasTypeParam: boolean } | undefined {
+  const body = (ast as { program?: { body?: unknown[] } }).program?.body
+  if (!Array.isArray(body)) return undefined
+  for (const raw of body as Array<Record<string, unknown>>) {
+    // Unwrap `export const props = …` → the VariableDeclaration it wraps.
+    const stmt = raw.type === 'ExportNamedDeclaration' && raw.declaration ? (raw.declaration as Record<string, unknown>) : raw
+    if (stmt.type === 'ExpressionStatement') {
+      const hit = macroInCall(stmt.expression, macro)
+      if (hit) return hit
+    } else if (stmt.type === 'VariableDeclaration') {
+      for (const d of (stmt.declarations as Array<Record<string, unknown>>) ?? []) {
+        const hit = macroInCall(d.init, macro)
+        if (hit) return hit
+      }
+    }
+  }
+  return undefined
+}
+
+function evalObjectExpr(content: string, node: Node, scope: Record<string, unknown>, where: string): Record<string, unknown> {
+  const src = content.slice(node.start, node.end)
+  const names = Object.keys(scope)
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-implied-eval, no-new-func
+    const fn = new Function(...names, `return (${src})`)
+    const out = fn(...names.map((k) => scope[k]))
+    if (!out || typeof out !== 'object') throw new Error('expected an object literal')
+    return out as Record<string, unknown>
+  } catch (e) {
+    throw new Error(
+      `${where}: could not evaluate the block declaration. Field/block args must be self-contained literals + ` +
+        `field-factory calls (no imported constants, computed values, or TS type-args). Cause: ${(e as Error).message}`,
+    )
+  }
+}
+
+/**
+ * Extract a `BlockDef` from a block SFC's source: `defineProps({ … field factories … })` → `fields`,
+ * `defineBlock({ label, slots, icon })` → metadata, `name` ← filename. Static (no component execution): the
+ * `defineProps`/`defineBlock` argument object-literals are sliced from source and evaluated with the field
+ * factories in scope; each field's `[KESTREL_FIELD]` is lifted into the schema.
+ */
+export function extractBlockDef(sfcSource: string, fileBase: string): ExtractedBlock {
+  const name = blockNameFromFile(fileBase)
+  const content = scriptSetup(sfcSource, fileBase)
+  let ast: ReturnType<typeof parse>
+  try {
+    ast = parse(content, { sourceType: 'module', plugins: ['typescript'] })
+  } catch (e) {
+    throw new Error(`${fileBase}: could not parse <script setup> — ${(e as Error).message}`)
+  }
+
+  const props = macroCall(ast, 'defineProps')
+  if (props?.hasTypeParam && !props.arg) {
+    throw new Error(`${fileBase}: use the runtime form defineProps({ … }) with field factories, not defineProps<T>() — the type-only form carries no schema`)
+  }
+  const propsObj = props?.arg ? evalObjectExpr(content, props.arg, FACTORIES, fileBase) : {}
+
+  const block = macroCall(ast, 'defineBlock')
+  const meta = block?.arg ? evalObjectExpr(content, block.arg, {}, fileBase) : {}
+
+  const fields: Record<string, FieldDef> = {}
+  for (const [key, value] of Object.entries(propsObj)) {
+    const carried = value && typeof value === 'object' ? (value as Record<symbol, unknown>)[KESTREL_FIELD] : undefined
+    if (carried === undefined) {
+      // An UNCALLED field factory (`heading: textField` instead of `textField()`) evaluates to the factory
+      // function itself — catch that common slip loudly rather than silently dropping the field.
+      if (typeof value === 'function' && FACTORY_SET.has(value)) {
+        throw new Error(`${fileBase}: prop "${key}" is a field factory that was not called — write ${(value as { name?: string }).name ?? 'xField'}({ … })`)
+      }
+      // Otherwise it's a plain (display-only) Vue prop (e.g. `media: Object`, the server-resolved $media bag
+      // BlockRenderer passes) — not part of the block schema. A misspelled factory throws at eval time above.
+      continue
+    }
+    const def = carried as FieldDef & { default?: unknown }
+    if (typeof def.default === 'function') {
+      // The registry is inlined as JSON (renderBlockRegistry) — a function default would be silently dropped.
+      throw new Error(`${fileBase}: prop "${key}" has a function \`default\` — block field defaults must be JSON-serializable literals`)
+    }
+    fields[key] = carried as FieldDef
+  }
+
+  const out: ExtractedBlock = { name, fields }
+  if (meta.label !== undefined) out.label = meta.label
+  if (Array.isArray(meta.slots) && meta.slots.length) out.slots = meta.slots as string[]
+  if (typeof meta.icon === 'string') out.icon = meta.icon
+  if (typeof meta.image === 'string') out.image = meta.image
+  return out
+}
+
+/** The `#kestrel/blocks` virtual body: extract each block SFC and inline the definitions as JSON data
+ *  (the block registry is plain, JSON-safe data — no imports needed beyond the field-type side effect the
+ *  caller prepends). */
+export function renderBlockRegistry(vuePaths: string[]): string {
+  const defs = vuePaths.map((p) => extractBlockDef(readFileSync(p, 'utf8'), basename(p)))
+  return `export default ${JSON.stringify(defs)}`
+}

package/layers/core/modules/auto-discovery/index.ts

@@ -0,0 +1,44 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { addComponentsDir, addTypeTemplate, createResolver, defineNuxtModule } from '@nuxt/kit'
+import { collectBlockSfcs, collectDefinitions, renderRegistry } from './scan'
+import { renderBlockRegistry } from './extract-block'
+
+export default defineNuxtModule({
+  meta: { name: 'kestrel-auto-discovery' },
+  setup(_options, nuxt) {
+    const roots = nuxt.options._layers.map((layer) => layer.cwd)
+    // The `#kestrel/*` registries are Nitro VIRTUAL modules (runtime only) — tsc can't see their shape, so
+    // server code importing them would be `Cannot find module`. Register the ambient declarations into BOTH
+    // the Nitro and Nuxt tsconfigs so the typecheck resolves them.
+    const { resolve } = createResolver(import.meta.url)
+    addTypeTemplate({ filename: 'types/kestrel-virtual.d.ts', src: resolve('./virtual.d.ts') }, { nitro: true, nuxt: true })
+
+    // Blocks are authored as single `.vue` files under each layer's `app/blocks/` — the SFC is BOTH the
+    // schema source (extracted at build into `#kestrel/blocks`) AND the display component. Register the dir
+    // so `app/blocks/Hero.vue` resolves as the global `BlocksHero` that the public BlockRenderer renders.
+    for (const root of roots) {
+      const dir = join(root, 'app/blocks')
+      if (existsSync(dir)) addComponentsDir({ path: dir, prefix: 'Blocks', global: true, pathPrefix: false })
+    }
+
+    nuxt.hook('nitro:config', (nitro) => {
+      nitro.virtual ||= {}
+      // Consumer field types register as a side effect on import, and the schema engine builds a table the
+      // moment a collection/block module loads. So the collections + blocks registries import the field-type
+      // registry FIRST — guaranteeing custom types are registered before any column / validator is built.
+      nitro.virtual['#kestrel/field-types'] = () =>
+        renderRegistry(collectDefinitions(roots, 'server/field-types'))
+      nitro.virtual['#kestrel/collections'] = () =>
+        `import '#kestrel/field-types'\n` + renderRegistry(collectDefinitions(roots, 'server/collections'))
+      // Extract each `app/blocks/*.vue` into a plain BlockDef inlined as JSON (no per-file imports needed).
+      nitro.virtual['#kestrel/blocks'] = () =>
+        `import '#kestrel/field-types'\n` + renderBlockRegistry(collectBlockSfcs(roots))
+      // Standalone (non-collection) tables: each layer's `server/schema-tables/*.ts` default-exports one
+      // drizzle table (media → folders, public → publish_deps/publish_status; consumers can add their own).
+      // The schema engine consumes this instead of core hardcoding upper-layer tables.
+      nitro.virtual['#kestrel/schema-tables'] = () =>
+        renderRegistry(collectDefinitions(roots, 'server/schema-tables'))
+    })
+  },
+})