@michaelthielemann/kestrel 1.2.1

package/layers/admin/app/composables/useEditForm.ts

@@ -0,0 +1,370 @@
+import type { SerializedField } from '../../../core/server/utils/serialize-collection'
+import type { LayoutNode } from '../../../core/server/utils/field-layout'
+import type { BlockErrorMap } from '../utils/edit-form'
+import type { DeadRef } from '../utils/dead-refs'
+import { asFieldDef, initialValues, mapServerErrors, parseBlockErrors, reconcileBlockErrors, readFetchError } from '../utils/edit-form'
+
+export interface UseEditFormOptions {
+  collection: string
+  id: string
+  /** Requested content locale (from the `?locale` route query). Defaults to the primary locale. */
+  locale?: string
+  /** translationGroup to link a NEW multi translation to its siblings (from the `?group` query). */
+  group?: string
+}
+
+export type SubmitResult = { ok: true; record: unknown } | { ok: false }
+
+function snapshot(values: Record<string, unknown>): Record<string, unknown> {
+  return JSON.parse(JSON.stringify(values))
+}
+
+export function useEditForm(opts: UseEditFormOptions) {
+  const { collection, id } = opts
+  const { t } = useT()
+  const { primary } = useContentLocales()
+  // The locale the editor *requests* (single GET/PUT + a new multi translation). For an existing multi
+  // row the active locale comes from the row itself (set in init); it can't be switched via a query.
+  const requestedLocale = opts.locale?.trim() || primary
+  const activeLocale = ref(requestedLocale)
+  const translations = ref<Record<string, number | null>>({})
+  // Stale references this record currently holds (derived on read) — drives the editor's dead-ref warnings.
+  const deadRefs = ref<DeadRef[]>([])
+  // The translation group the LocaleBar links new siblings to: the requested group for a new
+  // translation, or the loaded row's own group for an existing multi record.
+  const translationGroup = ref<string | undefined>(opts.group?.trim() || undefined)
+
+  const fields = ref<Record<string, SerializedField>>({})
+  // The collection's normalized admin editor layout (resolved server-side), or undefined → one field per row.
+  const fieldLayout = ref<LayoutNode[] | undefined>(undefined)
+  const mode = ref<'multi' | 'single'>('multi')
+  const translatable = ref(false)
+  const blocksEnabled = ref(false)
+  const blocksAllowed = ref<string[] | undefined>(undefined)
+  // pageLike collections carry a routable `path` (the slug) as a system column, edited in the page editor.
+  const pageLike = ref(false)
+  // seo-enabled collections carry a `seo` JSON system column ({ title, description, noindex }).
+  const hasSeo = ref(false)
+  // status-enabled collections carry a `status` system column ('draft' | 'published') — the publish gate.
+  const hasStatus = ref(false)
+  // Which editor body renders (the `editor` type on the serialized collection). The server resolves it,
+  // but fall back defensively (blocks → 'blocks', else 'fields') so an older/partial schema still works.
+  const editorType = ref('fields')
+
+  const values = reactive<Record<string, unknown>>({})
+  const errors = reactive<Record<string, string>>({})
+  const formError = ref('')
+  const blockErrors = ref<BlockErrorMap>({})
+  const saving = ref(false)
+  const baseline = ref<Record<string, unknown>>({})
+  const baseUpdatedAt = ref<number | undefined>(undefined)
+
+  const dirty = computed(() => !valuesEqual(values, baseline.value))
+  // The LAST SAVED publish status (from the baseline snapshot, not the live edited value). The editor's
+  // right "live" lamp keys its draft/published decision off this — an UNSAVED dropdown switch must not flip
+  // the generated-state indicator (nothing is generated until the change is saved). '' when statusless.
+  const savedStatus = computed(() => (hasStatus.value ? ((baseline.value.status as string | undefined) ?? '') : ''))
+  // The LAST SAVED page path (baseline, not the live edited slug). The preview iframe + the header's
+  // open-in-new-tab must target a URL that actually EXISTS — an unsaved slug edit would 404 until saved;
+  // on save the baseline moves and both follow to the new URL. '' when non-pageLike or never saved.
+  const savedPath = computed(() => (pageLike.value ? ((baseline.value.path as string | undefined) ?? '') : ''))
+
+  // Undo/redo: snapshot history of the whole form state. Every edit funnels through setField (block-tree
+  // ops route through setField('content', …)), so that's the single capture point. A rapid burst of edits
+  // to the same field coalesces into one step; the stacks reset on load/save (no undo across a save).
+  const past = ref<Record<string, unknown>[]>([])
+  const future = ref<Record<string, unknown>[]>([])
+  const canUndo = computed(() => past.value.length > 0)
+  const canRedo = computed(() => future.value.length > 0)
+  let coalesceKey = ''
+  let coalesceAt = 0
+  const COALESCE_MS = 600
+  const HISTORY_LIMIT = 100
+
+  function recordHistory(name: string) {
+    const now = Date.now()
+    const coalesce = name === coalesceKey && now - coalesceAt < COALESCE_MS
+    coalesceKey = name
+    coalesceAt = now
+    if (coalesce) return
+    past.value.push(snapshot(values))
+    if (past.value.length > HISTORY_LIMIT) past.value.shift()
+    future.value = []
+  }
+
+  function restore(snap: Record<string, unknown>) {
+    const fresh = snapshot(snap)
+    for (const k of Object.keys(fresh)) values[k] = fresh[k]
+    for (const k of Object.keys(values)) if (!(k in fresh)) delete values[k]
+    for (const k of Object.keys(errors)) delete errors[k]
+    blockErrors.value = {}
+    formError.value = ''
+    coalesceKey = ''
+  }
+
+  function undo() {
+    if (!past.value.length) return
+    future.value.push(snapshot(values))
+    restore(past.value.pop()!)
+  }
+  function redo() {
+    if (!future.value.length) return
+    past.value.push(snapshot(values))
+    restore(future.value.pop()!)
+  }
+
+  const renderableFields = computed<Record<string, SerializedField>>(() => {
+    if (!blocksEnabled.value) return fields.value
+    const { content: _content, ...rest } = fields.value
+    return rest
+  })
+
+  function fieldKeys() {
+    return Object.keys(fields.value)
+  }
+
+  function rebaseline(source: Record<string, unknown> | null) {
+    const next = initialValues(fields.value)
+    if (source) {
+      for (const k of fieldKeys()) {
+        const col = jsKey(k, fields.value[k]!)
+        if (col in source) next[k] = source[col]
+      }
+    }
+    // `content` is a synthesized blocks column, not a def.field — round-trip it explicitly.
+    if (blocksEnabled.value) next.content = (source?.content as unknown[]) ?? []
+    // `path` (the page slug) is a pageLike system column, likewise round-tripped explicitly.
+    if (pageLike.value) next.path = (source?.path as string | null | undefined) ?? ''
+    // `seo` is a JSON system column; default to an empty object so the editor can fill it in.
+    if (hasSeo.value) next.seo = (source?.seo as Record<string, unknown> | undefined) ?? {}
+    // `status` is a system column; a new record defaults to 'draft' (unpublished) — matches the DB default.
+    if (hasStatus.value) next.status = (source?.status as string | undefined) ?? 'draft'
+    for (const k of Object.keys(next)) values[k] = next[k]
+    baseline.value = snapshot(values)
+    // The optimistic-concurrency baseline: the `updatedAt` this load/save established, sent back on the
+    // next save so a stale tab (loaded before someone else saved) is refused with 409 instead of
+    // silently reverting their change. undefined for a never-saved new record.
+    const stamp = source?.updatedAt
+    baseUpdatedAt.value = stamp != null ? new Date(stamp as string | number).getTime() : undefined
+    // A fresh load or a save establishes a new baseline — history does not span it.
+    past.value = []
+    future.value = []
+    coalesceKey = ''
+  }
+
+  async function init() {
+    const all = await useCollections().load()
+    const schema = all.find((c) => c.name === collection)
+    if (!schema) throw createError({ statusCode: 404, statusMessage: `Unknown collection: ${collection}` })
+    fields.value = schema.fields
+    fieldLayout.value = schema.fieldLayout
+    mode.value = schema.mode
+    translatable.value = schema.translatable
+    blocksEnabled.value = schema.blocks?.enabled ?? false
+    blocksAllowed.value = schema.blocks?.allowed
+    pageLike.value = schema.pageLike ?? false
+    hasSeo.value = schema.seo ?? false
+    hasStatus.value = schema.status ?? false
+    editorType.value = (schema as { editor?: string }).editor ?? (schema.blocks?.enabled ? 'blocks' : 'fields')
+
+    let row: Record<string, unknown> | null = null
+    if (mode.value === 'single') {
+      row = await $fetch<Record<string, unknown> | null>(`/api/${collection}`, translatable.value ? { query: { locale: requestedLocale } } : {})
+      activeLocale.value = requestedLocale
+    } else if (id !== 'new') {
+      row = await $fetch<Record<string, unknown>>(`/api/${collection}/${id}`)
+      if (translatable.value) {
+        if (typeof row?.locale === 'string') activeLocale.value = row.locale
+        if (typeof row?.translationGroup === 'string') translationGroup.value = row.translationGroup
+        // Supplementary (drives the LocaleBar) — never block editing if it fails.
+        try {
+          translations.value = await $fetch<Record<string, number | null>>(`/api/${collection}/${id}/translations`)
+        } catch {
+          translations.value = {}
+        }
+      }
+    } else {
+      activeLocale.value = requestedLocale
+      // A new sibling translation has no id yet, so its locale→id map is resolved by GROUP. Without it the
+      // LocaleBar shows every already-translated locale as a "+" create link: the copy-from source is
+      // unreachable, and following that link saves a second row for an occupied locale — a duplicate-locale
+      // 409 the user can't resolve. Supplementary (drives the LocaleBar) — never block editing if it fails.
+      if (translatable.value && translationGroup.value) {
+        try {
+          translations.value = await $fetch<Record<string, number | null>>(`/api/${collection}/translations`, { query: { group: translationGroup.value } })
+        } catch {
+          translations.value = {}
+        }
+      }
+    }
+    rebaseline(row)
+
+    // Supplementary dead-reference map (the editor warnings) — for any saved record, never blocks editing.
+    const recordId = typeof row?.id === 'number' ? row.id : null
+    if (recordId != null) {
+      try {
+        deadRefs.value = await $fetch<DeadRef[]>(`/api/${collection}/${recordId}/dead-refs`)
+      } catch {
+        deadRefs.value = []
+      }
+    } else {
+      deadRefs.value = [] // a new (unsaved) record has no references — keep it explicit, never stale
+    }
+  }
+
+  // `coalesceAs` lets a caller opt out of the default same-name coalescing: block-tree structural ops
+  // (remove/move/duplicate/add) all round-trip through setField('content', …) like a text edit does, so
+  // without a distinct key a delete landing inside another edit's 600ms burst would merge into it and
+  // become impossible to undo on its own.
+  function setField(name: string, value: unknown, coalesceAs: string = name) {
+    // Capture the pre-edit state for undo (coalesced for a same-field typing burst).
+    recordHistory(coalesceAs)
+    // Reconcile before overwriting: keep block errors through a reorder, drop them on an edit.
+    if (name === 'content') {
+      blockErrors.value = reconcileBlockErrors(blockErrors.value, values.content as unknown[], value as unknown[])
+    }
+    values[name] = value
+    formError.value = ''
+    const field = fields.value[name]
+    if (field) errors[name] = isFieldVisible(field, values) ? (validateField(asFieldDef(field), value) ?? '') : ''
+    // A controller edit can hide sibling fields — drop their now-irrelevant advisory errors so a
+    // hidden required field never shows a phantom error or blocks the save.
+    for (const [n, f] of Object.entries(fields.value)) if (!isFieldVisible(f, values)) errors[n] = ''
+  }
+
+  /** Copy another locale's field/content values into this form (the LocaleBar "copy" action). Goes
+   *  through setField so validation, block-error reconcile, and dirty-tracking all apply. */
+  function applyFrom(source: Record<string, unknown>) {
+    for (const k of fieldKeys()) {
+      const col = jsKey(k, fields.value[k]!)
+      if (col in source) setField(k, source[col])
+    }
+    if (blocksEnabled.value && 'content' in source) setField('content', source.content)
+  }
+
+  function validateAll(): boolean {
+    let ok = true
+    for (const [name, field] of Object.entries(fields.value)) {
+      // A hidden field is exempt from validation (its `required` only applies when shown) — mirrors
+      // the server's required-when-visible enforcement, so the client never blocks a valid save.
+      if (!isFieldVisible(field, values)) { errors[name] = ''; continue }
+      const msg = validateField(asFieldDef(field), values[name])
+      errors[name] = msg ?? ''
+      if (msg) ok = false
+    }
+    return ok
+  }
+
+  function buildBody(): Record<string, unknown> {
+    const body: Record<string, unknown> = {}
+    for (const k of fieldKeys()) body[jsKey(k, fields.value[k]!)] = values[k]
+    if (blocksEnabled.value) body.content = values.content
+    // Send the slug as the routable path; a blank slug clears the route (stored as null, not "").
+    if (pageLike.value) body.path = (values.path as string) ? values.path : null
+    if (hasSeo.value) body.seo = values.seo ?? {}
+    if (hasStatus.value) body.status = (values.status as string) ?? 'draft'
+    // A new translatable multi record carries its locale, and links to a translation group when it is
+    // a sibling translation. Existing rows keep their locale; the singleton uses the ?locale query.
+    if (translatable.value && mode.value === 'multi' && id === 'new') {
+      body.locale = activeLocale.value
+      if (translationGroup.value) body.translationGroup = translationGroup.value
+    }
+    return body
+  }
+
+  function handleError(e: unknown) {
+    const { statusCode, statusMessage, issues } = readFetchError(e)
+    if (statusCode === 400) {
+      const mapped = mapServerErrors(issues)
+      for (const [k, msg] of Object.entries(mapped.fields)) errors[k] = msg
+      // `content` errors are nested (content[i].props.x) and have no flat field to render them,
+      // so surface a form-level banner instead of failing silently.
+      blockErrors.value = parseBlockErrors(issues, values.content as unknown[])
+      // A field error (e.g. the page slug) renders inline in PageFields, but that pane is unmounted while a
+      // block is selected — so also raise a banner whenever there are field errors, never a silent failure.
+      formError.value = mapped.form
+        ?? (mapped.fields.content
+          ? t('editor.fixBlockContent')
+          : Object.keys(mapped.fields).length ? t('editor.fixPageFields') : '')
+    } else if (statusCode === 409) {
+      formError.value = statusMessage ?? t('editor.saveConflict')
+    } else {
+      formError.value = statusMessage ?? t('editor.saveFailed')
+    }
+  }
+
+  async function submit(): Promise<SubmitResult> {
+    formError.value = ''
+    blockErrors.value = {}
+    // Clear the whole map, not just declared-field errors: `path`/`seo`/`status` are system columns
+    // (never in `fields.value`), so a stale server error on one of them would otherwise survive a
+    // later successful save. `validateAll` below repopulates every declared-field error fresh.
+    for (const k of Object.keys(errors)) delete errors[k]
+    // Client-side validation failed: surface the same banner the server path raises, so the failure is
+    // never silent — the offending field's inline error can sit in an unmounted pane (blocks editor).
+    if (!validateAll()) {
+      formError.value = t('editor.fixPageFields')
+      return { ok: false }
+    }
+    saving.value = true
+    try {
+      const body = buildBody()
+      // The optimistic-concurrency precondition: send the baseline `updatedAt` so a stale overwrite 409s
+      // instead of silently reverting a concurrent save. Omitted for a brand-new record (no baseline).
+      const ifUnmodified: Record<string, string> = baseUpdatedAt.value !== undefined ? { 'x-kestrel-if-unmodified-since': String(baseUpdatedAt.value) } : {}
+      // `method` cast: Nuxt's typed `$fetch` over-constrains the method for this dynamic (template-literal)
+      // admin route to GET; the runtime value is correct, only the static route type can't express it.
+      const row = mode.value === 'single'
+        ? await $fetch(`/api/${collection}`, { method: 'PUT' as never, body, headers: ifUnmodified, ...(translatable.value ? { query: { locale: activeLocale.value } } : {}) })
+        : id === 'new'
+          ? await $fetch(`/api/${collection}`, { method: 'POST' as never, body })
+          : await $fetch(`/api/${collection}/${id}`, { method: 'PATCH', body, headers: ifUnmodified })
+      rebaseline(row as Record<string, unknown>)
+      // `record` is the saved entity at the editor's public boundary; `row` stays the DB-layer term.
+      return { ok: true, record: row }
+    } catch (e) {
+      handleError(e)
+      return { ok: false }
+    } finally {
+      saving.value = false
+    }
+  }
+
+  const ready = init()
+
+  return {
+    collection,
+    locale: activeLocale,
+    translations,
+    deadRefs,
+    translationGroup,
+    applyFrom,
+    mode,
+    fields,
+    fieldLayout,
+    renderableFields,
+    translatable,
+    blocksEnabled,
+    blocksAllowed,
+    editorType,
+    pageLike,
+    hasSeo,
+    hasStatus,
+    values,
+    errors,
+    formError,
+    blockErrors,
+    dirty,
+    savedStatus,
+    savedPath,
+    saving,
+    ready,
+    setField,
+    validateAll,
+    submit,
+    undo,
+    redo,
+    canUndo,
+    canRedo,
+  }
+}

