@michaelthielemann/kestrel 1.2.1

package/layers/core/server/utils/defineCollection.ts

@@ -0,0 +1,207 @@
+import { validateFieldLayoutsDeep } from './field-layout'
+
+export type FieldType =
+  | 'text' | 'slug' | 'richtext' | 'number' | 'boolean' | 'datetime'
+  | 'choice' | 'link' | 'media' | 'relation' | 'repeater' | 'json'
+  // Consumer-defined types (registered via `defineFieldType`) — keeps built-in autocomplete while
+  // accepting any registered name.
+  | (string & {})
+
+/** A display string that may be localized per admin language: either a plain string (one language /
+ *  language-agnostic) or a `{ <adminLang>: string }` map resolved against the active admin language
+ *  (falling back to `en`, then any present value). Works for built-in AND consumer-defined collections. */
+export type Localized = string | Record<string, string>
+
+interface BaseFieldDef {
+  required?: boolean
+  default?: unknown
+  translatable?: boolean
+  unique?: boolean
+  /** Add a non-unique DB index on this field's column — for a field frequently FILTERED or SORTED by but
+   *  not unique (e.g. `media.folder`). `unique` already implies an index, so this is only the non-unique case. */
+  index?: boolean
+  /** Editor label, optionally localized per admin language. Defaults to the humanized field key
+   *  (e.g. `siteName` → "Site Name") so the editor label matches the collection-list header. */
+  label?: Localized
+  /** Show this field only when the condition matches other fields' values (see `Condition`). A hidden
+   *  field is exempt from `required` and gets a nullable column; its stored value is left as-is (v1). */
+  condition?: Condition
+  /** The field's previous key. On a schema sync the column is RENAMED (data preserved) instead of being
+   *  dropped + re-added. Remove once applied everywhere. */
+  renamedFrom?: string
+  /** Per-instance read populator override (Pruvious `additional.population`). When set, the field-tree
+   *  walker runs THIS instead of the field type's default populator for this one field — e.g. a relation
+   *  that should project only a couple of columns, or a masked value. Server-only (a function; never
+   *  serialized to the admin). Typed inline (structurally identical to the populate seam's `FieldPopulator`)
+   *  so this foundational, import-free types file needs no dependency on `populate.ts`. */
+  populate?: (
+    bag: Record<string, unknown>,
+    key: string,
+    field: FieldDef,
+    ctx: { depth: number; locale: string; def: CollectionDef },
+    keyMode: 'columns' | 'props',
+  ) => void
+}
+
+export type ConditionScalar = string | number | boolean | null
+
+/** A single operator test against the referenced field's value. Multiple keys are ANDed. */
+export interface ConditionOperator {
+  eq?: ConditionScalar
+  ne?: ConditionScalar
+  gt?: number | string
+  gte?: number | string
+  lt?: number | string
+  lte?: number | string
+  in?: ConditionScalar[]
+  notIn?: ConditionScalar[]
+  /** Case-sensitive `new RegExp(value).test(dep)`; a non-string dependency never matches. */
+  regexp?: string
+  /** `true` matches null/undefined/''/[]; `false` matches a present value. */
+  empty?: boolean
+}
+
+/** A leaf rule: test another field's value. Use `is` (strict-equality shorthand) OR `op`; a bare rule
+ *  (neither) means "present" (non-empty). `field` is a sibling field's key (v1 scope). */
+export interface ConditionRule {
+  field: string
+  is?: ConditionScalar
+  op?: ConditionOperator
+}
+
+/** Field visibility logic. A discriminated tree: leaf `ConditionRule`s combined by explicit
+ *  `and`/`or`/`not` (no overloaded magic keys, so a real field named "and"/"or" never collides). */
+export type Condition =
+  | ConditionRule
+  | { and: Condition[] }
+  | { or: Condition[] }
+  | { not: Condition }
+
+export type LinkType = 'internal' | 'external' | 'email' | 'tel'
+
+export type LinkValue =
+  | { type: 'internal'; collection: string; id: number; hash?: string; label?: string }
+  | { type: 'external'; url: string; label?: string }
+  | { type: 'email'; email: string; label?: string }
+  | { type: 'tel'; tel: string; label?: string }
+
+export type FieldDef =
+  | (BaseFieldDef & { type: 'text'; options?: { minLength?: number; maxLength?: number; multiline?: boolean } })
+  // A url-safe slug (text-backed). `from` = the field key to auto-generate from when left blank; `prefix` is
+  // display-only in the editor widget (e.g. '/galleries/').
+  | (BaseFieldDef & { type: 'slug'; options?: { from?: string; prefix?: string } })
+  | (BaseFieldDef & { type: 'richtext' })
+  // `unit` is a display-only suffix shown after the value in the editor widget (e.g. 'rem'); the stored
+  // value stays a bare number. `units` is reserved for a future selectable-unit variant and is not yet
+  // honoured server-side.
+  | (BaseFieldDef & { type: 'number'; options?: { min?: number; max?: number; integer?: boolean; decimals?: number; unit?: string; units?: string[] } })
+  | (BaseFieldDef & { type: 'boolean' })
+  | (BaseFieldDef & { type: 'datetime'; options?: { precision?: 'date' | 'datetime' | 'time'; range?: boolean } })
+  | (BaseFieldDef & { type: 'choice'; options: { choices: { label: string; value: string }[]; multiple?: boolean; display?: 'select' | 'buttons' | 'checkboxes' } })
+  | (BaseFieldDef & { type: 'link'; options?: { types?: LinkType[]; collections?: string[] } })
+  | (BaseFieldDef & { type: 'media'; options?: { multiple?: boolean; accept?: 'image' | 'any' } })
+  | (BaseFieldDef & { type: 'relation'; relation: { collection: string; many?: boolean; labelField?: string } })
+  | (BaseFieldDef & { type: 'repeater'; options: { fields: Record<string, FieldDef>; fieldLayout?: FieldLayoutDSL } })
+  | (BaseFieldDef & { type: 'json' })
+  // A consumer-defined field type (registered via `defineFieldType`): any other `type` string, with
+  // free-form `options` forwarded to its server descriptor + editor widget.
+  | (BaseFieldDef & { type: string & {}; options?: Record<string, unknown> })
+
+/** The specific `FieldDef` arm for a built-in field `type`; falls back to the full union for consumer
+ *  types (whose arm is the open `type: string & {}`). The `[…] extends [never]` tuple wrap stops the
+ *  conditional from distributing over `never`. */
+export type FieldOf<T extends FieldType> = [Extract<FieldDef, { type: T }>] extends [never]
+  ? FieldDef
+  : Extract<FieldDef, { type: T }>
+
+/** Type-guard narrowing a `FieldDef` to a specific built-in arm. Needed because the open consumer arm
+ *  (`type: string & {}`) makes `type` a non-discriminant, so a bare `f.type === 'x'` won't narrow `f`. */
+export function fieldIs<T extends FieldType>(field: FieldDef, type: T): field is FieldOf<T> {
+  return field.type === type
+}
+
+/** Whether a relation/media field is stored as (and addressed by) a single `<name>Id` FK column —
+ *  true unless it is a many-relation or a multiple-media field. The single source of the `Id`-suffix
+ *  rule shared by column naming (`resolveColumnName`), serialization (the `single` flag), and the editor. */
+export function isSingleRefColumn(field: FieldDef): boolean {
+  return (fieldIs(field, 'relation') && !field.relation.many)
+    || (fieldIs(field, 'media') && !field.options?.multiple)
+}
+
+/**
+ * Author-facing field-layout DSL (resolved by `resolveFieldLayout`). Each entry is one of:
+ *  - a string — a single full-width row (`'title'`), optionally widthed (`'title|50%'`);
+ *  - a string[] — a side-by-side row, equal columns by default, or per-field `field|2` (flex weight) /
+ *    `field|30%` (a CSS length/percent);
+ *  - a single-key object — a named group of rows: `{ 'SEO': [ 'metaTitle', ['a', 'b'] ] }` (one level deep).
+ */
+export type FieldLayoutEntry = string | string[] | Record<string, FieldLayoutEntry[]>
+export type FieldLayoutDSL = FieldLayoutEntry[]
+
+export interface CollectionDef {
+  name: string
+  mode: 'multi' | 'single'
+  /** Per-locale content. Optional — defaults to false (a single, non-localized record set). */
+  translatable?: boolean
+  pageLike?: boolean
+  seo?: boolean
+  blocks?: { enabled: true; allowed?: string[] }
+  status?: boolean
+  /** Which admin editor renders this collection's body (the presentation axis, kept separate from the
+   *  `blocks` schema flag). Defaults to `'blocks'` when `blocks.enabled`, else `'fields'`. Open string:
+   *  extensions register additional editor types (e.g. `'node-graph'`) via `registerCollectionEditor`. */
+  editor?: string
+  fields: Record<string, FieldDef>
+  /** Admin editor layout: rows of fields. A string is its own full-width row; a nested array puts fields
+   *  side by side (equal columns, or `field|2` / `field|30%` for flex weights / CSS lengths); a single-key
+   *  object is a named group `{ 'SEO': [ … ] }`. Fields omitted from the layout append as full-width rows,
+   *  so adding a field never hides it. Absent → today's one-field-per-row. (Deviates from Pruvious, which
+   *  nests this under a `dashboard` wrapper — Kestrel keeps its flat CollectionDef idiom.) */
+  fieldLayout?: FieldLayoutDSL
+  /** Display labels. `new` is the complete, per-locale "create" phrase (e.g. de `'Neue Seite'` /
+   *  `'Neuer Beitrag'`) — supplying the whole phrase sidesteps German gender agreement, which no
+   *  `'Neu {x}'` template can get right. Falls back to a generic phrase from `singular` when absent. */
+  label?: { singular?: Localized; plural?: Localized; new?: Localized }
+  /** Nav/dashboard icon: a UI registry icon name (e.g. `'settings'`) or raw inline SVG markup. Lets
+   *  each collection — including custom ones — be visually distinct in the admin rail. */
+  icon?: string
+  /** Marks a Kestrel-shipped built-in (`pages`, `media`). Built-ins register by default but a consumer
+   *  can disable them via `kestrel: { collections: { <name>: false } }` (config → `KESTREL_COLLECTIONS_<NAME>`
+   *  env → default-on). Ignored for user-defined collections. */
+  builtin?: boolean
+  /** Show this collection in the admin rail (default true). Set `false` for a system/config store — e.g.
+   *  a settings singleton — that a layer manages internally and surfaces (if at all) through its own UI, so
+   *  it never appears as a flat top-level rail item beside the layer's main page. */
+  nav?: boolean
+}
+
+export function defineCollection(def: CollectionDef): CollectionDef {
+  // A pageLike record is governed by the slug engine (required + auto-generated + globally unique route),
+  // which only runs through the multi create/update path — `putSingleton` writes directly. A routable
+  // singleton would silently skip that enforcement, so refuse the combo loudly at definition time.
+  if (def.pageLike && def.mode === 'single') {
+    throw new Error(`[kestrel] pageLike collection "${def.name}" must be mode: 'multi' (a routable record needs the slug engine)`)
+  }
+  // The built-in `blocks` editor body persists to the `content` column, which the write schema only exposes
+  // when blocks are enabled. editor:'blocks' without blocks:{enabled:true} would mount a working page builder
+  // whose every edit is silently dropped on save — refuse the combo loudly at definition time.
+  if (def.editor === 'blocks' && !def.blocks?.enabled) {
+    throw new Error(`[kestrel] collection "${def.name}" sets editor: 'blocks' but is missing blocks: { enabled: true } — its block edits would never persist`)
+  }
+  // Framework tool endpoints share the flat /api/<segment> namespace. A pageLike collection whose name
+  // matches one enters the anonymous public-read set (publicReadableResources) and makes that endpoint
+  // anonymously reachable — e.g. a `links` collection exposes /api/links/resolve, leaking draft slugs.
+  // Refuse the collision loudly. (`media` is served by the generic router, so it is NOT a tool namespace.)
+  if (RESERVED_API_NAMESPACES.has(def.name)) {
+    throw new Error(`[kestrel] collection name "${def.name}" is a reserved framework API namespace — it would shadow /api/${def.name} and leak it into the anonymous public-read set; choose another name`)
+  }
+  // Fail loud at definition time on a bad field layout (unknown/duplicate field, invalid width, malformed
+  // group) — top level plus every nested repeater — so it surfaces at import/startup, not on first render.
+  validateFieldLayoutsDeep(def)
+  return def
+}
+
+const RESERVED_API_NAMESPACES = new Set([
+  'auth', 'blocks', 'collections', 'links', 'publish-status', 'references', 'route',
+  'galleries-secure', 'galleries-secure-proofing',
+])

