@michaelthielemann/kestrel 1.2.1

package/layers/admin/app/utils/list-columns.ts

@@ -0,0 +1,141 @@
+import type { SerializedCollection, SerializedField } from '../../../core/server/utils/serialize-collection'
+import { fieldFilterKind, META_FILTER_KIND, type FilterKind } from '../../../core/app/utils/filter-ops'
+import { jsKey } from './field-keys'
+
+export type ListColumnType = 'meta' | 'field' | 'translations' | 'deadRefs'
+
+export interface ListColumn {
+  /** The wire/row key: used to read `row[key]` and as the sort/filter field. The translations column
+   *  uses the server sidecar key `$translations`, which is never sent as a sort/filter (not a real column). */
+  key: string
+  type: ListColumnType
+  /** Field display name (only for `type:'field'`) — used directly as the column label. */
+  name?: string
+  /** i18n key for the column label (meta + translations columns). */
+  labelKey?: string
+  field?: SerializedField
+  sortable: boolean
+  filterable: boolean
+  /** The column's filter kind (present iff `filterable`) — drives the operator set + typed value control. */
+  filterKind?: FilterKind
+}
+
+/** The sidecar key the server attaches per row for translation status (mirrors `$media`). */
+export const TRANSLATIONS_KEY = '$translations'
+
+/** The sidecar key the server attaches per row when any reference it holds points at a dead/unpublished
+ *  target (the derived stale-reference warning). Like `$translations`, never a real sort/filter column. */
+export const DEAD_REFS_KEY = '$hasDeadRefs'
+
+/** Whether a collection holds any field/block that can reference another record — gates the dead-reference
+ *  column (mirrors the server's `collectionMayReference`, over the serialized schema). */
+export function hasReferenceFields(schema: SerializedCollection): boolean {
+  if (schema.blocks.enabled) return true
+  if (schema.seo) return true // the `seo` system column carries a media ref (the social image)
+  return Object.values(schema.fields).some(fieldMayReference)
+}
+function fieldMayReference(field: SerializedField): boolean {
+  switch (field.type) {
+    case 'relation':
+    case 'media':
+    case 'link':
+    case 'richtext':
+      return true
+    case 'repeater':
+      return Object.values((field.options?.fields ?? {}) as Record<string, SerializedField>).some(fieldMayReference)
+    default:
+      return false
+  }
+}
+
+const META_LABEL: Record<string, string> = {
+  id: 'list.col.id',
+  path: 'list.col.slug',
+  status: 'list.col.status',
+  createdAt: 'list.col.createdAt',
+  updatedAt: 'list.col.updatedAt',
+}
+
+/** Whether a field can be meaningfully SORTED as a single scalar DB column. JSON-backed fields
+ *  (richtext/json/repeater/link, multi-value choice/relation/media) cannot. (Filterability is a separate,
+ *  richer question — see `fieldFilterKind`: richtext and the multi-value fields ARE filterable, via
+ *  substring / JSON-array membership, even though they are not sortable.) */
+function isSortableField(f: SerializedField): boolean {
+  switch (f.type) {
+    case 'richtext':
+    case 'json':
+    case 'repeater':
+    case 'link':
+      return false
+    case 'choice':
+      return !f.options?.multiple
+    case 'relation':
+    case 'media':
+      return !!f.single
+    default:
+      return true // text, number, boolean, datetime
+  }
+}
+
+/** Whether a field column is shown by default — only plain scalar display types. Heavier/structured fields
+ *  (richtext, json, repeater, link, relation, media, multi-choice) are available but off by default. */
+function isDefaultFieldColumn(f: SerializedField): boolean {
+  switch (f.type) {
+    case 'text':
+    case 'number':
+    case 'boolean':
+    case 'datetime':
+      return true
+    case 'choice':
+      return !f.options?.multiple
+    default:
+      return false
+  }
+}
+
+/** A meta/system column, filterable iff it has a FilterKind (id/path/status/timestamps all do). */
+function metaColumn(key: string): ListColumn {
+  const filterKind = META_FILTER_KIND[key]
+  return { key, type: 'meta', labelKey: META_LABEL[key], sortable: true, filterable: !!filterKind, ...(filterKind ? { filterKind } : {}) }
+}
+
+/** Every column a collection list can offer, in display order: id · fields · slug · status · timestamps ·
+ *  translations. The user picks which are visible (see `defaultVisibleKeys` / `resolveVisibleColumns`). */
+export function availableColumns(schema: SerializedCollection): ListColumn[] {
+  const cols: ListColumn[] = [metaColumn('id')]
+  for (const [name, field] of Object.entries(schema.fields)) {
+    const filterKind = fieldFilterKind(field)
+    cols.push({ key: jsKey(name, field), type: 'field', name, field, sortable: isSortableField(field), filterable: filterKind !== null, ...(filterKind ? { filterKind } : {}) })
+  }
+  if (schema.pageLike) cols.push(metaColumn('path'))
+  if (schema.status) cols.push(metaColumn('status'))
+  cols.push(metaColumn('createdAt'))
+  cols.push(metaColumn('updatedAt'))
+  if (schema.translatable && schema.mode === 'multi') {
+    cols.push({ key: TRANSLATIONS_KEY, type: 'translations', labelKey: 'list.translations', sortable: false, filterable: false })
+  }
+  // A compact warning column (a triangle on rows holding a stale reference) — only where refs are possible.
+  if (hasReferenceFields(schema)) {
+    cols.push({ key: DEAD_REFS_KEY, type: 'deadRefs', labelKey: 'list.deadRefs', sortable: false, filterable: false })
+  }
+  return cols
+}
+
+/** The default visible set: everything except `id` and the heavier field types — i.e. the scalar fields
+ *  plus slug, status, timestamps and translations. */
+export function defaultVisibleKeys(schema: SerializedCollection): string[] {
+  return availableColumns(schema)
+    .filter((c) => {
+      if (c.key === 'id') return false
+      if (c.type === 'field') return isDefaultFieldColumn(c.field!)
+      return true
+    })
+    .map((c) => c.key)
+}
+
+/** Project the requested keys onto the available columns: preserves the canonical column order and silently
+ *  drops keys that no longer exist (e.g. a removed field still listed in a saved preference). */
+export function resolveVisibleColumns(available: ListColumn[], keys: string[]): ListColumn[] {
+  const wanted = new Set(keys)
+  return available.filter((c) => wanted.has(c.key))
+}