package/layers/admin/app/composables/useLinkResolver.ts

@@ -0,0 +1,40 @@
+import { reactive } from 'vue'
+
+/**
+ * Batched, cached client resolution of internal-link refs (`{collection, id}`) → public href,
+ * mirroring the server `resolveInternalHref` so the live preview's `KestrelLink` renders real internal
+ * paths instead of `'#'`. Per instance (no shared module state → SSR-safe). No locale param: an
+ * internal link points to one specific record, whose href is its own locale's path. Misses are cached
+ * (empty string) so a dangling (missing-target) ref isn't re-fetched on every preview recompute.
+ */
+export function useLinkResolver() {
+  const cache = reactive(new Map<string, string>())
+  const pending = new Set<string>()
+  const keyFor = (collection: string, id: number) => `${collection}:${id}`
+
+  async function ensure(refs: { collection: string; id: number }[]): Promise<void> {
+    const missing = refs.filter((r) =>
+      !!r.collection && Number.isInteger(r.id) && r.id > 0
+      && !cache.has(keyFor(r.collection, r.id)) && !pending.has(keyFor(r.collection, r.id)))
+    if (!missing.length) return
+    const keys = missing.map((r) => keyFor(r.collection, r.id))
+    for (const k of keys) pending.add(k)
+    try {
+      const { data } = await $fetch<{ data: { collection: string; id: number; href: string }[] }>(
+        '/api/links/resolve', { query: { refs: keys.join(',') } },
+      )
+      const got = new Map(data.map((d) => [keyFor(d.collection, d.id), d.href]))
+      for (const k of keys) cache.set(k, got.get(k) ?? '') // cache misses too, as '' → no re-fetch
+    } catch {
+      // leave unresolved — the preview shows '#' for these until a later attempt
+    } finally {
+      for (const k of keys) pending.delete(k)
+    }
+  }
+
+  function resolve(collection: string, id: number): string | null {
+    return cache.get(keyFor(collection, id)) || null
+  }
+
+  return { cache, ensure, resolve }
+}

