@michaelthielemann/kestrel 1.2.1

package/layers/public/app/components/KestrelPreviewBridge.vue

@@ -0,0 +1,133 @@
+<script setup lang="ts">
+import { computed, nextTick, onMounted, onUnmounted, provide, ref, shallowRef } from 'vue'
+import { blockEditKey } from '../utils/block-edit-context'
+import {
+  parseEditorMessage, readyMessage, selectMessage,
+  type PreviewBlockNode,
+} from '../utils/preview-protocol'
+
+/**
+ * The iframe half of the editor live preview. Wraps the page's BlockRenderer via a scoped slot: it
+ * exposes the LIVE block tree (the editor's in-memory content, received over postMessage) — falling
+ * back to the server-rendered `blocks` prop until the first message — and provides the block-edit
+ * context so the renderer emits clickable, highlightable markers. Mounted only in preview mode
+ * (`?kestrel-preview=1` + admin, or the dedicated fallback page), and lazy-loaded there, so none of
+ * this ships in the normal public bundle.
+ *
+ * SECURITY: messages are trusted only when `event.origin` is OUR origin AND `event.source` is the
+ * embedding parent window — a third-party page that frames the site (or is framed by it) can never
+ * inject preview content. Outbound posts target our own origin only.
+ */
+const props = defineProps<{ blocks?: unknown[] }>()
+
+// Live tree: null until the editor's first content message, then always the message payload.
+// shallowRef — each message replaces the whole tree; BlockRenderer keys by block id.
+const live = shallowRef<PreviewBlockNode[] | null>(null)
+const blocks = computed<unknown[]>(() => live.value ?? (Array.isArray(props.blocks) ? props.blocks : []))
+
+// Selection: local state, synced both ways (click here → editor tree; tree click → highlight here).
+const selectedId = ref<string | null>(null)
+provide(blockEditKey, {
+  selectedId,
+  select: (id: string) => {
+    selectedId.value = id // highlight immediately; the editor echoes the selection back
+    post(selectMessage(id))
+  },
+})
+
+function post(msg: unknown) {
+  // Posting to self when opened directly (parent === window) is harmless — our own listener ignores
+  // frame→editor types — and keeping it unconditional keeps the handshake testable.
+  window.parent.postMessage(msg, window.location.origin)
+}
+
+function onMessage(e: MessageEvent) {
+  if (e.origin !== window.location.origin || e.source !== window.parent) return
+  const m = parseEditorMessage(e.data)
+  if (!m) return
+  if (m.kestrel === 'preview:content') {
+    const prev = selectedId.value
+    live.value = m.blocks
+    selectedId.value = m.selectedId
+    // A selection made while the frame was still loading arrives with the first content push (not as a
+    // separate selected message) — scroll to it like a live selection would.
+    if (m.selectedId && m.selectedId !== prev) void scrollToSelected(m.selectedId)
+  } else {
+    selectedId.value = m.selectedId
+    void scrollToSelected(m.selectedId)
+  }
+}
+
+// Bring an externally-selected block into view (tree-pane click in the editor).
+async function scrollToSelected(id: string | null) {
+  if (!id) return
+  await nextTick()
+  const el = Array.from(document.querySelectorAll('[data-block-id]')).find((n) => n.getAttribute('data-block-id') === id)
+  // The marker is `display: contents` (no box of its own), so scroll its rendered child instead.
+  ;(el?.firstElementChild ?? el)?.scrollIntoView({ block: 'nearest' })
+}
+
+// The preview is a canvas, not a browsing context: swallow every link navigation (consumer layout nav,
+// CTA anchors) AND form submission in the CAPTURE phase, so neither native navigation nor Vue Router
+// (which respects defaultPrevented) can steer the iframe away from the previewed page. Block clicks
+// still select — preventDefault does not stop propagation, so the marker handlers keep working.
+// (Programmatic navigation from consumer script can't be intercepted here; the editor host snaps the
+// frame back on load when its location no longer matches the preview URL.)
+function onClickCapture(e: MouseEvent) {
+  const a = (e.target as Element | null)?.closest?.('a[href]')
+  if (a) e.preventDefault()
+}
+function onSubmitCapture(e: Event) {
+  e.preventDefault()
+}
+
+onMounted(() => {
+  window.addEventListener('message', onMessage)
+  document.addEventListener('click', onClickCapture, true)
+  document.addEventListener('submit', onSubmitCapture, true)
+  // Handshake: tell the editor this document (fresh mount OR reload) is ready for the current state.
+  post(readyMessage())
+})
+onUnmounted(() => {
+  window.removeEventListener('message', onMessage)
+  document.removeEventListener('click', onClickCapture, true)
+  document.removeEventListener('submit', onSubmitCapture, true)
+})
+</script>
+
+<template>
+  <slot :blocks="blocks" />
+</template>
+
+<style lang="scss">
+// Selection chrome for the marker wrappers BlockRenderer emits when the edit context is present.
+// This document is the CONSUMER's public page (no admin design tokens), so the colors are concrete
+// values with overridable custom properties — a consumer can theme them from their own CSS.
+//
+// The marker itself is `display: contents`: it generates NO box, so the block root stays the parent's
+// real flex/grid ITEM exactly as on the published site — this restores flex/grid-item props, `gap`, and
+// breakpoints keyed to the block root, which a wrapper box would break by displacing the root. (It does
+// NOT change `>` combinators: the marker element is still in the DOM tree, so `parent > block-root`
+// rules match the same as before — unchanged either way.) The highlight chrome therefore lives on the
+// block root via `> *`. Events are unaffected — the marker div is still in the DOM/event path.
+.block-edit-marker {
+  display: contents;
+
+  > * {
+    cursor: pointer;
+    outline: 2px solid transparent;
+    outline-offset: -2px;
+    transition: outline-color 120ms ease;
+  }
+  &:hover > * {
+    outline-color: var(--kestrel-preview-hover, rgba(100, 116, 139, 0.55));
+  }
+  &--selected > * {
+    // Selection ring drawn with `outline` (not box-shadow) so a consumer block that carries its own root
+    // box-shadow keeps it while selected — a box-shadow ring here would replace it. Slightly thicker than
+    // the hover ring for contrast on dark/indigo consumer sites.
+    outline-color: var(--kestrel-preview-accent, #4f46e5);
+    outline-width: 3px;
+  }
+}
+</style>

package/layers/public/app/composables/public-page.ts

@@ -0,0 +1,24 @@
+import type { ComputedRef } from 'vue'
+
+export interface PublicPageState {
+  collection: string | null
+  page: Record<string, unknown> | null
+}
+
+/** The record rendered by the catch-all page, shared with layouts (language menu & co.); the page and a
+ *  layout share no other channel, so the catch-all mirrors its resolved `{ collection, page }` here. */
+export const usePublicPageState = () =>
+  useState<PublicPageState>('public-page', () => ({ collection: null, page: null }))
+
+/** Content locale of the current public route, derived from the URL prefix scheme. Reads the locale set
+ *  from `runtimeConfig.public` via the public-layer `pickPublicLocales` (NOT admin's `useContentLocales`,
+ *  which would make the public site depend on `layers/admin`). */
+export function usePublicLocale(): ComputedRef<string> {
+  const route = useRoute()
+  const { locales, primary, prefixPrimary } = pickPublicLocales(
+    useRuntimeConfig().public as { locales?: unknown; primaryLocale?: unknown; prefixPrimary?: unknown },
+  )
+  return computed(
+    () => resolvePublicRoute(route.path.split('/').filter(Boolean), locales, primary, prefixPrimary).locale,
+  )
+}

package/layers/public/app/error.vue

@@ -0,0 +1,12 @@
+<script setup lang="ts">
+import type { NuxtError } from '#app'
+defineProps<{ error: NuxtError }>()
+</script>
+
+<template>
+  <main>
+    <h1>{{ error.statusCode }}</h1>
+    <p>{{ error.statusCode === 404 ? 'Page not found.' : 'Something went wrong.' }}</p>
+    <NuxtLink to="/">Home</NuxtLink>
+  </main>
+</template>

package/layers/public/app/layouts/default.vue

@@ -0,0 +1,5 @@
+<template>
+  <main>
+    <slot />
+  </main>
+</template>

package/layers/public/app/pages/[...slug].vue

@@ -0,0 +1,157 @@
+<script setup lang="ts">
+interface RenderedPage {
+  title?: string
+  seo?: {
+    title?: string
+    description?: string
+    noindex?: boolean
+    $media?: { image?: { src: string; width: number | null; height: number | null } | null }
+  }
+  content?: unknown[]
+  status?: string
+}
+
+const route = useRoute()
+// Locale routing is config-driven (KESTREL_LOCALES / KESTREL_PRIMARY_LOCALE → runtimeConfig.public), NOT
+// hardcoded to en/de — otherwise every non-default locale's prerendered pages 404. Mirrors the server's
+// prefix scheme (primary unprefixed, others `/<locale>/…`) via the pure `resolvePublicRoute`.
+const { locales, primary, prefixPrimary } = pickPublicLocales(
+  useRuntimeConfig().public as { locales?: unknown; primaryLocale?: unknown; prefixPrimary?: unknown },
+)
+const { locale, path } = resolvePublicRoute(route.path.split('/').filter(Boolean), locales, primary, prefixPrimary)
+
+// Resolve across ALL pageLike collections (not just `pages`) via the generic route resolver, so a
+// consumer's own pageLike collection renders to static HTML too. `useRequestFetch` forwards the
+// incoming request's cookies to the SSR sub-fetch, so an authenticated admin's session reaches
+// `/api/route` and a draft renders at its real URL (the live preview); anonymous + the static render
+// stay published-only (the handler enforces it).
+const requestFetch = useRequestFetch()
+const { data: resolved } = await useAsyncData(`page:${locale}:${path}`, () =>
+  requestFetch('/api/route', {
+    query: { path, locale },
+  }).then((r) => r as {
+    collection: string | null
+    page: (RenderedPage & Record<string, unknown>) | null
+    alternates?: Array<{ locale: string; path: string }>
+  }),
+)
+const page = computed(() => resolved.value?.page ?? null)
+
+// The layout (language menu & co.) needs the resolved record and its collection; pages and layouts share
+// no other channel, so mirror the fetch result into the shared state — reactively, so client-side
+// navigations update it too.
+const pageState = usePublicPageState()
+watchEffect(() => {
+  pageState.value = {
+    collection: resolved.value?.collection ?? null,
+    page: resolved.value?.page ?? null,
+  }
+})
+
+// A draft only ever resolves here for an authenticated admin (anonymous + the static render are
+// published-only), so its presence is an unambiguous "you are previewing an unpublished page" signal.
+const isDraftPreview = computed(() => page.value?.status === 'draft')
+
+// Editor live-preview mode: `?kestrel-preview=1` AND an authenticated admin session. The session is
+// checked server-side (cookies forwarded, same seam as the draft fetch above) so SSR and hydration
+// agree on which branch renders; an anonymous visitor with the query param gets the normal page.
+// The bridge component is Lazy — its chunk (message channel + marker chrome) loads only in this mode.
+const previewRequested = route.query[PREVIEW_QUERY] === '1'
+const { data: previewSession } = previewRequested
+  ? await useAsyncData('kestrel-preview-session', () =>
+      requestFetch('/api/auth/session').catch(() => ({ authenticated: false })))
+  : { data: ref<{ authenticated: boolean } | null>(null) }
+const previewActive = computed(() => previewRequested && previewSession.value?.authenticated === true)
+
+// The site root stays reachable (empty document) before a home page is published;
+// any other unmatched path is a genuine 404.
+if (!page.value && path !== '/') throw createError({ statusCode: 404, statusMessage: 'Page not found' })
+
+// Canonical / Open Graph / twitter card / hreflang: pure model (`buildPageHead`) fed from the resolved
+// page + the public runtime config. Absolute-URL emissions (canonical, og:url, hreflang, relative
+// og:image) require a configured siteUrl and degrade away without one.
+const publicRc = useRuntimeConfig().public as { siteUrl?: string; siteName?: string }
+const seo = page.value?.seo ?? {}
+const head = buildPageHead({
+  siteUrl: typeof publicRc.siteUrl === 'string' ? publicRc.siteUrl : '',
+  siteName: typeof publicRc.siteName === 'string' ? publicRc.siteName : '',
+  path,
+  locale,
+  primary,
+  prefixPrimary,
+  title: seo.title || page.value?.title,
+  description: seo.description || undefined,
+  image: seo.$media?.image ?? null,
+  alternates: resolved.value?.alternates ?? [],
+})
+
+// Set the document language from the resolved locale so prerendered /de pages ship <html lang="de">
+// (WCAG 2.2 SC 3.1.1); without this every page would carry the build-default language.
+// Point AI agents at the generated llms.txt (alongside the robots.txt comment + sitemap) on every page.
+useHead({
+  htmlAttrs: { lang: locale },
+  link: [
+    ...(head.canonical ? [{ rel: 'canonical', href: head.canonical }] : []),
+    ...head.links,
+    { rel: 'alternate', type: 'text/markdown', href: '/llms.txt', title: 'llms.txt' },
+  ],
+})
+useSeoMeta({
+  title: seo.title || page.value?.title,
+  description: seo.description || undefined,
+  robots: seo.noindex ? 'noindex, nofollow' : undefined,
+  ogTitle: head.meta.ogTitle,
+  ogDescription: head.meta.ogDescription,
+  ogUrl: head.meta.ogUrl,
+  ogType: head.meta.ogType,
+  ogSiteName: head.meta.ogSiteName,
+  ogImage: head.meta.ogImage,
+  ogImageWidth: head.meta.ogImageWidth,
+  ogImageHeight: head.meta.ogImageHeight,
+  twitterCard: head.meta.twitterCard,
+})
+</script>
+
+<template>
+  <article>
+    <!-- Only ever shown to an authenticated admin previewing an unpublished page (drafts never resolve
+         for anonymous visitors or the static render), so it never ships to the public/static site.
+         Suppressed inside the editor preview iframe — the editor's own status ampel covers it. -->
+    <div v-if="isDraftPreview && !previewActive" class="kestrel-draft-badge" role="status">
+      <span class="kestrel-draft-badge__dot" aria-hidden="true" />
+      Draft preview — not published
+    </div>
+    <!-- Editor preview: the bridge swaps in the editor's live (unsaved) tree over postMessage and makes
+         blocks selectable; the saved content renders until the first message. Normal path unchanged. -->
+    <LazyKestrelPreviewBridge v-if="previewActive" :blocks="(page?.content as any[]) ?? []" v-slot="{ blocks }">
+      <BlockRenderer :blocks="(blocks as any[])" />
+    </LazyKestrelPreviewBridge>
+    <BlockRenderer v-else :blocks="(page?.content as any[]) ?? []" />
+  </article>
+</template>
+
+<style scoped>
+/* Self-contained (no token dependency) so it renders identically whatever layout the consumer ships. */
+.kestrel-draft-badge {
+  position: fixed;
+  inset-block-start: 0.75rem;
+  inset-inline-end: 0.75rem;
+  z-index: 2147483647;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.4rem;
+  padding: 0.35rem 0.7rem;
+  border-radius: 999px;
+  background: #1e293b;
+  color: #fff;
+  font: 600 0.78rem/1 ui-sans-serif, system-ui, sans-serif;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.25);
+  pointer-events: none;
+}
+.kestrel-draft-badge__dot {
+  width: 0.5rem;
+  height: 0.5rem;
+  border-radius: 50%;
+  background: #fbbf24;
+}
+</style>