package/layers/admin/app/utils/list-query.ts

@@ -0,0 +1,96 @@
+import { FILTER_RE, isFilterOp, opAllowed, type FilterOp } from '../../../core/app/utils/filter-ops'
+import { clampPerPage } from '../../../core/app/utils/list-limits'
+import type { ListColumn } from './list-columns'
+
+// The page-size bounds live in ONE shared module (core/app/utils/list-limits) so the client list, the
+// per-page picker and the server crud cap can never drift; `toQuery` clamps through it below.
+
+/** One active filter clause in the admin UI: the chosen operator + its (string) value. Kept per-column
+ *  (`Record<field, FilterCell>`) — the per-column panel shows one clause per column. */
+export interface FilterCell {
+  op: FilterOp
+  value: string
+}
+
+export interface ListState {
+  sort: string | null
+  page: number
+  perPage: number
+  filter: Record<string, FilterCell>
+}
+
+/** UI state -> the `$fetch` query object the list endpoint expects. An `eq` clause stays the bare
+ *  `filter[field]` key (so existing URLs round-trip); any other operator serializes as `filter[field][op]`.
+ *  Empty-valued clauses are dropped. `perPage` is clamped. */
+export function toQuery(state: ListState): Record<string, string | number> {
+  const q: Record<string, string | number> = {
+    page: Math.max(1, Math.floor(state.page)),
+    perPage: clampPerPage(state.perPage),
+  }
+  if (state.sort) q.sort = state.sort
+  for (const [field, cell] of Object.entries(state.filter)) {
+    if (cell.value === '' || cell.value == null) continue
+    q[cell.op === 'eq' ? `filter[${field}]` : `filter[${field}][${cell.op}]`] = cell.value
+  }
+  return q
+}
+
+/** Pick the first usable scalar from a URL query value. Real `route.query` values are strings (or arrays of
+ *  strings for a repeated key — we take the first, so `filter[x]=a&filter[x]=b` keeps the FIRST clause); a
+ *  round-trip through `toQuery` may hand back a number (page/perPage), so coerce that too. Anything else
+ *  (null / object) yields `undefined`. */
+function firstStr(v: unknown): string | undefined {
+  const s = Array.isArray(v) ? v[0] : v
+  if (typeof s === 'string') return s
+  if (typeof s === 'number') return String(s)
+  return undefined
+}
+
+/** The pure inverse of `toQuery`: read committed list state back OUT of a URL query. It NEVER throws — every
+ *  invalid or hostile key is DROPPED so the caller's defaults apply (a junk `page`/`perPage`, an unknown or
+ *  non-sortable `sort` field, an unknown/unfilterable filter column, or an operator not allowed for that
+ *  column's kind). A repeated `filter[field]` keeps the FIRST clause (the admin model holds one clause per
+ *  column). Absent/invalid keys are OMITTED, so `parseListQuery(toQuery(state), columns)` deep-equals the
+ *  normalized `state`. */
+export function parseListQuery(query: Record<string, unknown>, columns: ListColumn[]): Partial<ListState> {
+  const out: Partial<ListState> = {}
+
+  const p = firstStr(query.page)
+  if (p != null) { const n = Number(p); if (Number.isFinite(n) && n >= 1) out.page = Math.floor(n) }
+
+  const pp = firstStr(query.perPage)
+  if (pp) { const n = Number(pp); if (Number.isFinite(n)) out.perPage = clampPerPage(n) } // garbage → omit → cookie
+
+  const s = firstStr(query.sort)
+  if (s) { const base = s.startsWith('-') ? s.slice(1) : s; if (columns.some((c) => c.key === base && c.sortable)) out.sort = s } // unknown/non-sortable → omit → default
+
+  const filter: Record<string, FilterCell> = {}
+  for (const [k, raw] of Object.entries(query)) {
+    const m = FILTER_RE.exec(k)
+    if (!m) continue
+    const field = m[1]!
+    if (field in filter) continue // one clause per column: the first key for this field wins
+    const op = m[2] ?? 'eq'
+    const value = firstStr(raw)
+    if (value == null || value === '') continue // empty value → drop
+    if (!isFilterOp(op)) continue // unknown operator token → drop
+    const col = columns.find((c) => c.key === field && c.filterable)
+    if (!col) continue // unknown / unfilterable column → drop
+    if (!opAllowed(col.filterKind ?? 'text', op)) continue // op disallowed for the column kind → drop
+    filter[field] = { op, value }
+  }
+  if (Object.keys(filter).length) out.filter = filter
+
+  return out
+}
+
+/** Toggle a column between ascending (`field`) and descending (`-field`); a new field starts ascending. */
+export function toggleSort(current: string | null, field: string): string {
+  return current === field ? `-${field}` : field
+}
+
+export function sortDirection(current: string | null, field: string): 'asc' | 'desc' | null {
+  if (current === field) return 'asc'
+  if (current === `-${field}`) return 'desc'
+  return null
+}

