@michaelthielemann/kestrel 1.2.1

package/layers/admin/app/utils/block-tree.ts

@@ -0,0 +1,214 @@
+import type { SerializedBlock } from '../../../core/server/utils/serialize-collection'
+import { reorder } from '../../../ui/app/utils/reorder'
+import { initialValues } from './edit-form'
+
+// Pure, immutable operations over a nested block tree (`content`), addressed by each block's stable
+// `id` rather than a positional index — this is what lets a single shared selection + one fields pane
+// edit a block at ANY depth: every op walks the whole tree by id and rebuilds only the path to it. No
+// Vue here — fully unit-testable.
+
+export interface BlockRow {
+  id: string
+  type: string
+  props: Record<string, unknown>
+  slots?: Record<string, unknown>
+}
+
+type GenId = () => string
+
+/** Stable config + id-addressed operations for the tree pane, threaded through the recursion as one
+ *  object. Lives here (not in the SFC) so the component, the editor shell, and tests can share the type. */
+export interface BlockTreeCtx {
+  byName: Record<string, SerializedBlock>
+  allowedTypes: SerializedBlock[]
+  ops: {
+    select: (id: string | null) => void
+    add: (parentId: string | null, slotName: string | null, type: string) => void
+    remove: (id: string) => void
+    move: (id: string, dir: -1 | 1) => void
+    duplicate: (id: string) => void
+  }
+}
+
+/** A seeded blank block of `type`: fresh id + props defaulted from the type's field schema. */
+export function blankBlock(type: string, schemas: Record<string, SerializedBlock>, genId: GenId): BlockRow {
+  return { id: genId(), type, props: initialValues(schemas[type]?.fields ?? {}) }
+}
+
+/** Deep-clone a block subtree with fresh ids at every level (duplicate never shares an id or a ref). */
+export function cloneBlockTree(b: BlockRow, genId: GenId): BlockRow {
+  const copy: BlockRow = { ...b, id: genId(), props: JSON.parse(JSON.stringify(b.props ?? {})) }
+  if (b.slots) {
+    copy.slots = Object.fromEntries(
+      Object.entries(b.slots).map(([name, arr]) => [name, Array.isArray(arr) ? (arr as BlockRow[]).map((c) => cloneBlockTree(c, genId)) : arr]),
+    )
+  }
+  return copy
+}
+
+export interface Found {
+  block: BlockRow
+  /** The array that directly contains the block. */
+  siblings: BlockRow[]
+  index: number
+  /** The id of the block whose slot contains this one, or null at the root level. */
+  parentId: string | null
+  /** The slot name this block lives in, or null at the root level. */
+  slotName: string | null
+}
+
+/** Locate a block anywhere in the tree by id (with its container + position), or null. */
+export function findInTree(blocks: BlockRow[], id: string): Found | null {
+  function walk(arr: BlockRow[], parentId: string | null, slotName: string | null): Found | null {
+    for (let i = 0; i < arr.length; i++) {
+      const b = arr[i]!
+      if (b.id === id) return { block: b, siblings: arr, index: i, parentId, slotName }
+      if (b.slots) {
+        for (const [name, sub] of Object.entries(b.slots)) {
+          if (Array.isArray(sub)) {
+            const hit = walk(sub as BlockRow[], b.id, name)
+            if (hit) return hit
+          }
+        }
+      }
+    }
+    return null
+  }
+  return walk(blocks, null, null)
+}
+
+/** Immutably transform the block with `id` (block → new block), rebuilding ONLY the path to it; every
+ *  untouched block AND array keeps its reference. Returning the original `blocks` when nothing changed is
+ *  what makes the recursive `next !== sub` a correct change-detector (a bare `.map` always allocates, so it
+ *  would rebuild every slot-bearing block in the tree on any edit). */
+function updateBlock(blocks: BlockRow[], id: string, fn: (b: BlockRow) => BlockRow): BlockRow[] {
+  let changed = false
+  const out = blocks.map((b) => {
+    if (b.id === id) { changed = true; return fn(b) }
+    if (!b.slots) return b
+    const mapped = withMappedSlots(b)
+    if (mapped !== b) changed = true
+    return mapped
+  })
+  return changed ? out : blocks
+  function withMappedSlots(b: BlockRow): BlockRow {
+    let changed = false
+    const slots: Record<string, unknown> = {}
+    for (const [name, sub] of Object.entries(b.slots!)) {
+      if (Array.isArray(sub)) {
+        const next = updateBlock(sub as BlockRow[], id, fn)
+        if (next !== sub) changed = true
+        slots[name] = next
+      } else slots[name] = sub
+    }
+    return changed ? { ...b, slots } : b
+  }
+}
+
+/** Immutably transform the ARRAY that directly contains `id` (array+index → new array); every untouched
+ *  block AND array keeps its reference (same same-ref-when-unchanged rule as `updateBlock`). */
+function updateContaining(blocks: BlockRow[], id: string, fn: (arr: BlockRow[], index: number) => BlockRow[]): BlockRow[] {
+  const idx = blocks.findIndex((b) => b.id === id)
+  if (idx !== -1) return fn(blocks, idx)
+  let changed = false
+  const out = blocks.map((b) => {
+    if (!b.slots) return b
+    let slotChanged = false
+    const slots: Record<string, unknown> = {}
+    for (const [name, sub] of Object.entries(b.slots)) {
+      if (Array.isArray(sub)) {
+        const next = updateContaining(sub as BlockRow[], id, fn)
+        if (next !== sub) slotChanged = true
+        slots[name] = next
+      } else slots[name] = sub
+    }
+    if (!slotChanged) return b
+    changed = true
+    return { ...b, slots }
+  })
+  return changed ? out : blocks
+}
+
+export function updatePropById(blocks: BlockRow[], id: string, key: string, value: unknown): BlockRow[] {
+  return updateBlock(blocks, id, (b) => ({ ...b, props: { ...b.props, [key]: value } }))
+}
+
+/** Remove the block with `id` from wherever it lives. */
+export function removeById(blocks: BlockRow[], id: string): BlockRow[] {
+  return updateContaining(blocks, id, (arr, i) => arr.filter((_, j) => j !== i))
+}
+
+/** Where selection should move when the block with `id` is removed: previous sibling, else next, else
+ *  the parent (null at the root). Computed against the tree BEFORE removal. */
+export function removalRetarget(blocks: BlockRow[], id: string): string | null {
+  const f = findInTree(blocks, id)
+  if (!f) return null
+  if (f.index > 0) return f.siblings[f.index - 1]!.id
+  if (f.index < f.siblings.length - 1) return f.siblings[f.index + 1]!.id
+  return f.parentId
+}
+
+/** Move the block with `id` one step within its container (`dir` -1 up / +1 down); clamps at the edges. */
+export function moveById(blocks: BlockRow[], id: string, dir: -1 | 1): BlockRow[] {
+  return updateContaining(blocks, id, (arr, i) => {
+    const to = i + dir
+    if (to < 0 || to >= arr.length) return arr
+    return reorder(arr, i, to)
+  })
+}
+
+/** Duplicate the block with `id` (fresh ids throughout) right after it; returns the new tree + new id. */
+export function duplicateById(blocks: BlockRow[], id: string, genId: GenId): { tree: BlockRow[]; newId: string } {
+  let newId = ''
+  const tree = updateContaining(blocks, id, (arr, i) => {
+    const copy = cloneBlockTree(arr[i]!, genId)
+    newId = copy.id
+    const next = [...arr]
+    next.splice(i + 1, 0, copy)
+    return next
+  })
+  return { tree, newId }
+}
+
+/** Append a seeded block of `type` at the root (`parentId` null) or into a parent's slot; returns the
+ *  new tree + the new block's id. */
+export function addBlock(
+  blocks: BlockRow[],
+  parentId: string | null,
+  slotName: string | null,
+  type: string,
+  schemas: Record<string, SerializedBlock>,
+  genId: GenId,
+): { tree: BlockRow[]; newId: string } {
+  const block = blankBlock(type, schemas, genId)
+  if (parentId === null || slotName === null) return { tree: [...blocks, block], newId: block.id }
+  const tree = updateBlock(blocks, parentId, (parent) => {
+    const cur = Array.isArray(parent.slots?.[slotName]) ? (parent.slots![slotName] as BlockRow[]) : []
+    return { ...parent, slots: { ...(parent.slots ?? {}), [slotName]: [...cur, block] } }
+  })
+  return { tree, newId: block.id }
+}
+
+/** Ids of every block that itself has an error OR has a descendant with one (ancestor roll-up), for
+ *  tree badges. `directIds` are the blocks the error map keys directly. */
+export function errorBearingIds(blocks: BlockRow[], directIds: Set<string>): Set<string> {
+  const out = new Set<string>()
+  function walk(arr: BlockRow[]): boolean {
+    let any = false
+    for (const b of arr) {
+      let descendantHasError = false
+      if (b.slots) {
+        for (const sub of Object.values(b.slots)) {
+          if (Array.isArray(sub) && walk(sub as BlockRow[])) descendantHasError = true
+        }
+      }
+      if (directIds.has(b.id) || descendantHasError) {
+        out.add(b.id)
+        any = true
+      }
+    }
+    return any
+  }
+  walk(blocks)
+  return out
+}