package/layers/public/app/pages/__kestrel/preview.vue

@@ -0,0 +1,34 @@
+<script setup lang="ts">
+/**
+ * Dedicated editor live-preview page for records WITHOUT a public URL — a new/unsaved record, a blank
+ * slug, or a blocks-enabled non-pageLike collection. It renders the real public app (default layout,
+ * the consumer's CSS/fonts/breakpoints) around an empty BlockRenderer that the editor fills over the
+ * postMessage bridge. Saved pageLike records preview at their REAL URL instead (higher fidelity);
+ * this page is the graceful fallback so previews never regress to "save first".
+ *
+ * Admin-gated server-side: `useRequestFetch` forwards the incoming cookies to `/api/auth/session`
+ * (the same seam the catch-all uses for draft rendering), and anonymous requests get a 404 — the
+ * page's existence is not advertised. It is never linked, prerendered, or published (the publisher
+ * enumerates DB page rows only), and carries noindex as belt-and-braces.
+ */
+const requestFetch = useRequestFetch()
+const { data: session } = await useAsyncData('kestrel-preview-session', () =>
+  requestFetch('/api/auth/session').catch(() => ({ authenticated: false })),
+)
+if (!session.value?.authenticated) throw createError({ statusCode: 404, statusMessage: 'Page not found' })
+
+// Content locale from the editor (drives <html lang> for faithful per-locale rendering).
+const route = useRoute()
+const lang = typeof route.query.locale === 'string' && route.query.locale ? route.query.locale : undefined
+useHead({
+  title: 'Preview',
+  meta: [{ name: 'robots', content: 'noindex, nofollow' }],
+  ...(lang ? { htmlAttrs: { lang } } : {}),
+})
+</script>
+
+<template>
+  <KestrelPreviewBridge v-slot="{ blocks }">
+    <BlockRenderer :blocks="(blocks as any[])" />
+  </KestrelPreviewBridge>
+</template>