package/layers/admin/app/utils/nav-active.ts

@@ -0,0 +1,9 @@
+/**
+ * Whether a rail nav item linking to `base` (e.g. "/admin/posts") should read as active for the
+ * current route `path`. Inclusive of descendant routes so a collection stays lit while editing one
+ * of its records (/admin/posts/1) — Vue Router's record-based active match does not, because the
+ * list and record pages are flat sibling routes that share no matched record.
+ */
+export function isNavItemActive(path: string, base: string): boolean {
+  return path === base || path.startsWith(`${base}/`)
+}

package/layers/admin/app/utils/populate-blocks.ts

@@ -0,0 +1,288 @@
+import type { SerializedBlock, SerializedField } from '../../../core/server/utils/serialize-collection'
+import type { ResolvedMedia } from '../../../media/app/composables/useMediaResolver'
+import { collectRichtextRefs, resolveRichtextLinks } from '../../../fields/app/utils/richtext-links'
+
+// Single source of truth for the resolved-media shape lives in the media layer (admin → media).
+export type { ResolvedMedia }
+
+interface BlockNode {
+  id?: string
+  type: string
+  props?: Record<string, unknown>
+  [k: string]: unknown
+}
+
+/** The sub-field schema of a `repeater` SerializedField, or null. Serialized as `options.fields` (a
+ *  name→SerializedField map, recursively) by `serializeField`. */
+function repeaterFields(field: SerializedField): Record<string, SerializedField> | null {
+  if (field.type !== 'repeater') return null
+  const sub = (field.options as { fields?: Record<string, SerializedField> } | undefined)?.fields
+  return sub && typeof sub === 'object' ? sub : null
+}
+
+/** A block's `slots` bag from the data (a name→child-array map), or null if it has none. */
+function slotsOf(node: BlockNode): Record<string, unknown> | null {
+  const s = (node as { slots?: unknown }).slots
+  return s && typeof s === 'object' && !Array.isArray(s) ? (s as Record<string, unknown>) : null
+}
+
+/**
+ * Rebuild a block's `slots` bag, recursing each child array through `recurse`. Identity-preserving: a
+ * slot whose populated children are each `===` the originals keeps the original array ref, and when NO
+ * slot changed the whole bag is reported unchanged (`null`) — so the live preview never churns block
+ * identities on an unaffected subtree. The `b === arr[i]` short-circuit is load-bearing for reactivity.
+ */
+function mapSlots(
+  slots: Record<string, unknown> | null,
+  recurse: (arr: unknown[]) => BlockNode[],
+): Record<string, unknown> | null {
+  if (!slots) return null
+  const rebuilt: Record<string, unknown> = {}
+  let changed = false
+  for (const [name, arr] of Object.entries(slots)) {
+    if (!Array.isArray(arr)) {
+      rebuilt[name] = arr
+      continue
+    }
+    const populated = recurse(arr)
+    const same = populated.length === arr.length && populated.every((b, i) => b === arr[i])
+    rebuilt[name] = same ? arr : populated
+    if (!same) changed = true
+  }
+  return changed ? rebuilt : null
+}
+
+export interface LinkRef { collection: string; id: number }
+
+/** The `{collection, id}` of an internal LinkValue, or null for external/email/tel/empty. */
+function internalRefOf(value: unknown): LinkRef | null {
+  if (!value || typeof value !== 'object') return null
+  const v = value as Record<string, unknown>
+  return v.type === 'internal' && typeof v.collection === 'string' && typeof v.id === 'number'
+    ? { collection: v.collection, id: v.id }
+    : null
+}
+
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+// Field-bag recursion — the client mirror of the server field-tree walker
+// (`layers/fields/server/utils/field-populate.ts`). A "bag" is a block's props OR a repeater entry;
+// both key media/link/richtext values BARE (props key-mode). Every collector/populator descends
+// `repeater` sub-fields so a repeater-nested media/link resolves in the preview exactly as it does in
+// the generated page — the two must stay in lock-step.
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+
+/** Media ids referenced by a value-bag (a block's props or a repeater entry), recursing repeater entries. */
+function collectMediaFromBag(fields: Record<string, SerializedField>, bag: Record<string, unknown>, ids: Set<number>): void {
+  for (const [key, field] of Object.entries(fields)) {
+    if (field.type === 'media') {
+      const v = bag[key]
+      if (field.options?.multiple) {
+        if (Array.isArray(v)) for (const x of v) if (typeof x === 'number') ids.add(x)
+      } else if (typeof v === 'number') {
+        ids.add(v)
+      }
+    } else {
+      const sub = repeaterFields(field)
+      const entries = sub ? bag[key] : null
+      if (sub && Array.isArray(entries)) {
+        for (const e of entries) if (e && typeof e === 'object') collectMediaFromBag(sub, e as Record<string, unknown>, ids)
+      }
+    }
+  }
+}
+
+/** Every media id referenced by block props (incl. repeater entries), deduped and walked into slot
+ *  children — for one batched resolve call. */
+export function collectMediaIds(blocks: unknown, byType: Record<string, SerializedBlock>): number[] {
+  const ids = new Set<number>()
+  const walk = (nodes: unknown): void => {
+    if (!Array.isArray(nodes)) return
+    for (const node of nodes as BlockNode[]) {
+      const def = node?.type ? byType[node.type] : undefined
+      if (def && node.props) collectMediaFromBag(def.fields, node.props, ids)
+      const slots = node ? slotsOf(node) : null
+      if (slots) for (const arr of Object.values(slots)) walk(arr)
+    }
+  }
+  walk(blocks)
+  return [...ids]
+}
+
+/**
+ * Populate media in a value-bag: attach a `$media` sibling for its direct media fields and recurse each
+ * repeater entry. Identity-preserving — returns the SAME bag ref when nothing resolved and reuses each
+ * unchanged repeater array/entry — so the preview doesn't churn identities on every recompute.
+ */
+function populateMediaInBag(
+  fields: Record<string, SerializedField>,
+  bag: Record<string, unknown>,
+  resolve: (id: number) => ResolvedMedia | null,
+): Record<string, unknown> {
+  let media: Record<string, unknown> | null = null
+  let repeaters: Record<string, unknown> | null = null
+  for (const [key, field] of Object.entries(fields)) {
+    if (field.type === 'media') {
+      const v = bag[key]
+      if (field.options?.multiple) {
+        if (Array.isArray(v)) {
+          const resolved = v.filter((x): x is number => typeof x === 'number').map(resolve).filter((m): m is ResolvedMedia => !!m)
+          if (resolved.length) (media ??= {})[key] = resolved
+        }
+      } else if (typeof v === 'number') {
+        const m = resolve(v)
+        if (m) (media ??= {})[key] = m
+      }
+    } else {
+      const sub = repeaterFields(field)
+      const entries = sub ? bag[key] : null
+      if (sub && Array.isArray(entries)) {
+        const populated = entries.map((e) => (e && typeof e === 'object' ? populateMediaInBag(sub, e as Record<string, unknown>, resolve) : e))
+        if (!populated.every((e, i) => e === entries[i])) (repeaters ??= {})[key] = populated
+      }
+    }
+  }
+  if (!media && !repeaters) return bag
+  const out = { ...bag }
+  if (repeaters) Object.assign(out, repeaters)
+  if (media) out.$media = media
+  return out
+}
+
+/**
+ * Client mirror of the server media populator: attach a `$media` bag to each block's props (and each
+ * repeater entry) so the public `BlockRenderer` and `Blocks*` display components render images in the
+ * live preview. Pure; `resolve` is the (reactive) id→media lookup. Recurses slot children AND repeater
+ * entries. A block whose whole subtree needs no media (media-free, unknown type, empty/unchanged slots,
+ * or not-yet-resolved ids) is returned **by reference** so unchanged branches keep their refs all the
+ * way up.
+ */
+export function populateBlocksMedia(
+  blocks: unknown,
+  byType: Record<string, SerializedBlock>,
+  resolve: (id: number) => ResolvedMedia | null,
+): BlockNode[] {
+  if (!Array.isArray(blocks)) return []
+  return (blocks as BlockNode[]).map((node) => {
+    const def = node?.type ? byType[node.type] : undefined
+    const nextProps = def && node.props ? populateMediaInBag(def.fields, node.props, resolve) : node.props
+
+    // Rebuild slots only where a child subtree actually changed; otherwise reuse the original array
+    // ref so an empty or media-free slot doesn't force a new parent object.
+    const nextSlots = mapSlots(node ? slotsOf(node) : null, (arr) => populateBlocksMedia(arr, byType, resolve))
+
+    if (nextProps === node.props && !nextSlots) return node
+    const out: BlockNode = { ...node }
+    if (nextProps !== node.props) out.props = nextProps
+    if (nextSlots) out.slots = nextSlots
+    return out
+  })
+}
+
+/** Internal-link + richtext-marker refs in a value-bag (a block's props or a repeater entry), recursing
+ *  repeater entries. */
+function collectLinkRefsFromBag(fields: Record<string, SerializedField>, bag: Record<string, unknown>, add: (ref: LinkRef) => void): void {
+  for (const [key, field] of Object.entries(fields)) {
+    if (field.type === 'link') {
+      const ref = internalRefOf(bag[key])
+      if (ref) add(ref)
+    } else if (field.type === 'richtext') {
+      for (const ref of collectRichtextRefs(bag[key] as string | undefined)) add(ref)
+    } else {
+      const sub = repeaterFields(field)
+      const entries = sub ? bag[key] : null
+      if (sub && Array.isArray(entries)) {
+        for (const e of entries) if (e && typeof e === 'object') collectLinkRefsFromBag(sub, e as Record<string, unknown>, add)
+      }
+    }
+  }
+}
+
+/** Every internal-link `{collection,id}` referenced by block props (incl. repeater entries + richtext
+ *  markers), deduped, walked into slots — for one batched resolve call (mirror of `collectMediaIds`). */
+export function collectLinkRefs(blocks: unknown, byType: Record<string, SerializedBlock>): LinkRef[] {
+  const seen = new Set<string>()
+  const refs: LinkRef[] = []
+  const add = (ref: LinkRef): void => {
+    const k = `${ref.collection}:${ref.id}`
+    if (!seen.has(k)) {
+      seen.add(k)
+      refs.push(ref)
+    }
+  }
+  const walk = (nodes: unknown): void => {
+    if (!Array.isArray(nodes)) return
+    for (const node of nodes as BlockNode[]) {
+      const def = node?.type ? byType[node.type] : undefined
+      if (def && node.props) collectLinkRefsFromBag(def.fields, node.props, add)
+      const slots = node ? slotsOf(node) : null
+      if (slots) for (const arr of Object.values(slots)) walk(arr)
+    }
+  }
+  walk(blocks)
+  return refs
+}
+
+/**
+ * Resolve internal links + richtext markers in a value-bag, recursing repeater entries. Identity-
+ * preserving — a link/richtext value that needs no change keeps its ref, an unchanged repeater array/
+ * entry keeps its ref, and a bag with nothing to change is returned as-is (lazily cloned only on the
+ * first actual change).
+ */
+function populateLinksInBag(
+  fields: Record<string, SerializedField>,
+  bag: Record<string, unknown>,
+  resolveHref: (collection: string, id: number) => string | null,
+): Record<string, unknown> {
+  let next: Record<string, unknown> | null = null
+  for (const [key, field] of Object.entries(fields)) {
+    if (field.type === 'link') {
+      const ref = internalRefOf(bag[key])
+      if (!ref) continue
+      const href = resolveHref(ref.collection, ref.id)
+      const current = bag[key] as Record<string, unknown>
+      if (href == null || current.href === href) continue
+      ;(next ??= { ...bag })[key] = { ...current, href }
+    } else if (field.type === 'richtext') {
+      const current = bag[key]
+      if (typeof current !== 'string') continue
+      const resolved = resolveRichtextLinks(current, resolveHref)
+      if (resolved === current) continue // no markers (or already identical) → keep ref
+      ;(next ??= { ...bag })[key] = resolved
+    } else {
+      const sub = repeaterFields(field)
+      const entries = sub ? bag[key] : null
+      if (sub && Array.isArray(entries)) {
+        const populated = entries.map((e) => (e && typeof e === 'object' ? populateLinksInBag(sub, e as Record<string, unknown>, resolveHref) : e))
+        if (!populated.every((e, i) => e === entries[i])) (next ??= { ...bag })[key] = populated
+      }
+    }
+  }
+  return next ?? bag
+}
+
+/**
+ * Client mirror of the server link populator: replace each block's internal-link field value with a
+ * cloned `{...value, href}` (and rewrite richtext markers) so the live preview's `KestrelLink` renders
+ * the real path instead of `'#'`. external/email/tel and unresolved internals are left untouched.
+ * Recurses slot children AND repeater entries. Identity-preserving like `populateBlocksMedia` — a block
+ * (and its slot/repeater subtree) whose links need no change is returned by reference.
+ */
+export function populateBlocksLinks(
+  blocks: unknown,
+  byType: Record<string, SerializedBlock>,
+  resolveHref: (collection: string, id: number) => string | null,
+): BlockNode[] {
+  if (!Array.isArray(blocks)) return []
+  return (blocks as BlockNode[]).map((node) => {
+    const def = node?.type ? byType[node.type] : undefined
+    const nextProps = def && node.props ? populateLinksInBag(def.fields, node.props, resolveHref) : node.props
+
+    const nextSlots = mapSlots(node ? slotsOf(node) : null, (arr) => populateBlocksLinks(arr, byType, resolveHref))
+
+    if (nextProps === node.props && !nextSlots) return node
+    const out: BlockNode = { ...node }
+    if (nextProps !== node.props) out.props = nextProps
+    if (nextSlots) out.slots = nextSlots
+    return out
+  })
+}