package/layers/admin/app/utils/collection-ops.ts

@@ -0,0 +1,44 @@
+// Wire shapes for the collection batch endpoint, shared by the ops composable and the delete dialog.
+// Mirrors media/app/utils/ops.ts: one definition, no drift between the caller and the confirm UI.
+
+/** The four batch actions the command endpoint accepts (a row action is a bulk op with one id). */
+export type BatchAction = 'delete' | 'publish' | 'unpublish' | 'duplicate'
+
+/** POST /api/{collection}/bulk response. For `duplicate`, `ids` are the CREATED rows. */
+export interface BulkResult {
+  action: BatchAction
+  count: number
+  ids: number[]
+}
+
+/** GET /api/references/referrers?ids=1,2,3 response: id -> how many other records reference it.
+ *  `checked` is false when the index lookup itself failed, in which case `counts` is empty because nothing
+ *  could be read — NOT because nothing links to the selection. */
+export interface ReferrerCounts {
+  counts: Record<string, number>
+  checked: boolean
+}
+
+/** The pre-delete summary shown in the confirm dialog: how many rows, and how many of them other
+ *  records still link to (aggregated from the referrer counts). */
+export interface BatchDeleteReport {
+  /** How many rows are about to be deleted. */
+  count: number
+  /** How many of those rows are referenced by at least one other record. */
+  referencedCount: number
+  /** Per-id breakdown for the referenced rows (id + inbound referrer count), in input order. */
+  referenced: { id: number; referrers: number }[]
+  /** Whether the referrer lookup actually ran. `false` means the check FAILED (not "none found"), so
+   *  the dialog must warn that inbound links are unverified rather than imply a safe delete. */
+  checked: boolean
+}
+
+/** Fold the referrer-count map into a delete report — pure, so it is unit-testable without a network.
+ *  `checked` is the lookup's own outcome and is carried through untouched: an empty `counts` is ambiguous
+ *  on its own, and only this flag tells the dialog whether it may claim nothing links to the selection. */
+export function buildDeleteReport(ids: number[], counts: Record<string, number>, checked: boolean): BatchDeleteReport {
+  const referenced = ids
+    .map((id) => ({ id, referrers: Number(counts[String(id)] ?? 0) }))
+    .filter((r) => r.referrers > 0)
+  return { count: ids.length, referencedCount: referenced.length, referenced, checked }
+}