package/layers/admin/app/composables/useListColumns.ts

@@ -0,0 +1,53 @@
+import type { Ref } from 'vue'
+import type { SerializedCollection } from '../../../core/server/utils/serialize-collection'
+import { availableColumns, defaultVisibleKeys, resolveVisibleColumns, type ListColumn } from '../utils/list-columns'
+
+/**
+ * Per-collection list column visibility, persisted in a cookie (SSR-safe, like the rail-collapsed state).
+ * The store maps collection name → the chosen visible keys; an absent entry falls back to the default set.
+ * Stale keys (a since-removed field) are dropped on read via `resolveVisibleColumns`.
+ */
+export function useListColumns(schema: Ref<SerializedCollection>) {
+  const store = useCookie<Record<string, string[]>>('kestrel-list-columns', { default: () => ({}) })
+
+  const available = computed<ListColumn[]>(() => availableColumns(schema.value))
+  const defaults = computed<string[]>(() => defaultVisibleKeys(schema.value))
+
+  const visibleKeys = computed<string[]>(() => {
+    const stored = store.value[schema.value.name]
+    // Project through the available columns so order is canonical and removed columns disappear.
+    return resolveVisibleColumns(available.value, stored ?? defaults.value).map((c) => c.key)
+  })
+  const visibleColumns = computed<ListColumn[]>(() => resolveVisibleColumns(available.value, visibleKeys.value))
+
+  function persist(keys: string[]) {
+    // Keep canonical order so persisted prefs round-trip stably.
+    const ordered = available.value.filter((c) => keys.includes(c.key)).map((c) => c.key)
+    store.value = { ...store.value, [schema.value.name]: ordered }
+  }
+
+  function toggle(key: string) {
+    const next = new Set(visibleKeys.value)
+    if (next.has(key)) {
+      if (next.size <= 1) return // never hide the last column
+      next.delete(key)
+    } else {
+      next.add(key)
+    }
+    persist([...next])
+  }
+
+  function reset() {
+    const next = { ...store.value }
+    delete next[schema.value.name]
+    store.value = next
+  }
+
+  const isDefault = computed(() => {
+    const a = visibleKeys.value
+    const b = defaults.value
+    return a.length === b.length && a.every((k, i) => k === b[i])
+  })
+
+  return { available, visibleColumns, visibleKeys, toggle, reset, isDefault }
+}