package/layers/public/app/utils/block-edit-context.ts

@@ -0,0 +1,16 @@
+import type { InjectionKey, Ref } from 'vue'
+
+// Optional editing context for the public BlockRenderer. On the generated public site the renderer is
+// used WITHOUT this context (inject defaults to null) → it renders plain markup, byte-identical to
+// before. The admin preview *provides* it, which makes the renderer wrap each block in a clickable
+// marker carrying its id — so clicking a block in the preview selects it and the selected block is
+// highlighted. This keeps the SSG render path untouched while letting the same component double as a
+// selection-aware editor preview.
+export interface BlockEditContext {
+  /** The currently selected block id (or null for the page root). */
+  selectedId: Ref<string | null>
+  /** Select a block by id (from a preview click). */
+  select: (id: string) => void
+}
+
+export const blockEditKey: InjectionKey<BlockEditContext> = Symbol('kestrel.blockEdit')

package/layers/public/app/utils/link-href.ts

@@ -0,0 +1,46 @@
+import type { LinkValue } from '../../../core/server/utils/defineCollection'
+
+// The server link populator (depth > 0) resolves an internal link's localized target path and attaches
+// it as `href`. Until that populator runs (or for a not-yet-resolved value), internal links fall back
+// to '#'. external / email / tel are self-contained and need no resolution.
+type WithHref<T> = T & { href?: string }
+
+/** Turn any `LinkValue` into an `href`. external → the url; email → `mailto:`; tel → `tel:`; internal →
+ *  the populated `href` (localized target path), or '#' when unresolved. Empty string for no value. */
+export function linkToHref(value: WithHref<LinkValue> | null | undefined): string {
+  if (!value) return ''
+  switch (value.type) {
+    case 'external':
+      return value.url
+    case 'email':
+      return `mailto:${value.email}`
+    case 'tel':
+      return `tel:${value.tel}`
+    case 'internal': {
+      const base = value.href ?? '#'
+      // An unresolved internal (draft/missing target) stays '#'; don't fabricate a fragment-only link
+      // out of its hash. A resolved path gets `#<hash>` appended when present.
+      return base !== '#' && value.hash ? `${base}#${value.hash}` : base
+    }
+    default:
+      return ''
+  }
+}
+
+/** A human label for a link: its explicit `label`, else a scheme-appropriate default (the target). */
+export function linkLabel(value: WithHref<LinkValue> | null | undefined): string {
+  if (!value) return ''
+  if (value.label) return value.label
+  switch (value.type) {
+    case 'external':
+      return value.url
+    case 'email':
+      return value.email
+    case 'tel':
+      return value.tel
+    case 'internal':
+      return value.href ?? ''
+    default:
+      return ''
+  }
+}