package/layers/admin/app/utils/dead-refs.ts

@@ -0,0 +1,30 @@
+// Client-side shaping of the per-record dead-reference map (the `/dead-refs` endpoint payload) into the
+// sets the editor renders: which block nodes carry a stale reference (fed through `errorBearingIds` for
+// the tree roll-up, exactly like block errors) and which field keys are stale at a given location. Pure
+// + Vue-free so it unit-tests directly (happy-dom can't render the teleported field widgets).
+
+/** One stale reference a record holds, with its field/block location + why it is dead. Wire shape of the
+ *  server's `LocatedDeadRef`; kept here so the admin client doesn't import the server (drizzle) module. */
+export interface DeadRef {
+  field: string
+  blockId?: string
+  collection: string
+  id: number
+  reason: 'missing' | 'unpublished'
+}
+
+/** Block-node ids that DIRECTLY hold a dead reference — feed into `errorBearingIds` for the tree roll-up. */
+export function deadBlockIds(refs: DeadRef[]): Set<string> {
+  const out = new Set<string>()
+  for (const r of refs) if (r.blockId) out.add(r.blockId)
+  return out
+}
+
+/** Field keys with a dead reference at a location: a block id, or `null` for the record/page root. */
+export function deadFieldsAt(refs: DeadRef[], blockId: string | null): Set<string> {
+  const out = new Set<string>()
+  for (const r of refs) {
+    if (blockId === null ? !r.blockId : r.blockId === blockId) out.add(r.field)
+  }
+  return out
+}

