@michaelthielemann/kestrel 1.3.0 → 1.4.0

package/layers/admin/app/components/PageFields.vue

@@ -25,6 +25,11 @@ const props = defineProps<{
 const emit = defineEmits<{ update: [name: string, value: unknown] }>()
 const { t } = useT()
 
+// A project with a single layout has nothing to choose, so the control stays out of the pane entirely
+// rather than offering one dead option.
+const layoutOptions = computed(() => layoutSelectOptions(useOfferableLayouts(), t('pageSettings.layoutDefault')))
+const showLayout = computed(() => !!props.pageLike && layoutOptions.value.length > 1)
+
 // Live preview of the slug the server will auto-generate from the title while the field is left blank
 // (the server slugifies the title on save). Falls back to '/' when there is no title yet.
 const slugPlaceholder = computed(() => {
@@ -88,6 +93,26 @@ const slugPlaceholder = computed(() => {
     </template>
   </UiField>
 
+  <!-- Which layout renders this page (the `layout` system column). Empty = the `default` layout, so an
+       unset value keeps rendering exactly as a project without the column. -->
+  <UiField
+    v-if="showLayout"
+    class="page-settings__layout"
+    :label="t('pageSettings.layoutLabel')"
+    :hint="t('pageSettings.layoutHint')"
+    :error="errors.layout || null"
+  >
+    <template #default="f">
+      <UiSelect
+        :model-value="(values.layout as string) ?? ''"
+        :options="layoutOptions"
+        :disabled="disabled"
+        v-bind="f"
+        @update:model-value="(v) => emit('update', 'layout', v)"
+      />
+    </template>
+  </UiField>
+
   <!-- Page SEO (meta title/description/noindex + Google preview). The `seo` JSON system column. -->
   <SeoFields
     v-if="seo"

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

@@ -135,6 +135,8 @@ export function useEditForm(opts: UseEditFormOptions) {
     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) ?? ''
+    // '' is the "no override" form the select binds to.
+    if (pageLike.value) next.layout = (source?.layout 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.
@@ -261,6 +263,9 @@ export function useEditForm(opts: UseEditFormOptions) {
     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
+    // An unset layout is stored as NULL, never '': the render coalesces NULL to `default`, and a stored ''
+    // would be indistinguishable from a name that failed to save.
+    if (pageLike.value) body.layout = (values.layout as string) || 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

package/layers/core/app/composables/layouts.ts

@@ -0,0 +1,5 @@
+import { kestrelLayouts } from '#build/kestrel-layouts.mjs'
+
+export function useOfferableLayouts(): string[] {
+  return kestrelLayouts
+}

package/layers/core/app/utils/layouts.ts

@@ -0,0 +1,38 @@
+/** The admin shell. Never offerable for a public record — a page rendered inside it would carry the
+ *  admin chrome and its own `useHead`. */
+export const ADMIN_LAYOUT = 'admin'
+
+/** Nuxt's resolved `app.layouts` entry (`nuxt.options.app.layouts`, filled before the `app:resolve` hook). */
+export interface ResolvedLayout { name: string, file: string }
+
+/**
+ * The layout names a page may be assigned, from Nuxt's own resolved layout map. Nuxt has already done the
+ * layer-ordered, name-first dedup (a consumer's `default.vue` shadows the engine's), so this only filters
+ * and sorts — no directory scan of our own.
+ */
+export function offerableLayouts(layouts: Record<string, ResolvedLayout | undefined>): string[] {
+  return Object.values(layouts)
+    .filter((l): l is ResolvedLayout => !!l && typeof l.file === 'string' && l.file.endsWith('.vue'))
+    .map((l) => l.name)
+    .filter((name) => name !== ADMIN_LAYOUT)
+    .sort()
+}
+
+export function renderLayoutRegistry(names: string[]): string {
+  return `export const kestrelLayouts = ${JSON.stringify(names)}\n`
+}
+
+/**
+ * Options for the page-layout select. The fallback is one entry with an EMPTY value — an unset column
+ * already renders `default`, so offering `default` as its own value would give the editor two controls for
+ * one outcome and pin the row to a name the consumer may later rename.
+ */
+export function layoutSelectOptions(names: string[], fallbackLabel: string): { label: string, value: string }[] {
+  return [
+    { label: fallbackLabel, value: '' },
+    ...names.filter((n) => n !== DEFAULT_LAYOUT_NAME).map((n) => ({ label: n, value: n })),
+  ]
+}
+
+/** Mirrors `DEFAULT_LAYOUT` in the public layer; kept local so this util stays dependency-free. */
+const DEFAULT_LAYOUT_NAME = 'default'

package/layers/core/modules/auto-discovery/index.ts

@@ -1,8 +1,9 @@
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
-import { addComponentsDir, addTypeTemplate, createResolver, defineNuxtModule } from '@nuxt/kit'
+import { addComponentsDir, addTemplate, addTypeTemplate, createResolver, defineNuxtModule } from '@nuxt/kit'
 import { collectBlockSfcs, collectDefinitions, renderRegistry } from './scan'
 import { renderBlockRegistry } from './extract-block'
+import { offerableLayouts, renderLayoutRegistry } from '../../app/utils/layouts'
 
 export default defineNuxtModule({
   meta: { name: 'kestrel-auto-discovery' },
@@ -22,6 +23,15 @@ export default defineNuxtModule({
       if (existsSync(dir)) addComponentsDir({ path: dir, prefix: 'Blocks', global: true, pathPrefix: false })
     }
 
+    // Layouts need no scan of our own: Nuxt already resolves `app/layouts/*.vue` across the layers with the
+    // same name-first, consumer-wins dedup, and fills `app.layouts` just before `app:resolve` — which runs
+    // inside `generateApp`, ahead of the templates being written, so the closure below is filled in time.
+    let layoutNames: string[] = []
+    nuxt.hook('app:resolve', (app) => { layoutNames = offerableLayouts(app.layouts ?? {}) })
+    // `write` so the resolved list is inspectable in `.nuxt/` — a virtual-only template makes "which layouts
+    // did the build actually find" unanswerable without a debugger.
+    addTemplate({ filename: 'kestrel-layouts.mjs', write: true, getContents: () => renderLayoutRegistry(layoutNames) })
+
     nuxt.hook('nitro:config', (nitro) => {
       nitro.virtual ||= {}
       // Consumer field types register as a side effect on import, and the schema engine builds a table the

package/layers/core/modules/auto-discovery/virtual.d.ts

@@ -10,3 +10,6 @@ declare module '#kestrel/schema-tables' {
   const tables: unknown[]
   export default tables
 }
+declare module '#build/kestrel-layouts.mjs' {
+  export const kestrelLayouts: string[]
+}

package/layers/fields/server/utils/buildTable.ts

@@ -17,7 +17,7 @@ function reservedColumns(def: CollectionDef): { js: Set<string>; db: Set<string>
   if (def.translatable) add('locale', 'locale')
   if (def.mode === 'single') add('singletonKey', 'singleton_key')
   else if (def.translatable) add('translationGroup', 'translation_group')
-  if (def.pageLike) add('path', 'path')
+  if (def.pageLike) { add('path', 'path'); add('layout', 'layout') }
   if (def.status) add('status', 'status')
   if (def.seo) add('seo', 'seo')
   if (def.blocks?.enabled) add('content', 'content')
@@ -67,7 +67,13 @@ export function buildTable(def: CollectionDef): SQLiteTable {
   if (def.translatable) cols.locale = text('locale').notNull()
   if (def.mode === 'single') cols.singletonKey = text('singleton_key').notNull()
   else if (def.translatable) cols.translationGroup = text('translation_group').notNull()
-  if (def.pageLike) cols.path = text('path')
+  if (def.pageLike) {
+    cols.path = text('path')
+    // Nullable with no default: an editor's "inherit" must be distinguishable from an explicit `default`,
+    // and the render decides the fallback (see resolvePageLayout) so a deleted layout file degrades in one
+    // place instead of being frozen into every row.
+    cols.layout = text('layout')
+  }
   if (def.status) cols.status = text('status').notNull().default('draft')
   if (def.seo) cols.seo = text('seo', { mode: 'json' }).$type<SeoMeta>().notNull().default(sql`'{}'`)
   if (def.blocks?.enabled) cols.content = text('content', { mode: 'json' }).$type<Block[]>().notNull().default(sql`'[]'`)

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

@@ -1,6 +1,14 @@
 <script setup lang="ts">
+import type { LayoutKey } from 'nuxt/app'
+
+// The record decides its own layout, so route-meta resolution is opted out of and this page renders the
+// `<NuxtLayout>` itself. Side effect worth knowing: the layout becomes a CHILD of the page, so it can read
+// `usePublicPageState()` during SSR — as its parent it rendered before the page had written it.
+definePageMeta({ layout: false })
+
 interface RenderedPage {
   title?: string
+  layout?: string | null
   seo?: {
     title?: string
     description?: string
@@ -36,6 +44,12 @@ const { data: resolved } = await useAsyncData(`page:${locale}:${path}`, () =>
   }),
 )
 const page = computed(() => resolved.value?.page ?? null)
+// `fallback` below only rescues a truthy name that is missing from the layout map, so the empty cases have
+// to be coalesced here — see resolvePageLayout. The cast is the one honest bridge in this file: the stored
+// name is arbitrary editor data, while `NuxtLayout` types `name` as the union of layouts that existed at
+// build time. Narrowing to that union is impossible for a value read from the DB, and `fallback` is exactly
+// the runtime guard for a name outside it.
+const pageLayout = computed(() => resolvePageLayout(page.value?.layout) as LayoutKey)
 
 // 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
@@ -113,21 +127,23 @@ useSeoMeta({
 </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>
+  <NuxtLayout :name="pageLayout" fallback="default">
+    <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>
+  </NuxtLayout>
 </template>
 
 <style scoped>

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

@@ -0,0 +1,18 @@
+/** The layout every page falls back to. Nuxt's own name for the unnamed layout, and the one the public
+ *  layer ships (`layers/public/app/layouts/default.vue`), so it is always present. */
+export const DEFAULT_LAYOUT = 'default'
+
+/**
+ * The layout name to render a page in, from its stored `layout` column.
+ *
+ * Must never return an empty value. The catch-all declares `definePageMeta({ layout: false })` so the page
+ * owns its own `<NuxtLayout>`; that makes `route.meta.layout` the literal `false`, and NuxtLayout resolves
+ * `unref(props.name) ?? route.meta.layout ?? …` — `??` keeps `false`, which fails its `hasLayout` check and
+ * renders the page with NO layout wrapper. The `fallback` prop does not cover this: it only applies to a
+ * truthy name absent from the layout map. Coalescing here is what keeps an unset column rendering the
+ * normal site frame.
+ */
+export function resolvePageLayout(stored: string | null | undefined): string {
+  const name = typeof stored === 'string' ? stored.trim() : ''
+  return name || DEFAULT_LAYOUT
+}

package/layers/ui/app/i18n/de.ts

@@ -133,6 +133,9 @@ export const de: Catalog = {
 
   'pageSettings.slugLabel': 'Slug',
   'pageSettings.slugHint': 'URL-Pfad, z. B. /about (leer = automatisch aus dem Titel)',
+  'pageSettings.layoutLabel': 'Layout',
+  'pageSettings.layoutHint': 'Mit welchem Layout diese Seite gerendert wird.',
+  'pageSettings.layoutDefault': 'Standard (default)',
   'pageSettings.statusLabel': 'Status',
   'pageSettings.statusHint': 'Entwurf bleibt offline; Veröffentlicht rendert die Seite.',
   'pageSettings.statusDraft': 'Entwurf',

package/layers/ui/app/i18n/en.ts

@@ -144,6 +144,9 @@ export const en: Catalog = {
   // page settings (system fields on pageLike collections)
   'pageSettings.slugLabel': 'Slug',
   'pageSettings.slugHint': 'URL path, e.g. /about (blank = auto-generated from the title)',
+  'pageSettings.layoutLabel': 'Layout',
+  'pageSettings.layoutHint': 'Which layout renders this page.',
+  'pageSettings.layoutDefault': 'Standard (default)',
   'pageSettings.statusLabel': 'Status',
   'pageSettings.statusHint': 'Draft stays off the live site; Published renders it.',
   'pageSettings.statusDraft': 'Draft',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@michaelthielemann/kestrel",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "A slim, collection-driven Nuxt 4 CMS meta-layer with a runtime schema engine. Add `extends: ['@michaelthielemann/kestrel']`, define collections, and the database migrates itself.",
   "license": "Apache-2.0",
   "author": "Michael Thielemann <283621694+MichaelThielemann@users.noreply.github.com>",

package/scripts/copy-create-payload.mjs

@@ -13,11 +13,6 @@ const manifestPath = join(PKG, 'package.json')
 
 const clean = () => {
   for (const entry of GENERATED) rmSync(join(PKG, entry), { recursive: true, force: true })
-  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'))
-  if (manifest['//engine']) {
-    delete manifest['//engine']
-    writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`)
-  }
 }
 
 if (process.argv.includes('--clean')) {
@@ -42,11 +37,13 @@ if (process.argv.includes('--clean')) {
     if (existsSync(join(ROOT, file))) cpSync(join(ROOT, file), join(PKG, file))
   }
 
-  // Stamped so the scaffolded manifest pins the ranges the engine actually resolves.
-  manifest['//engine'] = {
+  // A generated file, not a key in the committed manifest: `postpack` is not guaranteed to run (a failed
+  // publish skips it), and a stamp left behind in package.json would be committed and then silently pin
+  // stale ranges. Deleting `lib/` removes this with everything else.
+  const stamp = {
     nuxt: engine.dependencies?.nuxt,
     typescript: engine.dependencies?.typescript,
     'vue-tsc': engine.devDependencies?.['vue-tsc'],
   }
-  writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`)
+  writeFileSync(join(PKG, 'lib', 'engine-meta.mjs'), `export default ${JSON.stringify(stamp, null, 2)}\n`)
 }