package/layers/public/app/utils/page-head.ts

@@ -0,0 +1,84 @@
+import { localePath } from '../../../core/app/utils/locale-path'
+
+export interface PageHeadImage { src: string; width?: number | null; height?: number | null }
+export interface PageHeadAlternate { locale: string; path: string }
+
+export interface PageHeadInput {
+  /** Absolute site origin ('' when unconfigured — canonical/hreflang/og:url are omitted then). */
+  siteUrl: string
+  siteName?: string
+  /** The page's unprefixed path + its locale (the emitter locale-prefixes via `localePath`). */
+  path: string
+  locale: string
+  primary: string
+  prefixPrimary: boolean
+  title?: string
+  description?: string
+  image?: PageHeadImage | null
+  /** Published translation siblings (self included); [] / omitted → no hreflang set. */
+  alternates?: PageHeadAlternate[]
+}
+
+/** A type alias, not an interface: unhead's `link` entries require an implicit `data-*` index signature,
+ *  which TS derives for aliases but never for interfaces. */
+export type PageHeadLink = { rel: 'alternate'; hreflang: string; href: string }
+
+export interface PageHead {
+  canonical?: string
+  links: PageHeadLink[]
+  meta: {
+    ogTitle?: string
+    ogDescription?: string
+    ogUrl?: string
+    ogType: 'website'
+    ogSiteName?: string
+    ogImage?: string
+    ogImageWidth?: number
+    ogImageHeight?: number
+    twitterCard: 'summary' | 'summary_large_image'
+  }
+}
+
+const isAbsolute = (src: string) => /^https?:\/\//.test(src)
+
+/**
+ * The head model for a rendered public page: canonical, Open Graph / twitter card, and the hreflang
+ * alternate set — pure, so the emission rules are unit-testable outside a Nuxt context. Everything that
+ * requires an absolute URL (canonical, og:url, hreflang, a relative og:image) degrades away when
+ * `siteUrl` is unconfigured; `x-default` points at the primary-locale variant when it is present
+ * (mirrors the sitemap's rules, so page heads and sitemap never disagree).
+ */
+export function buildPageHead(input: PageHeadInput): PageHead {
+  const base = input.siteUrl ? input.siteUrl.replace(/\/+$/, '') : ''
+  const abs = (path: string, locale: string) => `${base}${localePath(path, locale, input.primary, input.prefixPrimary)}`
+  const canonical = base ? abs(input.path, input.locale) : undefined
+
+  const links: PageHeadLink[] = []
+  if (base && input.alternates?.length) {
+    for (const a of input.alternates) links.push({ rel: 'alternate', hreflang: a.locale, href: abs(a.path, a.locale) })
+    const primary = input.alternates.find((a) => a.locale === input.primary)
+    if (primary) links.push({ rel: 'alternate', hreflang: 'x-default', href: abs(primary.path, primary.locale) })
+  }
+
+  let ogImage: string | undefined
+  if (input.image?.src) {
+    if (isAbsolute(input.image.src)) ogImage = input.image.src
+    else if (base) ogImage = `${base}${input.image.src}`
+  }
+
+  return {
+    canonical,
+    links,
+    meta: {
+      ogTitle: input.title || undefined,
+      ogDescription: input.description || undefined,
+      ogUrl: canonical,
+      ogType: 'website',
+      ogSiteName: input.siteName || undefined,
+      ogImage,
+      ogImageWidth: ogImage && input.image?.width ? input.image.width : undefined,
+      ogImageHeight: ogImage && input.image?.height ? input.image.height : undefined,
+      twitterCard: ogImage ? 'summary_large_image' : 'summary',
+    },
+  }
+}