package/layers/admin/app/composables/useListUrlState.ts

@@ -0,0 +1,53 @@
+import type { Ref } from 'vue'
+import type { ListColumn } from '../utils/list-columns'
+import { toQuery, toggleSort, parseListQuery, type FilterCell, type ListState } from '../utils/list-query'
+import { clampPerPage, DEFAULT_PER_PAGE } from '../../../core/app/utils/list-limits'
+
+/**
+ * The URL is the SINGLE SOURCE OF TRUTH for a collection list's committed state (sort · page · perPage ·
+ * filter). This composable derives that state from `route.query` (sanitized via `parseListQuery`, so a
+ * hostile/partial URL degrades to defaults rather than reaching the server), and turns each mutation into a
+ * router navigation: `page` uses `push` (Back walks pages), everything else uses `replace` (typing / toggling
+ * must not spam history). Every non-page action also resets `page → 1`, so a page-only transition is the only
+ * one that ever differs by page alone — the push/replace split is exact.
+ *
+ * The per-page cookie is a DEFAULT, never state: when the URL carries no `perPage`, the initial value is
+ * seeded from the cookie (clamped); when perPage changes we write the cookie so a chosen density survives
+ * navigation. The URL always wins.
+ */
+export function useListUrlState(columns: Ref<ListColumn[]>) {
+  const route = useRoute()
+  const router = useRouter()
+  const perPageCookie = useCookie<number>('kestrel-list-per-page', { default: () => DEFAULT_PER_PAGE })
+
+  const parsed = computed(() => parseListQuery(route.query, columns.value))
+  const sort = computed(() => parsed.value.sort ?? '-createdAt')
+  const page = computed(() => parsed.value.page ?? 1)
+  const perPage = computed(() => parsed.value.perPage ?? clampPerPage(perPageCookie.value)) // URL wins, else cookie
+  const filter = computed(() => parsed.value.filter ?? {})
+  // The exact `$fetch` query the list endpoint expects — always the SANITIZED computeds, never the raw URL.
+  const effectiveQuery = computed(() => toQuery({ sort: sort.value, page: page.value, perPage: perPage.value, filter: filter.value }))
+
+  // We replace the WHOLE query on every navigation, so re-merge `locale` from the RAW URL (it lives outside
+  // the list-state keys and must survive a sort/page/filter change). Reading `route.query.locale` — NOT a
+  // resolved prop — keeps a locale-LESS URL locale-less after a list mutation: for a translatable collection
+  // the prop is the PRIMARY locale even when the URL carries no `?locale`, so merging it would inject
+  // `locale=<primary>`, flip the host page's `${collection}::${locale}` key and needlessly REMOUNT the list
+  // mid-edit. The locale switcher still navigates with an explicit `?locale`, which is preserved here (and
+  // correctly re-keys → remounts on a real locale switch).
+  function go(patch: Partial<ListState>, mode: 'push' | 'replace') {
+    const next: ListState = { sort: sort.value, page: page.value, perPage: perPage.value, filter: filter.value, ...patch }
+    const locale = route.query.locale
+    return router[mode]({ query: { ...toQuery(next), ...(typeof locale === 'string' ? { locale } : {}) } })
+  }
+
+  const setSort = (f: string) => go({ sort: toggleSort(sort.value, f), page: 1 }, 'replace')
+  const setPage = (p: number) => go({ page: p }, 'push')
+  // Corrective clamp (a page that emptied out from under us) — REPLACE, not push, so the now-invalid page
+  // doesn't stay a reachable history entry that Back bounces the user forward from on every press.
+  const clampPage = (p: number) => go({ page: p }, 'replace')
+  const setPerPage = (n: number) => { perPageCookie.value = clampPerPage(n); return go({ perPage: clampPerPage(n), page: 1 }, 'replace') }
+  const setFilter = (f: Record<string, FilterCell>) => go({ filter: f, page: 1 }, 'replace')
+
+  return { sort, page, perPage, filter, effectiveQuery, setSort, setPage, clampPage, setPerPage, setFilter }
+}