package/layers/admin/app/utils/preview-channel.ts

@@ -0,0 +1,62 @@
+import { contentMessage, selectedMessage, type PreviewBlockNode } from '../../../public/app/utils/preview-protocol'
+
+/**
+ * Editor→iframe send half of the live-preview channel (the receive half is the public
+ * `KestrelPreviewBridge`). Content updates are coalesced to one post per animation frame — a typing
+ * burst produces a single message carrying the LATEST tree (read at fire time), so the preview stays
+ * keystroke-live (≤ one frame behind) without flooding the channel. Selection changes are tiny and
+ * latency-sensitive → posted immediately.
+ *
+ * `target` is a getter because the iframe's contentWindow appears on load and is replaced on every
+ * navigation/reload; posts silently no-op while it is gone. `origin` is passed as postMessage's
+ * targetOrigin so a frame that navigated cross-origin can never receive editor content.
+ */
+export interface PreviewSender {
+  sendContent: (blocks: PreviewBlockNode[]) => void
+  sendSelected: (selectedId: string | null) => void
+  dispose: () => void
+}
+
+export function createPreviewSender(
+  target: () => Window | null | undefined,
+  origin: string,
+  // Read at FIRE time (like the blocks), never captured at schedule time: an immediate selection post
+  // can overtake a pending content frame, and a stale captured id in that frame would then revert the
+  // bridge's newer selection (content messages carry the selection authoritatively).
+  getSelected: () => string | null,
+): PreviewSender {
+  let rafId: number | null = null
+  let latest: PreviewBlockNode[] | null = null
+
+  const post = (msg: unknown) => target()?.postMessage(msg, origin)
+
+  const fire = () => {
+    rafId = null
+    if (!latest) return
+    // JSON round-trip: detaches Vue reactive proxies (structured clone chokes on some exotic wrappers)
+    // and guarantees the payload is the same JSON-safe shape the DB round-trips. Block trees are small;
+    // at one clone per frame this is well under a millisecond.
+    post(contentMessage(JSON.parse(JSON.stringify(latest)), getSelected()))
+    latest = null
+  }
+
+  return {
+    sendContent(blocks) {
+      latest = blocks
+      rafId ??= requestAnimationFrame(fire)
+    },
+    sendSelected(selectedId) {
+      post(selectedMessage(selectedId))
+    },
+    dispose() {
+      if (rafId !== null) cancelAnimationFrame(rafId)
+      rafId = null
+      latest = null
+    },
+  }
+}
+
+/** Parent-side trust guard: accept a message only from OUR origin AND our preview iframe's window. */
+export function acceptsFrameEvent(event: MessageEvent, frameWindow: Window | null, origin: string): boolean {
+  return frameWindow !== null && event.origin === origin && event.source === frameWindow
+}