package/layers/public/app/utils/preview-protocol.ts

@@ -0,0 +1,81 @@
+/**
+ * The postMessage protocol between the admin block editor (parent window) and the live-preview iframe
+ * (the real public page in preview mode). Pure — shared by both sides and unit-tested here; the DOM
+ * wiring lives in the editor's preview host and the public `KestrelPreviewBridge`.
+ *
+ * Every message carries a `kestrel: 'preview:*'` discriminant so foreign postMessage traffic (HMR,
+ * browser extensions) can never be mistaken for ours. Parsing is direction-specific: the frame only
+ * accepts editor→frame types and vice versa — a reflected/echoed message parses to `null`.
+ * SECURITY: parsing validates SHAPE only. Both sides must additionally check `event.origin` against
+ * their own origin and `event.source` against the expected window before trusting a message —
+ * otherwise any page that embeds the site (or is embedded by it) could inject content.
+ */
+
+/** Query flag that switches the public page into preview mode (value `1`). */
+export const PREVIEW_QUERY = 'kestrel-preview'
+/** Dedicated preview page for records without a public URL (new/unsaved, non-pageLike). Admin-gated. */
+export const PREVIEW_FALLBACK_PATH = '/__kestrel/preview'
+
+/** The block-node shape the renderer consumes (already media/link-populated by the editor). */
+export interface PreviewBlockNode { id?: string; type: string; props?: Record<string, unknown>; slots?: Record<string, unknown> }
+
+/** editor → frame: the live (populated) block tree + the current selection. */
+export interface PreviewContentMessage { kestrel: 'preview:content'; blocks: PreviewBlockNode[]; selectedId: string | null }
+/** editor → frame: selection changed (tree click) — highlight + scroll into view. */
+export interface PreviewSelectedMessage { kestrel: 'preview:selected'; selectedId: string | null }
+/** frame → editor: the bridge mounted (or the iframe reloaded) — (re)send the full state. */
+export interface PreviewReadyMessage { kestrel: 'preview:ready' }
+/** frame → editor: a block was clicked in the preview. */
+export interface PreviewSelectMessage { kestrel: 'preview:select'; id: string }
+
+export type EditorToFrameMessage = PreviewContentMessage | PreviewSelectedMessage
+export type FrameToEditorMessage = PreviewReadyMessage | PreviewSelectMessage
+
+export const contentMessage = (blocks: PreviewBlockNode[], selectedId: string | null): PreviewContentMessage =>
+  ({ kestrel: 'preview:content', blocks, selectedId })
+export const selectedMessage = (selectedId: string | null): PreviewSelectedMessage =>
+  ({ kestrel: 'preview:selected', selectedId })
+export const readyMessage = (): PreviewReadyMessage => ({ kestrel: 'preview:ready' })
+export const selectMessage = (id: string): PreviewSelectMessage => ({ kestrel: 'preview:select', id })
+
+function tagOf(data: unknown): string | null {
+  if (typeof data !== 'object' || data === null || Array.isArray(data)) return null
+  const tag = (data as { kestrel?: unknown }).kestrel
+  return typeof tag === 'string' ? tag : null
+}
+
+/** Parse a message the FRAME received (editor → frame); `null` for anything else. */
+export function parseEditorMessage(data: unknown): EditorToFrameMessage | null {
+  const tag = tagOf(data)
+  if (tag === 'preview:content') {
+    const m = data as PreviewContentMessage
+    return Array.isArray(m.blocks) && (m.selectedId === null || typeof m.selectedId === 'string') ? m : null
+  }
+  if (tag === 'preview:selected') {
+    const m = data as PreviewSelectedMessage
+    return m.selectedId === null || typeof m.selectedId === 'string' ? m : null
+  }
+  return null
+}
+
+/** Parse a message the EDITOR received (frame → editor); `null` for anything else. */
+export function parseFrameMessage(data: unknown): FrameToEditorMessage | null {
+  const tag = tagOf(data)
+  if (tag === 'preview:ready') return data as PreviewReadyMessage
+  if (tag === 'preview:select') {
+    const m = data as PreviewSelectMessage
+    return typeof m.id === 'string' ? m : null
+  }
+  return null
+}
+
+/**
+ * The iframe URL for the editor's preview pane: the record's real public URL when it has one (saved
+ * pageLike record — server-populated first paint, drafts included for the admin session), else the
+ * dedicated fallback page (new/unsaved records, non-pageLike collections). Both carry the preview flag.
+ */
+export function previewSrc(publicUrl: string | null, locale: string): string {
+  if (publicUrl) return `${publicUrl}?${PREVIEW_QUERY}=1`
+  const loc = locale ? `&locale=${encodeURIComponent(locale)}` : ''
+  return `${PREVIEW_FALLBACK_PATH}?${PREVIEW_QUERY}=1${loc}`
+}