package/layers/admin/app/composables/usePendingPublishPoll.ts

@@ -0,0 +1,15 @@
+import { ref } from 'vue'
+
+// A create saves, then the host navigates the editor to the new record's own URL (`/new` → `/<id>`), which
+// tears down the editor that issued the save and remounts a fresh one at the real id. The republish it
+// kicked off is still in flight, so the ARRIVING editor must POLL the live status (not do a single refresh)
+// to catch the "Generating…" → "Live" transition. This module-scoped flag carries that intent across the
+// remount: the departing instance sets it on save, the arriving instance reads-and-clears it on mount.
+// Client-only ephemeral signal (set in a user save handler, read on mount) — a plain ref is enough; it never
+// runs during SSR, so there is no cross-request leakage.
+const pending = ref(false)
+
+/** Shared "the next editor mount should poll the live status" flag — see the note above. */
+export function usePendingPublishPoll() {
+  return pending
+}

package/layers/admin/app/composables/usePreviewViewport.ts

@@ -0,0 +1,30 @@
+import { computed } from 'vue'
+import type { Dim } from '../utils/preview-viewport'
+
+/**
+ * Persisted page-builder preview viewport: the target width/height as `Dim`s (a fixed px, or `'auto'`
+ * which fills the pane). Cookie-backed so the choice survives reloads and stays SSR-safe (server + client
+ * read the same value — no hydration mismatch), the same pattern as `useRailCollapsed`. Defaults to the
+ * config-driven desktop width with an `'auto'` height (fills the pane, no container scroll).
+ *
+ * Each setter reassigns the whole object (rather than mutating a field) so Nuxt's cookie watcher always
+ * re-serialises. Note: the seeded default only applies when the cookie is absent — if a project later
+ * changes `preview.desktopWidth`, an existing cookie keeps its `w` until the Desktop preset is clicked. A
+ * stale cookie from before Auto height (a numeric `h`, plus a now-ignored `fit`) is tolerated: it just
+ * reads as a fixed custom height until Desktop is re-selected.
+ */
+export interface PreviewViewport {
+  w: Dim
+  h: Dim
+}
+
+export function usePreviewViewport(desktopWidth: number) {
+  const state = useCookie<PreviewViewport>('kestrel-preview-viewport', {
+    default: () => ({ w: desktopWidth, h: 'auto' }),
+  })
+
+  const width = computed({ get: () => state.value.w, set: (v: Dim) => { state.value = { ...state.value, w: v } } })
+  const height = computed({ get: () => state.value.h, set: (v: Dim) => { state.value = { ...state.value, h: v } } })
+
+  return { width, height }
+}