package/layers/admin/app/utils/edit-form.ts

@@ -0,0 +1,223 @@
+import type { FieldDef } from '../../../core/server/utils/defineCollection'
+import type { SerializedField } from '../../../core/server/utils/serialize-collection'
+import { resolveFieldEmpty } from '../../../ui/app/utils/field-empty'
+
+export interface ServerIssue {
+  path: (string | number)[]
+  message: string
+  code?: string
+}
+
+export interface MappedErrors {
+  fields: Record<string, string>
+  form?: string
+}
+
+export interface FetchErrorInfo {
+  statusCode?: number
+  statusMessage?: string
+  issues: ServerIssue[]
+}
+
+// The wire `SerializedField` is structurally what every Field* widget and `validateField` read
+// (flat type + options record + relation); only its discriminated-union typing differs. Narrow here.
+export function asFieldDef(field: SerializedField): FieldDef {
+  return field as unknown as FieldDef
+}
+
+// Read an ofetch/H3 error envelope: top-level statusCode/statusMessage, Zod issues nested at err.data.data.
+export function readFetchError(e: unknown): FetchErrorInfo {
+  const err = e as { statusCode?: number; statusMessage?: string; data?: { data?: ServerIssue[] } & Record<string, unknown> }
+  const raw = err.data?.data ?? err.data
+  return {
+    statusCode: err.statusCode,
+    statusMessage: err.statusMessage,
+    issues: Array.isArray(raw) ? (raw as ServerIssue[]) : [],
+  }
+}
+
+function cloneDefault(value: unknown): unknown {
+  return value !== null && typeof value === 'object' ? structuredClone(value) : value
+}
+
+function emptyForField(field: SerializedField): unknown {
+  switch (field.type) {
+    case 'text':
+      return ''
+    case 'boolean':
+      return false
+    case 'repeater':
+      return []
+    case 'choice':
+      return field.options?.multiple ? [] : null
+    case 'relation':
+      return field.relation?.many ? [] : null
+    case 'media':
+      return field.options?.multiple ? [] : null
+    default:
+      // A consumer-defined type may register its blank shape (array/object-backed → [] / {}); else null.
+      return resolveFieldEmpty(field.type)?.() ?? null
+  }
+}
+
+/** Build a blank form state: a present (JSON-safe) default wins, else a type-appropriate empty. */
+export function initialValues(fields: Record<string, SerializedField>): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  for (const [name, field] of Object.entries(fields)) {
+    out[name] = 'default' in field ? cloneDefault(field.default) : emptyForField(field)
+  }
+  return out
+}
+
+/** Map a 400 body's Zod issues to per-field errors (by path[0]) and a single form-level error (empty path). */
+export function mapServerErrors(issues: ServerIssue[] | null | undefined): MappedErrors {
+  const fields: Record<string, string> = {}
+  let form: string | undefined
+  for (const issue of issues ?? []) {
+    const head = issue.path?.[0]
+    if (head === undefined || head === null || head === '') {
+      if (form === undefined) form = issue.message
+    } else {
+      const name = String(head)
+      if (!(name in fields)) fields[name] = issue.message
+    }
+  }
+  return form === undefined ? { fields } : { fields, form }
+}
+
+/** Per-block (keyed by the stable `block.id`), per-field error map for inline block-content errors. */
+export type BlockErrorMap = Record<string, Record<string, string>>
+
+interface BlockLike {
+  id?: unknown
+  props?: Record<string, unknown>
+  slots?: Record<string, unknown>
+}
+
+function blockId(block: unknown): string | null {
+  const id = (block as BlockLike | undefined)?.id
+  return typeof id === 'string' && id !== '' ? id : null
+}
+
+/**
+ * Parse nested block-content issues into a per-block, per-field error map keyed by the block's
+ * stable `id`. The server reports a *position* path — `[key, i, 'props', field, …]` for a top-level
+ * block, `[key, i, 'slots', name, j, 'props', field, …]` for one nested in a slot (any depth). We
+ * walk that path through the submitted `content` to find the target block and pin the error to its
+ * id, so it survives a later reorder at any level. First wins per field; an unresolvable path is
+ * skipped.
+ */
+export function parseBlockErrors(
+  issues: ServerIssue[] | null | undefined,
+  content: readonly unknown[] | null | undefined,
+  key = 'content',
+): BlockErrorMap {
+  const out: BlockErrorMap = {}
+  for (const issue of issues ?? []) {
+    const path = issue.path ?? []
+    if (path[0] !== key) continue
+    const hit = resolveBlockField(path.slice(1), content)
+    if (!hit) continue
+    out[hit.id] ??= {}
+    if (!(hit.field in out[hit.id]!)) out[hit.id]![hit.field] = issue.message
+  }
+  return out
+}
+
+/**
+ * Walk a position path (after the `content` head) through the block tree to the block whose
+ * `props.<field>` the issue targets. Steps over `<index>, 'slots', <name>` segments into nested
+ * slot arrays. Returns the target block's stable id + the field name, or null if the path is not a
+ * `…props.<field>` leaf or any segment doesn't resolve to an identified block.
+ */
+function resolveBlockField(
+  path: readonly (string | number)[],
+  blocks: readonly unknown[] | null | undefined,
+): { id: string; field: string } | null {
+  let arr: readonly unknown[] | null | undefined = blocks
+  for (let i = 0; i < path.length; ) {
+    const index = path[i]
+    if (typeof index !== 'number' || !Array.isArray(arr)) return null
+    const block = arr[index] as BlockLike | undefined
+    const next = path[i + 1]
+    if (next === 'props') {
+      const field = path[i + 2]
+      const id = blockId(block)
+      return typeof field === 'string' && id !== null ? { id, field } : null
+    }
+    if (next === 'slots') {
+      const name = path[i + 2]
+      if (typeof name !== 'string') return null
+      const slot = block?.slots?.[name]
+      arr = Array.isArray(slot) ? slot : null
+      i += 3
+      continue
+    }
+    return null
+  }
+  return null
+}
+
+/**
+ * Carry block errors across a `content` change. A block (identified by its stable `id`, top-level or nested in
+ * a slot at any depth) keeps its errors while it merely moves — a pure reorder, whether of its slot or of an
+ * ancestor — and is dropped when removed; added blocks never gain an error. Reconciliation is PER-FIELD: an
+ * edit clears only the edited field's stale message, so a still-invalid sibling field of the same block keeps
+ * its error instead of all of them flickering away until the next save.
+ */
+export function reconcileBlockErrors(
+  errors: BlockErrorMap,
+  prev: readonly unknown[] | null | undefined,
+  next: readonly unknown[] | null | undefined,
+): BlockErrorMap {
+  const prevById = new Map<string, BlockLike>()
+  const nextById = new Map<string, BlockLike>()
+  flattenBlocksById(prev, prevById)
+  flattenBlocksById(next, nextById)
+  const out: BlockErrorMap = {}
+  for (const [id, errs] of Object.entries(errors)) {
+    const before = prevById.get(id)
+    const after = nextById.get(id)
+    if (!before || !after) continue // removed → drop
+    const beforeProps = (before.props ?? {}) as Record<string, unknown>
+    const afterProps = (after.props ?? {}) as Record<string, unknown>
+    const kept: Record<string, string> = {}
+    for (const [field, message] of Object.entries(errs)) {
+      // Keep a field's error only while THAT field's value is unchanged; editing it clears its own stale message.
+      if (valuesEqual(beforeProps[field], afterProps[field])) kept[field] = message
+    }
+    if (Object.keys(kept).length) out[id] = kept
+  }
+  return out
+}
+
+/** Index every block in the tree (top-level and nested in slots) by its stable id. */
+function flattenBlocksById(blocks: readonly unknown[] | null | undefined, into: Map<string, BlockLike>): void {
+  for (const block of blocks ?? []) {
+    const id = blockId(block)
+    if (id !== null) into.set(id, block as BlockLike)
+    const slots = (block as BlockLike | undefined)?.slots
+    if (slots) for (const arr of Object.values(slots)) if (Array.isArray(arr)) flattenBlocksById(arr, into)
+  }
+}
+
+/** Structural deep-equality for the value shapes the editor tracks (primitives, arrays, plain objects). */
+export function valuesEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true
+  if (a === null || b === null || typeof a !== 'object' || typeof b !== 'object') return false
+
+  const aArr = Array.isArray(a)
+  const bArr = Array.isArray(b)
+  if (aArr !== bArr) return false
+  if (aArr && bArr) {
+    if (a.length !== b.length) return false
+    return a.every((item, i) => valuesEqual(item, b[i]))
+  }
+
+  const aRec = a as Record<string, unknown>
+  const bRec = b as Record<string, unknown>
+  const aKeys = Object.keys(aRec)
+  const bKeys = Object.keys(bRec)
+  if (aKeys.length !== bKeys.length) return false
+  return aKeys.every((k) => Object.prototype.hasOwnProperty.call(bRec, k) && valuesEqual(aRec[k], bRec[k]))
+}