package/layers/admin/app/utils/preview-viewport.ts

@@ -0,0 +1,80 @@
+import type { IconName } from '../../../ui/app/utils/icons'
+
+/**
+ * Pure geometry for the page-builder preview toolbar (device presets + automatic scale-to-fit + custom
+ * W×H). Kept framework-free so it's node-testable — the Vue component (`BlockPreview.vue`) only wires refs
+ * to these.
+ */
+
+/** A viewport axis: a fixed CSS px, or `'auto'` (fills the available pane at the current scale). */
+export type Dim = number | 'auto'
+
+export interface ViewportPreset {
+  key: 'desktop' | 'tablet' | 'mobile'
+  /** Toolbar glyph (registry key). */
+  icon: IconName
+  /** i18n label key (the resolution is shown alongside it in the tooltip). */
+  label: string
+  /** Reference viewport width/height — the iframe's REAL size (scaled only visually); `'auto'` fills. */
+  w: Dim
+  h: Dim
+}
+
+export type PresetKey = ViewportPreset['key'] | 'custom'
+
+/** Bounds shared by the two numeric W×H inputs. */
+export const DIM_MIN = 320
+export const WIDTH_MAX = 3840
+export const HEIGHT_MAX = 4320
+
+/**
+ * The three quick-select presets. Desktop keeps the config-driven breakpoint WIDTH (`kestrel.config.ts` →
+ * `preview.desktopWidth`, default 1440) but an `'auto'` HEIGHT so the frame fills the pane vertically and
+ * only the iframe's own document scrolls. Tablet/mobile are canonical fixed device viewports (iPad
+ * portrait / iPhone) so `100vh`/sticky/lazy behave like the real device, scaled down to fit both axes.
+ */
+export function PRESETS(desktopWidth: number): ViewportPreset[] {
+  return [
+    { key: 'desktop', icon: 'monitor', label: 'preview.device.desktop', w: desktopWidth, h: 'auto' },
+    { key: 'tablet', icon: 'tablet', label: 'preview.device.tablet', w: 768, h: 1024 },
+    { key: 'mobile', icon: 'smartphone', label: 'preview.device.mobile', w: 390, h: 844 },
+  ]
+}
+
+/** The preset a (w,h) exactly matches, else `'custom'` — drives which quick-select button is highlighted. */
+export function matchPreset(w: Dim, h: Dim, presets: ViewportPreset[]): PresetKey {
+  return presets.find((p) => p.w === w && p.h === h)?.key ?? 'custom'
+}
+
+/**
+ * Uniform (no-distortion) scale: fit each FIXED axis into its available space, take the min, and **cap at
+ * 1×** (never upscale). An `'auto'` axis doesn't constrain — it fills instead (see `resolveDim`). So
+ * desktop (width fixed, height auto) is width-limited; tablet/mobile (both fixed) fit whichever axis is
+ * tighter and letterbox the other. Returns 1 before the stage is measured (`avail ≤ 0`) so nothing jumps.
+ */
+export function fitScale(availW: number, availH: number, w: Dim, h: Dim): number {
+  const ratios = [1]
+  if (typeof w === 'number' && w > 0 && availW > 0) ratios.push(availW / w)
+  if (typeof h === 'number' && h > 0 && availH > 0) ratios.push(availH / h)
+  return Math.min(...ratios)
+}
+
+/**
+ * Resolve a `Dim` to real px. A fixed value passes straight through; an `'auto'` axis fills the available
+ * space at the current scale (`avail / scale`, so the SCALED px exactly equals `avail`). Falls back to
+ * `fallback` when unmeasured (SSR/tests: `avail ≤ 0` or `scale ≤ 0`) so the frame still has a size.
+ */
+export function resolveDim(avail: number, dim: Dim, scale: number, fallback: number): number {
+  if (dim !== 'auto') return dim
+  return avail > 0 && scale > 0 ? Math.round(avail / scale) : fallback
+}
+
+/**
+ * Commit a numeric-input value: clamp into `[min,max]` and floor to an integer px. Returns `null` for
+ * empty/non-finite input so the caller keeps the previous value (the field can hold un-parsable editing
+ * text whose model is momentarily null — we must not reset the viewport to a default then).
+ */
+export function clampDim(n: number | null | undefined, min: number, max: number): number | null {
+  if (n == null || !Number.isFinite(n)) return null
+  return Math.min(max, Math.max(min, Math.floor(n)))
+}