package/layers/admin/app/composables/usePublishStatus.ts

@@ -0,0 +1,98 @@
+import { ref, toValue } from 'vue'
+import type { MaybeRefOrGetter } from 'vue'
+
+/** The live publish state of a record's static page, as returned by `GET /api/publish-status`. */
+export interface PublishStatusData {
+  route: string | null
+  status: 'success' | 'error' | null
+  error?: string | null
+  updatedAt?: string | null
+  /** Which output the last attempt wrote to — `'local'` dir or `'s3'` bucket; null when no row yet. */
+  target?: 'local' | 's3' | null
+  /** Whether the runtime publisher actually produces files in THIS environment (prod + `output.auto`).
+   *  `false` in dev / with static output off → a page can never turn "Live" here, so don't poll for it. */
+  generates?: boolean
+  /** The configured output destination (where the NEXT publish would go), independent of any row. */
+  driver?: 'local' | 's3'
+}
+
+const EMPTY: PublishStatusData = { route: null, status: null }
+
+/**
+ * Fetch (and refetch) the LIVE / generated publish state of the record the editor is on, for the right
+ * dot of the editor Ampel. Explicit `refresh()` (no auto-fetch) so it is testable in isolation and the
+ * caller controls timing: the editor refreshes on mount and again after each save (a save may (re)publish
+ * the page). Skips the request entirely when disabled (non-pageLike collection) or the record is unsaved
+ * (`id === 'new'` has no server row, hence no route yet). A failed fetch degrades to an empty status
+ * rather than surfacing an error — the ampel is a non-critical signal.
+ */
+export function usePublishStatus(args: {
+  collection: MaybeRefOrGetter<string>
+  id: MaybeRefOrGetter<string | number>
+  locale?: MaybeRefOrGetter<string | undefined>
+  enabled?: MaybeRefOrGetter<boolean>
+}) {
+  const data = ref<PublishStatusData>({ ...EMPTY })
+  // Bumped by every `refresh()` / `refreshUntilSettled()` start; an in-flight poll compares the token it
+  // captured and bails the moment a newer call supersedes it (navigation, another save), so stale loops
+  // can't keep writing to `data`.
+  let pollToken = 0
+
+  async function fetchOnce(): Promise<void> {
+    // Guard every write by the token captured at call time: if a newer refresh/poll supersedes this one
+    // while its request is in flight, its (possibly stale) response must NOT overwrite the fresher data —
+    // two overlapping fetches (a rapid re-save superseding a poll) can otherwise resolve out of order.
+    const token = pollToken
+    const enabled = args.enabled === undefined ? true : toValue(args.enabled)
+    const id = toValue(args.id)
+    if (!enabled || id === 'new' || id == null) {
+      if (token === pollToken) data.value = { ...EMPTY }
+      return
+    }
+    try {
+      const res = await $fetch<PublishStatusData>('/api/publish-status', {
+        query: { collection: toValue(args.collection), id, locale: toValue(args.locale) },
+      })
+      if (token === pollToken) data.value = res
+    } catch {
+      if (token === pollToken) data.value = { ...EMPTY }
+    }
+  }
+
+  /** One-shot fetch. Also cancels any running poll (this is the fresh source of truth). */
+  async function refresh(): Promise<void> {
+    pollToken++
+    await fetchOnce()
+  }
+
+  /**
+   * Poll the live status until it SETTLES, for the right lamp after a save: in prod a save enqueues an
+   * async (debounced) republish that finishes a moment later, so a single refresh would only ever catch the
+   * pre-republish row. Stops when the record has no route, the environment doesn't generate (`generates ===
+   * false` — dev / static output off: nothing will ever be produced, so polling is pointless), or a terminal
+   * outcome (`success`/`error`) from the NEW republish lands.
+   *
+   * `since` is the row's `updatedAt` BEFORE this save. `publish_status` is a latest-state upsert that is NOT
+   * cleared first, so a re-saved page keeps its prior success/error row until the fresh render rewrites it —
+   * without this baseline the very first poll would read that stale row and settle instantly (e.g. staying
+   * green "Live" for a re-save that actually failed to republish). So a terminal outcome only counts as
+   * settled once its `updatedAt` differs from `since`. Bounded by `attempts`; superseded-safe via `pollToken`.
+   */
+  async function refreshUntilSettled(opts?: { attempts?: number; delayMs?: number; since?: string | null }): Promise<void> {
+    const token = ++pollToken
+    const attempts = opts?.attempts ?? 12
+    const delayMs = opts?.delayMs ?? 2000
+    const since = opts?.since ?? null
+    for (let i = 0; i < attempts; i++) {
+      if (token !== pollToken) return
+      await fetchOnce()
+      if (token !== pollToken) return
+      const d = data.value
+      const settled = (d.status === 'success' || d.status === 'error') && (d.updatedAt ?? null) !== since
+      if (!d.route || d.generates === false || settled) return
+      if (i < attempts - 1) await new Promise((resolve) => setTimeout(resolve, delayMs))
+    }
+  }
+
+  return { data, refresh, refreshUntilSettled }
+}