package/layers/admin/app/utils/editor-expose.ts

@@ -0,0 +1,26 @@
+import type { PublishStatusData } from '../composables/usePublishStatus'
+
+/**
+ * The handle `CollectionEditor` exposes via `defineExpose` — the header hosts (`[collection]/[id].vue`
+ * and `SingletonEditor.vue`) drive Save / undo / preview and read the status ampel through it. ONE typed
+ * contract instead of three drifting inline copies: Vue does not type-check a template `ref="editorRef"`
+ * against `defineExpose`, so without a shared interface a renamed/removed key (e.g. `previewUrl`) compiles
+ * in both hosts and silently becomes `undefined` at runtime. Type both host refs as `EditorExpose | null`.
+ */
+export interface EditorExpose {
+  dirty: boolean
+  saving: boolean
+  canUndo: boolean
+  canRedo: boolean
+  undo: () => void
+  redo: () => void
+  hasStatus: boolean
+  status: string
+  /** The last SAVED publish status (baseline), for the right lamp's draft/published decision. */
+  savedStatus: string
+  previewUrl: string | null
+  pageLike: boolean
+  live: PublishStatusData | null
+  /** The record's own title (see `recordTitle`), or `''` — the header then shows "Edit {collection} #{id}". */
+  recordTitle: string
+}