package/layers/core/server/utils/duplicate.ts

@@ -0,0 +1,162 @@
+import { eq, getTableColumns } from 'drizzle-orm'
+import { createError } from 'h3'
+import type { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3'
+import type { AnySQLiteColumn, AnySQLiteTable } from 'drizzle-orm/sqlite-core'
+import type { BuiltCollection } from './collection-types'
+import { create } from './crud'
+import { slugSourceKey, dedupeSourcePath } from './page-slug'
+import { primaryLocale, prefixPrimaryLocale } from './locale'
+import { allCollections } from './registry'
+import { fieldIs, type FieldOf } from './defineCollection'
+import { slugify } from '../../app/utils/slugify'
+import { resolveColumnName } from '../../../fields/server/field-registry/naming'
+import { isHardRequired } from '../../../fields/server/field-registry/index'
+import { regenerateBlockIds } from '../../../fields/server/utils/block-ids'
+
+type DB = BetterSQLite3Database
+type Row = Record<string, unknown>
+
+/**
+ * Append (or increment) a plain `(copy)` suffix on a title-like string:
+ *   `Foo` → `Foo (copy)` → `Foo (copy 2)` → `Foo (copy 3)` → …
+ * Pure and non-localized; drives BOTH the list label and (for pageLike / slug fields) the derived slug.
+ * When `maxLength` is given (the slug-source field's `options.maxLength`), the BASE is truncated so the
+ * whole `base + suffix` result still fits — so a record at (or within a suffix of) its length limit stays
+ * duplicable instead of tripping create()'s re-validated `.max`. When the maxLength cannot fit even the
+ * suffix on its own, the source text is returned unchanged (no suffix); for a pageLike copy the `-N` route
+ * de-dup then still guarantees a unique slug. The increment rule holds under truncation.
+ */
+export function withCopySuffix(text: string, maxLength?: number): string {
+  const m = /^(.*) \(copy(?: (\d+))?\)$/.exec(text)
+  const base = m ? m[1]! : text
+  const n = (m ? (m[2] ? Number.parseInt(m[2], 10) : 1) : 0) + 1
+  const suffix = n === 1 ? '(copy)' : `(copy ${n})`
+  const full = base ? `${base} ${suffix}` : suffix
+  if (maxLength === undefined || full.length <= maxLength) return full
+  // The suffix alone overflows the budget → drop it (a pageLike copy's `-N` route de-dup still disambiguates).
+  if (suffix.length > maxLength) return text.slice(0, maxLength)
+  // Truncate the base so `base + ' ' + suffix` fits exactly within maxLength (−1 for the joining space).
+  const room = maxLength - suffix.length - 1
+  const truncated = room > 0 ? base.slice(0, room).trimEnd() : ''
+  return truncated ? `${truncated} ${suffix}` : suffix
+}
+
+/** The one field whose verbatim copy CANNOT be reconciled: required + unique + not a slug (a slug re-derives,
+ *  the pageLike path re-derives+de-dupes). Returns its def key, or `undefined` when the collection has none. */
+function blockingUniqueField(c: BuiltCollection): string | undefined {
+  for (const [key, f] of Object.entries(c.def.fields)) {
+    if (f.unique && isHardRequired(f) && f.type !== 'slug') return key
+  }
+  return undefined
+}
+
+/**
+ * Duplicate one record into a NEW draft copy, composing `crud.create()` so validation, the fresh
+ * translationGroup nanoid, the slug de-dup, field transforms, the unique-slug check, the insert AND
+ * `emitWrite` (which rebuilds `record_refs` and drives the publish queue) all come for free — there is NO
+ * parallel insert path. The copy:
+ *   • strips id / timestamps → a fresh PK + timestamps (create() also strips them);
+ *   • drops `translationGroup` → create() mints a new group, so the copy is a LONE row in a brand-new group
+ *     for its single locale (Option A — keeping the group would violate the UNIQUE(group, locale) index);
+ *   • blanks `path` (pageLike) → `resolvePageSlug` re-derives + `-2`/`-3` de-dupes from the suffixed title,
+ *     or — for a pageLike collection with NO slug-source text field — seeds the source's path, de-duped;
+ *   • forces `status: 'draft'` → a copy of a published record is NOT itself published;
+ *   • regenerates every block id → the copy never shares block identity with its source;
+ *   • appends a `(copy)` suffix to the slug-source text field → the label and derived slug read "Foo (copy)";
+ *   • blanks non-required unique fields EXCEPT the slug-source (its `(copy)` suffix already makes it distinct);
+ *   • SHARES referenced media / relations / links verbatim (scalar column values copied, never deep-copied).
+ * Throws: 405 for a singleton · 404 for an unknown id · 422 (naming the field) when a REQUIRED UNIQUE field
+ * that is not the slug/path would collide verbatim (surfaced up-front instead of a raw SQLite 409).
+ */
+export function duplicateRecord(db: DB, c: BuiltCollection, id: number): Row {
+  if (c.def.mode === 'single') {
+    throw createError({ statusCode: 405, statusMessage: 'Cannot duplicate a singleton' })
+  }
+  const blocking = blockingUniqueField(c)
+  if (blocking) {
+    throw createError({ statusCode: 422, statusMessage: `Cannot duplicate: the required unique field "${blocking}" would collide` })
+  }
+
+  const cols = getTableColumns(c.table) as Record<string, AnySQLiteColumn>
+  // RAW row (NOT getOne — no populate): populate nests media/relations into objects that would not round-
+  // trip through the insert schema; the duplicate must copy the stored scalar FKs so the copy SHARES them.
+  const src = db.select().from(c.table as AnySQLiteTable).where(eq(cols.id, id)).get() as Row | undefined
+  if (!src) throw createError({ statusCode: 404, statusMessage: `${c.name} ${id} not found` })
+
+  const body: Row = { ...src }
+  delete body.id
+  delete body.createdAt
+  delete body.updatedAt
+  delete body.translationGroup
+  delete body.path
+  if (c.def.status) body.status = 'draft'
+  if (c.def.blocks?.enabled) body.content = regenerateBlockIds(src.content)
+
+  appendCopySuffix(c, body)
+  blankNonRequiredUniqueFields(db, c, body)
+  seedCopyPath(db, c, src, body)
+
+  return create(db, c, body)
+}
+
+/** Suffix the slug-source text field (the same field `slugSourceValue`/`resolvePageSlug` derive from),
+ *  budgeting the suffix against the field's `options.maxLength` so a record at its length limit stays
+ *  duplicable (create() re-validates the text `.max`). */
+function appendCopySuffix(c: BuiltCollection, body: Row): void {
+  const key = slugSourceKey(c.def)
+  if (!key) return
+  const value = body[key]
+  if (typeof value !== 'string') return
+  const field = c.def.fields[key]
+  const maxLength = field && fieldIs(field, 'text') ? field.options?.maxLength : undefined
+  body[key] = withCopySuffix(value, maxLength)
+}
+
+/** A unique field can't be copied verbatim (it would collide). A unique `slug` is re-derived from the
+ *  now-suffixed source AND de-duped with a `-N` suffix against existing rows (so duplicating the SAME
+ *  record twice yields `foo-copy`, then `foo-copy-2` — a plain slug field has no pageLike `-N` path dedup
+ *  of its own, so two copies would otherwise collide on create's hard unique-slug check). Any OTHER unique
+ *  field (guaranteed non-hard-required by the pre-flight — its column is nullable) falls to NULL, which
+ *  SQLite permits many of. The slug-SOURCE text field is EXEMPT even when itself `unique`: its `(copy)`
+ *  suffix already distinguishes it, so nulling it would be silent data loss (and, for a pageLike
+ *  collection, leave resolvePageSlug no title → a 400). */
+function blankNonRequiredUniqueFields(db: DB, c: BuiltCollection, body: Row): void {
+  const slugSource = slugSourceKey(c.def)
+  const cols = getTableColumns(c.table) as Record<string, AnySQLiteColumn>
+  for (const [key, f] of Object.entries(c.def.fields)) {
+    if (!f.unique || key === slugSource) continue
+    const { jsKey } = resolveColumnName(key, f)
+    if (fieldIs(f, 'slug')) body[jsKey] = dedupedCopySlug(db, c, cols, key, f, body)
+    else body[jsKey] = null
+  }
+}
+
+/** The de-duped slug for a copy: slugify the (already `(copy)`-suffixed) `from` source, else the copied
+ *  slug value, then append `-2`/`-3`/… until it is free. Empty base → undefined (let create's transform try). */
+function dedupedCopySlug(db: DB, c: BuiltCollection, cols: Record<string, AnySQLiteColumn>, key: string, f: FieldOf<'slug'>, body: Row): string | undefined {
+  const { jsKey } = resolveColumnName(key, f)
+  const from = f.options?.from
+  const source = from ? body[from] : undefined
+  const base = typeof source === 'string' && source ? slugify(source)
+    : typeof body[jsKey] === 'string' ? slugify(body[jsKey] as string) : ''
+  if (!base) return undefined
+  let candidate = base
+  for (let n = 2; db.select({ id: cols.id }).from(c.table as AnySQLiteTable).where(eq(cols[jsKey]!, candidate)).get(); n++) {
+    candidate = `${base}-${n}`
+  }
+  return candidate
+}
+
+/** For a pageLike collection with NO slug-source text field, create()'s auto-gen branch has no title to
+ *  derive a slug from (and duplicate blanked `path`), so seed the copy's `path` off the SOURCE row's own
+ *  explicit path — de-duped to a free route — which create()'s explicit branch then accepts. A no-op for
+ *  every other collection (the suffixed title drives the slug) and when the source carries no usable path. */
+function seedCopyPath(db: DB, c: BuiltCollection, src: Row, body: Row): void {
+  if (!c.def.pageLike || slugSourceKey(c.def)) return
+  const path = dedupeSourcePath(db, c, src, {
+    collections: allCollections(),
+    primary: primaryLocale(),
+    prefixPrimary: prefixPrimaryLocale(),
+  })
+  if (path) body.path = path
+}

package/layers/core/server/utils/field-layout.ts

@@ -0,0 +1,125 @@
+import type { CollectionDef, FieldDef, FieldLayoutDSL, Localized } from './defineCollection'
+
+/**
+ * Field layout: the pure, node-testable resolver that turns the author DSL (`CollectionDef.fieldLayout` /
+ * a repeater's `options.fieldLayout`) into a normalized, JSON-safe structure the admin renders. It runs at
+ * definition time (fail-loud) and again in serialize (the wire copy); no runtime deps — only the erased
+ * type imports above.
+ */
+
+/** A neutral column track: a flex WEIGHT (a plain number → the UI renders it as an `fr` unit) or an
+ *  explicit LENGTH (`'30%'`, `'12rem'`, …). The engine stays free of CSS-grid vocabulary — the UI layer
+ *  (Layout.vue) is the single place that turns tracks into a `grid-template-columns` value. */
+export type LayoutTrack = number | string
+
+/** A rendered row: the fields (in source/reading order) and one column track per field. */
+export interface LayoutRow {
+  kind: 'row'
+  fields: string[]
+  /** One track per field (positionally aligned); default weight `1`. Never an author-supplied CSS string. */
+  tracks: LayoutTrack[]
+}
+/** A single named group (one level deep): a labelled `<fieldset>` wrapping stacked rows. */
+export interface LayoutGroup {
+  kind: 'group'
+  label: Localized
+  rows: LayoutRow[]
+}
+export type LayoutNode = LayoutRow | LayoutGroup
+
+// Width grammar, strict allow-lists so a field width can NEVER inject arbitrary CSS into the grid template.
+const WEIGHT = /^\d+(?:\.\d+)?$/ //                  bare number -> `<n>fr` (flex weight)
+const LENGTH = /^\d+(?:\.\d+)?(?:fr|%|px|rem|em)$/ // an explicit CSS length/percent (allow-listed units)
+
+interface Cell {
+  field: string
+  /** A flex weight (number) or an explicit length (string), or undefined → default weight 1. */
+  track?: LayoutTrack
+}
+
+/** Parse one `'name'` / `'name|2'` / `'name|30%'` token into its field + optional grid track width. */
+function parseToken(tok: unknown, ctx: string): Cell {
+  if (typeof tok !== 'string') throw new Error(`[kestrel] ${ctx}: a row field must be a string (got ${typeof tok})`)
+  const parts = tok.split('|')
+  if (parts.length > 2) throw new Error(`[kestrel] ${ctx}: "${tok}" has more than one "|"`)
+  const field = parts[0]!.trim()
+  if (!field) throw new Error(`[kestrel] ${ctx}: empty field name in "${tok}"`)
+  if (parts.length === 1) return { field }
+  const w = parts[1]!.trim()
+  // A zero (or, defensively, negative) track collapses the cell to a sliver via `.ui-field-cell { min-inline-size:0 }`
+  // — silently hiding it. Only a strictly positive value is a real column, so require it alongside the grammar.
+  // Strictly positive AND finite: a huge digit run (`'9'.repeat(400)`) parses to Infinity, which passes
+  // the digit-only grammar but is not a real column and serializes to JSON `null` on the wire — reject it.
+  const positive = (tok: string) => { const n = parseFloat(tok); return n > 0 && Number.isFinite(n) }
+  // A bare number or an `fr` length are both FLEX WEIGHTS → emit a plain number (no CSS unit in the wire).
+  if (WEIGHT.test(w) && positive(w)) return { field, track: parseFloat(w) }
+  if (LENGTH.test(w) && positive(w)) return { field, track: w.endsWith('fr') ? parseFloat(w) : w }
+  throw new Error(`[kestrel] ${ctx}: invalid width "${w}" for "${field}" (use a positive number weight like "2", or a length like "30%"/"12rem"/"200px")`)
+}
+
+/**
+ * Resolve a layout DSL against the field set. A lone string is a full-width row; a string[] is a
+ * side-by-side row; a single-key object is a named group of rows (one level, never nested). Fields not
+ * mentioned append as full-width rows at the end (declaration order) so adding a field never hides it.
+ * Throws on an unknown/duplicate field, a bad width, or a malformed group.
+ */
+export function resolveFieldLayout(dsl: FieldLayoutDSL, fieldKeys: string[], ctx: string): LayoutNode[] {
+  const known = new Set(fieldKeys)
+  const seen = new Set<string>()
+  const nodes: LayoutNode[] = []
+
+  const use = (field: string) => {
+    if (!known.has(field)) throw new Error(`[kestrel] ${ctx}: unknown field "${field}" in the layout`)
+    if (seen.has(field)) throw new Error(`[kestrel] ${ctx}: field "${field}" appears more than once in the layout`)
+    seen.add(field)
+  }
+  const toRow = (entry: string | unknown[]): LayoutRow => {
+    const tokens = Array.isArray(entry) ? entry : [entry]
+    if (!tokens.length) throw new Error(`[kestrel] ${ctx}: a row must contain at least one field`)
+    const cells = tokens.map((t) => parseToken(t, ctx))
+    cells.forEach((c) => use(c.field))
+    return { kind: 'row', fields: cells.map((c) => c.field), tracks: cells.map((c) => c.track ?? 1) }
+  }
+
+  for (const entry of dsl) {
+    if (typeof entry === 'string' || Array.isArray(entry)) {
+      nodes.push(toRow(entry))
+      continue
+    }
+    // A single-key object → a named group of rows.
+    const names = Object.keys(entry)
+    if (names.length !== 1) throw new Error(`[kestrel] ${ctx}: a group must have exactly one name (got ${names.length})`)
+    const label = names[0]!
+    const inner = entry[label]!
+    if (!Array.isArray(inner) || !inner.length) throw new Error(`[kestrel] ${ctx}: group "${label}" needs at least one row`)
+    const rows = inner.map((r) => {
+      if (typeof r !== 'string' && !Array.isArray(r)) throw new Error(`[kestrel] ${ctx}: group "${label}" may not nest another group (one level only)`)
+      return toRow(r)
+    })
+    nodes.push({ kind: 'group', label, rows })
+  }
+
+  // Any field missing from the layout appends as a full-width row (declaration order) — never hidden.
+  for (const field of fieldKeys) if (!seen.has(field)) nodes.push({ kind: 'row', fields: [field], tracks: [1] })
+  return nodes
+}
+
+/**
+ * Validate every field layout a definition carries — the collection's own plus each (nested) repeater's —
+ * for the throwing side effect. Called from `defineCollection()` so a bad layout fails at import/startup.
+ */
+export function validateFieldLayoutsDeep(def: CollectionDef): void {
+  if (def.fieldLayout) resolveFieldLayout(def.fieldLayout, Object.keys(def.fields), `collection "${def.name}"`)
+  walkRepeaterLayouts(def.fields, '')
+}
+
+function walkRepeaterLayouts(fields: Record<string, FieldDef>, prefix: string): void {
+  for (const [key, field] of Object.entries(fields)) {
+    if (field.type !== 'repeater') continue
+    // Structural narrow (avoids a runtime import of `fieldIs` — keeps this file's only runtime edge one-way).
+    const options = (field as Extract<FieldDef, { type: 'repeater' }>).options
+    const ctx = `${prefix}repeater "${key}"`
+    if (options.fieldLayout) resolveFieldLayout(options.fieldLayout, Object.keys(options.fields), ctx)
+    walkRepeaterLayouts(options.fields, `${ctx} > `)
+  }
+}

package/layers/core/server/utils/filter-predicate.ts

@@ -0,0 +1,101 @@
+import { eq, ne, lt, lte, gt, gte, sql, or, isNull, type SQL } from 'drizzle-orm'
+import { createError } from 'h3'
+import type { AnySQLiteColumn } from 'drizzle-orm/sqlite-core'
+import { escapeLike } from './sql'
+import type { FilterKind, FilterOp } from '../../app/utils/filter-ops'
+
+/** Coerce a (stringified) filter value to the target COLUMN's storage type before the predicate. Keyed on
+ *  the resolved Drizzle column (not the builtin def type-name) so a CUSTOM field type backed by a
+ *  boolean/number column coerces too. parseFilter stringifies every query param, and drizzle maps any
+ *  non-empty string (incl. 'false') to 1 for a boolean column, so an uncoerced boolean filter matches the
+ *  wrong rows. (Owns this here — its single home — so both crud.list and filterCondition share it without a
+ *  crud↔predicate import cycle.) */
+export function coerceFilterValue(col: { getSQLType(): string; mode?: string }, value: unknown): unknown {
+  if (col.mode === 'boolean') return value === true || value === 'true' || value === '1'
+  // A timestamp column stores a Date and drizzle maps it via Date.getTime(); a raw string/number reaches
+  // mapToDriverValue and throws `value.getTime is not a function` → an unhandled 500 (reachable
+  // unauthenticated on any public collection). Coerce to a Date; an unparseable value is a clean 400.
+  if (col.mode === 'timestamp' || col.mode === 'timestamp_ms') {
+    const d = new Date(typeof value === 'number' ? value : String(value))
+    if (Number.isNaN(d.getTime())) throw createError({ statusCode: 400, statusMessage: `Invalid timestamp filter value: ${String(value)}` })
+    return d
+  }
+  const sqlType = col.getSQLType()
+  if ((sqlType === 'integer' || sqlType === 'real') && typeof value === 'string') {
+    const n = Number(value)
+    return Number.isFinite(n) ? n : value
+  }
+  return value
+}
+
+/** JSON-array membership: EXISTS an element of the array column equal to the (typed) value. Fully
+ *  parameterised — only the schema-derived column identifier is interpolated, never user input — matching
+ *  media/usages.ts:25. A `stringSet` (multi choice) matches string members; an `idSet` (many relation/media)
+ *  matches an integer id (a non-numeric filter value is a clean 400, not a mismatch that silently matches
+ *  nothing). */
+function member(col: AnySQLiteColumn, kind: 'stringSet' | 'idSet', raw: string): SQL {
+  let value: string | number = raw
+  if (kind === 'idSet') {
+    // Number('') / Number('  ') are 0 (finite) and Number('1e3') is 1000 — none is a valid id token. Require a
+    // plain (optionally signed) integer so a blank/garbage filter is a clean 400, not a silent empty match.
+    const t = raw.trim()
+    if (t === '' || !/^-?\d+$/.test(t)) throw createError({ statusCode: 400, statusMessage: `Invalid id filter value: ${raw}` })
+    value = Number(t)
+  }
+  return sql`EXISTS (SELECT 1 FROM json_each(${sql.identifier(col.name)}) WHERE value = ${value})`
+}
+
+/**
+ * The exclusive end of the DAY a date-only value names, or null when the rule does not apply. A datetime
+ * column stores an instant, but `YYYY-MM-DD` (what a date picker and the `filter[c][op]=YYYY-MM-DD` wire
+ * contract carry) names a whole day: compared against that day's midnight, "on or before" would drop the
+ * day itself and "after" would return it. The next UTC day works for both storages — a `Date` for a
+ * timestamp column, and a lexicographically correct string for a TEXT one ('2026-07-25T16:00' < '2026-07-26').
+ */
+function exclusiveDayEnd(kind: FilterKind, raw: string): string | null {
+  if (kind !== 'datetime' || !/^\d{4}-\d{2}-\d{2}$/.test(raw)) return null
+  const d = new Date(`${raw}T00:00:00Z`)
+  // A non-existent calendar date is left to the normal coercion rather than widened: '2026-13-01' is
+  // unparseable (a clean 400 on a timestamp column) and '2026-02-31' rolls forward three days, so shifting
+  // it would silently ask a different question than the URL states.
+  if (Number.isNaN(d.getTime()) || d.toISOString().slice(0, 10) !== raw) return null
+  d.setUTCDate(d.getUTCDate() + 1)
+  return d.toISOString().slice(0, 10)
+}
+
+/**
+ * Build the WHERE predicate for ONE already-validated filter clause (the caller allow-lists `kind`/`op`).
+ * Every user value crosses as a drizzle bound param; the only interpolation is `sql.identifier(col.name)`
+ * (schema-derived, never user input) — injection-safe, matching picker.ts / usages.ts.
+ *
+ * The json_each membership and LIKE ESCAPE are SQLite-specific but consistent with the existing query code
+ * and the SQLite-only engine; a future Postgres query dialect would have to supply @>/ILIKE variants here
+ * (a loud compile failure, never a silent mis-query). NOTE: `contains` on text/richtext matches the STORED
+ * string — for richtext that is the HTML source, so 'p' can hit a '<p>' tag (documented caveat; a stripped
+ * shadow column / FTS index is a later enhancement).
+ */
+export function filterCondition(col: AnySQLiteColumn, kind: FilterKind, op: FilterOp, raw: string): SQL {
+  switch (op) {
+    case 'eq': return eq(col, coerceFilterValue(col, raw))
+    // SQL <> excludes NULL by three-valued logic; "is not X" must still surface an uncategorised (NULL) row.
+    case 'ne': { const v = coerceFilterValue(col, raw); return col.notNull ? ne(col, v) : or(ne(col, v), isNull(col))! }
+    case 'lt': return lt(col, coerceFilterValue(col, raw))
+    // Only the two bounds that would fall on the wrong side of a whole day get the boundary swap; `lt` /
+    // `gte` already mean "before the day" / "from the day on" when compared against its midnight.
+    case 'lte': {
+      const end = exclusiveDayEnd(kind, raw)
+      return end ? lt(col, coerceFilterValue(col, end)) : lte(col, coerceFilterValue(col, raw))
+    }
+    case 'gt': {
+      const end = exclusiveDayEnd(kind, raw)
+      return end ? gte(col, coerceFilterValue(col, end)) : gt(col, coerceFilterValue(col, raw))
+    }
+    case 'gte': return gte(col, coerceFilterValue(col, raw))
+    case 'contains':
+      if (kind === 'stringSet' || kind === 'idSet') return member(col, kind, raw)
+      // text / richtext substring (SQLite LIKE is ASCII case-insensitive); LIKE metacharacters escaped.
+      return sql`${col} like ${`%${escapeLike(raw)}%`} escape '\\'`
+    case 'notContains':
+      return sql`NOT ${member(col, kind as 'stringSet' | 'idSet', raw)}`
+  }
+}

package/layers/core/server/utils/http.ts

@@ -0,0 +1,50 @@
+import { createError, getRouterParam, type H3Event } from 'h3'
+import { getCollection } from './registry'
+import type { BuiltCollection } from './collection-types'
+
+export function getCollectionOr404(name: string): BuiltCollection {
+  const collection = getCollection(name)
+  if (!collection) throw createError({ statusCode: 404, statusMessage: `Unknown collection: ${name}` })
+  return collection
+}
+
+export function requireCollection(event: H3Event): BuiltCollection {
+  return getCollectionOr404(getRouterParam(event, 'collection') as string)
+}
+
+export function parseId(raw: string): number {
+  if (!/^[1-9][0-9]*$/.test(raw)) throw createError({ statusCode: 400, statusMessage: `Invalid id: ${raw}` })
+  return Number(raw)
+}
+
+export function requireId(event: H3Event): number {
+  return parseId(getRouterParam(event, 'id') as string)
+}
+
+/**
+ * Parse a list of record ids — from a bulk request body (`number[]`) or a comma-separated query string
+ * (`?ids=1,2,3`). Dedupes (preserving first-seen order) and rejects, with a clean 400: an empty list, any
+ * element that is not a positive integer, or more than `cap` ids. The cap is enforced up front on the raw
+ * input, so an oversized body is rejected without being fully walked and allocated. Shared by the `bulk`
+ * command endpoint and the batched referrer lookup so both enforce the same id contract.
+ */
+export function parseIdList(raw: unknown, cap: number): number[] {
+  const parts: unknown[] = Array.isArray(raw)
+    ? raw
+    : typeof raw === 'string'
+      ? raw.split(',').map((s) => s.trim()).filter(Boolean)
+      : []
+  // Bound the work before parsing: reject an oversized input up front rather than iterating and building a
+  // Set of a million ids just to 400. `parts.length` is an upper bound on the deduped result, so this also
+  // subsumes any post-dedupe cap — a raw list that fits here can never exceed `cap` after deduping.
+  if (parts.length > cap) throw createError({ statusCode: 400, statusMessage: `Too many ids (max ${cap})` })
+  const ids: number[] = []
+  const seen = new Set<number>()
+  for (const p of parts) {
+    const n = typeof p === 'number' ? p : typeof p === 'string' ? Number(p) : Number.NaN
+    if (!Number.isInteger(n) || n <= 0) throw createError({ statusCode: 400, statusMessage: `Invalid id: ${String(p)}` })
+    if (!seen.has(n)) { seen.add(n); ids.push(n) }
+  }
+  if (!ids.length) throw createError({ statusCode: 400, statusMessage: 'ids must be a non-empty list' })
+  return ids
+}