package/layers/public/app/utils/public-route.ts

@@ -0,0 +1,46 @@
+/**
+ * Resolve the request locale + the lookup path from the URL path segments, matching the server routing
+ * (`localePath`): every non-primary configured locale is prefixed `/<locale>/…`; the primary locale is
+ * unprefixed unless `prefixPrimary` is set (then `/<primary>/…` too). A leading segment counts as a locale
+ * prefix when it is a configured locale (the primary only when `prefixPrimary`); anything else is part of
+ * the path under the primary locale. Pure (no runtime-config access) so it is unit-testable and not
+ * en/de-hardcoded.
+ */
+/** Config shape read off `runtimeConfig.public` (a subset). */
+export interface PublicLocaleConfig {
+  locales?: unknown
+  primaryLocale?: unknown
+  prefixPrimary?: unknown
+}
+
+/**
+ * Resolve the configured content locales from a `runtimeConfig.public`-shaped object. Pure, so the
+ * fallback/primary logic is unit-testable without a Nuxt context, and lives in the PUBLIC layer so
+ * public code (the catch-all page + `usePublicLocale`) never has to reach into `layers/admin` for it.
+ * The `['en']` fallback is a safe last resort for an absent/empty config (nuxt.config always sets
+ * `public.locales`); primary-only is a safer guess than assuming a second locale exists.
+ */
+export function pickPublicLocales(pub: PublicLocaleConfig): {
+  locales: string[]
+  primary: string
+  prefixPrimary: boolean
+} {
+  const locales = Array.isArray(pub.locales) && pub.locales.length ? pub.locales.map(String) : ['en']
+  const primary =
+    typeof pub.primaryLocale === 'string' && locales.includes(pub.primaryLocale) ? pub.primaryLocale : locales[0]!
+  return { locales, primary, prefixPrimary: pub.prefixPrimary === true }
+}
+
+export function resolvePublicRoute(
+  segments: string[],
+  locales: string[],
+  primaryLocale: string,
+  prefixPrimary = false,
+): { locale: string; path: string } {
+  const head = segments[0]?.toLowerCase()
+  const prefixed = head !== undefined && locales.includes(head) && (head !== primaryLocale || prefixPrimary)
+  const locale = prefixed ? head : primaryLocale
+  const rest = prefixed ? segments.slice(1) : segments
+  const path = ('/' + rest.join('/')).toLowerCase().replace(/\/+$/, '') || '/'
+  return { locale, path }
+}