package/layers/admin/app/utils/editor-form-context.ts

@@ -0,0 +1,83 @@
+import type { ComputedRef, InjectionKey, Ref } from 'vue'
+import type { FieldDef } from '../../../core/server/utils/defineCollection'
+import type { LayoutNode } from '../../../core/server/utils/field-layout'
+import type { BlockErrorMap } from './edit-form'
+import type { DeadRef } from './dead-refs'
+
+/**
+ * The form context `CollectionEditor` (the generic shell) provides to whichever editor **body** the
+ * registry resolves (fields · blocks · an extension's, e.g. node-graph). It carries the load-bearing
+ * `useEditForm` surface a body needs to read and mutate the record, so a body swaps in without a giant
+ * prop list — the same provide/inject seam as `recordEditContextKey`, one level up.
+ *
+ * Provide it BEFORE the shell's top-level `await` (after an await the setup instance is gone and `provide`
+ * silently no-ops), exactly like the record-edit context.
+ */
+/** Props for the shared page-fields pane. Defined once here so the shell's pre-built bindings and
+ *  `PageFieldsPane`'s own `defineProps` stay a single type (a widened `Record` would break the v-bind). */
+export interface PageFieldsBindings {
+  translatable?: boolean
+  collection: string
+  id: string
+  mode: 'single' | 'multi'
+  locale: string
+  translations: Record<string, number | null>
+  group?: string
+  fields: Record<string, FieldDef>
+  /** Normalized admin editor layout for the page fields (undefined → one field per row). */
+  fieldLayout?: LayoutNode[]
+  values: Record<string, unknown>
+  errors: Record<string, string>
+  deadFields?: Set<string>
+  pageLike?: boolean
+  seo?: boolean
+  status?: boolean
+  disabled?: boolean
+}
+
+export interface EditorFormContext {
+  /** Reactive form values / per-field errors (from `useEditForm`; reactive objects, not refs). */
+  values: Record<string, unknown>
+  errors: Record<string, string>
+  formError: Ref<string>
+  blockErrors: Ref<BlockErrorMap>
+  /** Route every mutation through this (→ block-error reconciliation, dirty tracking, history). The
+   *  optional `coalesceAs` lets a caller (e.g. a block-tree structural op) tag its own undo-history key
+   *  instead of coalescing under the bare field name. */
+  setField: (name: string, value: unknown, coalesceAs?: string) => void
+  locale: Ref<string>
+  translations: Ref<Record<string, number | null>>
+  translationGroup: Ref<string | undefined>
+  deadRefs: Ref<DeadRef[]>
+  saving: Ref<boolean>
+  mode: Ref<'multi' | 'single'>
+  translatable: Ref<boolean>
+  pageLike: Ref<boolean>
+  hasSeo: Ref<boolean>
+  hasStatus: Ref<boolean>
+  blocksAllowed: Ref<string[] | undefined>
+  /** Collection (page-root) fields as `FieldDef`s, ready for the field Renderer. */
+  renderable: ComputedRef<Record<string, FieldDef>>
+  /** The record's localized public URL (saved pageLike record with a path), or null (new/unsaved,
+   *  non-pageLike). The shell computes it once for the header's open-in-new-tab AND the live preview. */
+  previewUrl: ComputedRef<string | null>
+  undo: () => void
+  redo: () => void
+  applyFrom: (row: Record<string, unknown>) => void
+  /** Pre-bound props/handlers for the shared page-fields pane, rendered by both the fields and blocks
+   *  bodies (identical binding, differing only in layout chrome). */
+  pageFieldsBindings: ComputedRef<PageFieldsBindings>
+  pageFieldsHandlers: Record<string, (...args: never[]) => void>
+  /** A body registers how to reveal a validation failure (e.g. the blocks body focuses the offending
+   *  block). The shell calls it on a failed save, staying agnostic of the body's internals. */
+  registerRevealError: (fn: () => void) => void
+}
+
+export const editorFormContextKey = Symbol('kestrel.editorForm') as InjectionKey<EditorFormContext>
+
+/** Inject the editor form context inside a body component; throws if used outside `CollectionEditor`. */
+export function useEditorFormContext(): EditorFormContext {
+  const ctx = inject(editorFormContextKey)
+  if (!ctx) throw new Error('[kestrel] editor body used outside CollectionEditor (no editor form context)')
+  return ctx
+}

package/layers/admin/app/utils/editor-registry.ts

@@ -0,0 +1,20 @@
+import type { Component } from 'vue'
+
+/**
+ * Registry of admin editor *bodies* keyed by editor type (the `editor` field on a serialized collection).
+ * Mirrors the field-widget registry (`layers/ui/app/utils/field-registry.ts`), one level up: instead of
+ * picking a widget per field type, it picks the whole editor body per collection.
+ *
+ * The built-in `fields` / `blocks` bodies register themselves when the admin editor loads (see
+ * `register-editors`); extensions add their own via a `*.client.ts` plugin (auto-discovered through
+ * `extends`), exactly like `registerFieldComponent`. The frame — the admin rail (layout) and the record
+ * header/toolbar + form state (`CollectionEditor` / the host pages) — stays generic; only this body swaps.
+ */
+export const editorComponents: Record<string, Component> = {}
+
+export const resolveCollectionEditor = (type: string): Component | undefined => editorComponents[type]
+
+/** Register an editor body for a type. Mutates the singleton; a later call overrides the same type. */
+export function registerCollectionEditor(type: string, component: Component): void {
+  editorComponents[type] = component
+}

package/layers/admin/app/utils/field-keys.ts

@@ -0,0 +1,11 @@
+import type { SerializedField } from '../../../core/server/utils/serialize-collection'
+
+/**
+ * The jsKey (wire key) for a field — NOT a DB column name. The server marks single relation/media fields
+ * with `single` (stored as a `<name>Id` FK column, e.g. `author` -> `authorId`); everything else keeps the
+ * field name. The editor binds widgets by field name but must read/write rows, request bodies and list
+ * queries by this key — reading the server flag instead of re-deriving the rule (which silently drifts).
+ */
+export function jsKey(name: string, field: SerializedField): string {
+  return field.single ? `${name}Id` : name
+}