@bakery-framework/plugin-vue 1.2.3 → 2.0.0-alpha.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bakery-framework/plugin-vue",
-  "version": "1.2.3",
+  "version": "2.0.0-alpha.2",
   "description": "Bakery vue plugin.",
   "keywords": [
     "bakery",
@@ -25,6 +25,7 @@
   "main": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
+    "./client": "./src/client.ts",
     "./package.json": "./package.json",
     "./vue.d.ts": "./src/vue.d.ts"
   },
@@ -42,7 +43,7 @@
     "vue": "^3.5.38"
   },
   "dependencies": {
-    "@bakery-framework/core": "^1.0.0"
+    "@bakery-framework/core": "^1.2.3"
   },
   "engines": {
     "bun": ">=1.3.14"

package/src/chunks.ts

@@ -2,6 +2,7 @@ import { Bakery } from '@bakery-framework/core/core/bakery'
 import { Logger } from '@bakery-framework/core/logger'
 import { fs, response } from '@bakery-framework/core/utils'
 import { ETag } from '@bakery-framework/core/utils/http'
+import { vueBuildVariant } from './compile'
 import { VUE_VERSION } from './utils'
 
 const logger = new Logger('vue')
@@ -14,21 +15,43 @@ const BUNDLE_DEFINES = {
   __VUE_PROD_HYDRATION_MISMATCH_DETAILS__: 'false',
 }
 
+const VUE_ENTRIES = {
+  runtime: 'vue/dist/vue.runtime.esm-bundler.js',
+  full: 'vue/dist/vue.esm-bundler.js',
+} as const
+
+/**
+ * The one canonical URL for the served Vue build — the import-map alias
+ * (`setup.ts`) and the request check below both read it, so they cannot drift.
+ *
+ * The variant is part of the filename, not just of the entry choice, because
+ * the chunk cache is keyed on this name with the *source's* mtime: flipping
+ * `build` in `server.config.ts` does not touch `vue.esm-bundler.js` on disk,
+ * so a shared name would keep serving the previous variant out of cache
+ * indefinitely.
+ */
+export function vueChunkPath(): string {
+  return `${VUE_CHUNK_PREFIX}${VUE_VERSION}.${vueBuildVariant()}.js`
+}
+
 /** Serves the self-hosted Vue runtime that `Bakery.config.importMap` points at. */
 export async function serveVueChunk(
   path: string,
   req: Request,
 ): Promise<Response> {
-  if (path !== `${VUE_CHUNK_PREFIX}${VUE_VERSION}.js`) {
+  if (path !== vueChunkPath()) {
     return response.error('Not Found', 404)
   }
 
+  const variant = vueBuildVariant()
   const dir = fs.resolve(Bakery.cacheDir, 'vue-official', 'chunks')
-  const fileName = `${VUE_VERSION}.js`
+  // Derived from the URL, not restated: the cache name and the request path
+  // must agree on the variant, and one writer is how they keep agreeing.
+  const fileName = path.slice(VUE_CHUNK_PREFIX.length)
 
   let sourcePath = ''
   try {
-    sourcePath = Bun.resolveSync('vue/dist/vue.esm-bundler.js', Bakery.root)
+    sourcePath = Bun.resolveSync(VUE_ENTRIES[variant], Bakery.root)
   } catch {
     return response.error('Vue not found', 404)
   }

package/src/client.ts

@@ -0,0 +1,203 @@
+/**
+ * `defineLayout()` — browser-side navigation for catch-all pages.
+ *
+ * A catch-all page (`[...slug].vue`, `[...slug!].vue`) owns every URL under
+ * its directory: whatever the path, the server serves the same file. That
+ * invariant is what makes client-side navigation *safe* here — swapping
+ * content on a URL change can never disagree with what a hard reload would
+ * serve — and it is why this API is only available on catch-all pages: on any
+ * other page, two URLs mean two different files, and intercepting the
+ * navigation would show the wrong one. The server stamps the route's shape
+ * into `globalThis.__vue_route`; `defineLayout()` throws without it.
+ *
+ * The page becomes its subtree's layout: it reads `segments` and renders
+ * whichever of its own components the path means — no `<slot />`, no extra
+ * file. Clicks on same-origin links under the base are intercepted and become
+ * a `pushState` plus a reactive update; links that leave the base navigate
+ * normally; back/forward is handled the same way, falling back to a real
+ * navigation when history leaves the subtree.
+ *
+ * Imported from `@bakery-framework/plugin-vue/client`, which the browser
+ * resolves through the import map like any installed package. `vue` stays a
+ * bare import, so this shares the page's Vue instance.
+ */
+import { type Ref, ref } from 'vue'
+
+/** What the server stamps on the page — see `handleHtml` in `handler.ts`. */
+type StampedRoute = {
+  catchAll: boolean
+  /** URL prefix owned by the page: '' for a root catch-all, else '/admin'. */
+  base: string
+  /** The catch-all's param name (`slug` in `[...slug!]`). */
+  param: string | null
+  /**
+   * First path segments the catch-all's *siblings* claim — `faculty` when
+   * `faculty/[id].vue` sits beside the catch-all. Those URLs belong to more
+   * specific routes, so they get real navigations, not soft ones.
+   */
+  claimed?: string[]
+  /** True when a `[param]` sibling claims every single-segment path. */
+  claimedSingle?: boolean
+}
+
+export type LayoutNavigation = {
+  /** Path segments under the base — `[]` on the bare directory. */
+  readonly segments: Ref<string[]>
+  /** The URL prefix this page owns. */
+  readonly base: string
+  /** Navigate within the subtree; segments or a path, `/`-prefixed or not. */
+  navigate(to: string | string[]): void
+  /**
+   * Listen for navigations. Return `false` from a listener to cancel one —
+   * cancellation applies to clicks and `navigate()`; back/forward cannot be
+   * cancelled, only observed, because the history entry has already moved.
+   */
+  on(listener: LayoutListener): () => void
+}
+
+export type LayoutListener = (
+  next: string[],
+  prev: string[],
+  cause: 'click' | 'navigate' | 'history',
+) => boolean | undefined | void
+
+/** Is `path` the base itself or inside it? Prefix-safe: `/admin` ≠ `/admini`. */
+export function isUnderBase(base: string, path: string): boolean {
+  if (base === '') return path.startsWith('/')
+  return path === base || path.startsWith(`${base}/`)
+}
+
+/** The segments of `path` below `base` — `[]` for the base itself. */
+export function segmentsUnder(base: string, path: string): string[] {
+  const rest = base === '' ? path : path.slice(base.length)
+  return rest.split('/').filter(Boolean)
+}
+
+function pathFor(base: string, to: string | string[]): string {
+  if (Array.isArray(to)) {
+    const joined = to.filter(Boolean).join('/')
+    return joined ? `${base}/${joined}` : base || '/'
+  }
+  if (to.startsWith('/')) return to
+  return to ? `${base}/${to}` : base || '/'
+}
+
+export function defineLayout(): LayoutNavigation {
+  const route = (globalThis as any).__vue_route as StampedRoute | undefined
+
+  // The guard is the contract, not a formality — see the module comment.
+  if (!route?.catchAll) {
+    throw new Error(
+      'defineLayout() is only available on catch-all pages ' +
+        '([...slug].vue or [...slug!].vue): only there does every URL under ' +
+        'the page resolve back to the same file on a full load.',
+    )
+  }
+
+  const base = route.base
+  const claimed = new Set(route.claimed ?? [])
+  const claimedSingle = Boolean(route.claimedSingle)
+  const listeners = new Set<LayoutListener>()
+
+  // The catch-all owns only what nothing else claims. A sibling route under
+  // the base — `faculty/[id].vue` beside `[...slug].vue` — wins those URLs on
+  // the server, so a soft-nav there would render this page where a hard load
+  // renders that one.
+  function claimedElsewhere(next: string[]): boolean {
+    if (next.length === 1 && claimedSingle) return true
+    return next.length > 0 && claimed.has(next[0])
+  }
+
+  const initial =
+    typeof location !== 'undefined'
+      ? segmentsUnder(base, location.pathname)
+      : []
+  const segments = ref<string[]>(initial)
+
+  function fire(next: string[], cause: Parameters<LayoutListener>[2]): boolean {
+    const prev = segments.value
+    let allowed = true
+    for (const listener of listeners) {
+      if (listener(next, prev, cause) === false) allowed = false
+    }
+    return allowed
+  }
+
+  function go(to: string | string[], cause: 'click' | 'navigate'): void {
+    const path = pathFor(base, to)
+    if (!isUnderBase(base, path)) {
+      // Leaving the subtree is a real navigation — the next URL belongs to a
+      // different file, and pretending otherwise would render a lie.
+      if (typeof location !== 'undefined') location.href = path
+      return
+    }
+    const next = segmentsUnder(base, path)
+    if (claimedElsewhere(next)) {
+      // Under the base, but a more specific route's territory — real
+      // navigation, same reasoning as leaving the base.
+      if (typeof location !== 'undefined') location.href = path
+      return
+    }
+    if (!fire(next, cause)) return
+    if (typeof history !== 'undefined') history.pushState(null, '', path)
+    segments.value = next
+  }
+
+  if (typeof document !== 'undefined') {
+    document.addEventListener('click', event => {
+      if (event.defaultPrevented) return
+      if (event.button !== 0) return
+      if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey)
+        return
+
+      const anchor = (event.target as Element | null)?.closest?.('a[href]')
+      if (!anchor) return
+      if (anchor.getAttribute('target')) return
+      if (anchor.hasAttribute('download')) return
+
+      const href = anchor.getAttribute('href') ?? ''
+      // Same-document and external schemes stay the browser's business.
+      if (href.startsWith('#')) return
+      const url = new URL(href, location.href)
+      if (url.origin !== location.origin) return
+      if (!isUnderBase(base, url.pathname)) return
+      if (
+        url.pathname === location.pathname &&
+        url.search === location.search
+      ) {
+        event.preventDefault()
+        return
+      }
+
+      event.preventDefault()
+      go(url.pathname + url.search, 'click')
+    })
+
+    window.addEventListener('popstate', () => {
+      const path = location.pathname
+      if (!isUnderBase(base, path)) {
+        // History walked out of the subtree; the entry is already current, so
+        // the only honest move is loading what that URL actually serves.
+        location.reload()
+        return
+      }
+      const next = segmentsUnder(base, path)
+      if (claimedElsewhere(next)) {
+        location.reload()
+        return
+      }
+      fire(next, 'history') // observable, not cancellable — see `on`
+      segments.value = next
+    })
+  }
+
+  return {
+    segments,
+    base,
+    navigate: to => go(to, 'navigate'),
+    on(listener) {
+      listeners.add(listener)
+      return () => listeners.delete(listener)
+    },
+  }
+}

package/src/compile.ts

@@ -1,9 +1,6 @@
 import { compileText } from '@bakery-framework/core/compiler'
-import { Logger } from '@bakery-framework/core/logger'
 import type { SFCStyleCompileResults } from '@vue/compiler-sfc'
 
-const logger = new Logger('vue')
-
 import type {
   AssembleComponentOptions,
   CompileScriptOptions,
@@ -36,6 +33,21 @@ export function setVuePluginOptions(opts?: VuePluginOptions) {
   if (opts) vuePluginOptions = opts
 }
 
+/**
+ * `'runtime'` unless the app opted into the full build.
+ *
+ * `customElements` deliberately does *not* force `'full'`: for SFCs the
+ * custom-element decision is made server-side, in `compileTemplateBlock`'s
+ * `isCustomElement`, and arrives in the browser already baked into the render
+ * function. Verified against a live runtime-only page: a configured tag
+ * renders as a plain element, reactively, with no "Failed to resolve
+ * component" warning. Only browser-compiled `template:` strings need the full
+ * build, and only the app knows whether it has any.
+ */
+export function vueBuildVariant(): 'runtime' | 'full' {
+  return vuePluginOptions.build === 'full' ? 'full' : 'runtime'
+}
+
 export function resolveIsCustomElement(tag: string): boolean {
   const ce = vuePluginOptions?.customElements
   const userFn = vuePluginOptions?.compilerOptions?.isCustomElement
@@ -102,7 +114,7 @@ export async function compileScriptBlock(
 
 export async function compileTemplateBlock(
   options: CompileTemplateOptions,
-): Promise<string | null> {
+): Promise<{ code: string; errors: string[] } | null> {
   const { descriptor, id, filename, bindings } = options
   if (!descriptor.template) return null
   const { compileTemplate } = await loadCompiler()
@@ -122,7 +134,16 @@ export async function compileTemplateBlock(
           if (node.type !== 5) return
           const content = node.content
 
-          // Simple expression: `{{ value }}`
+          // Simple expression: `{{ value }}`.
+          //
+          // Comments inside an interpolation are not handled specially,
+          // deliberately: Vue itself cannot parse `{{ total // pesos }}` —
+          // measured against bare `compileTemplate`, which reports the same
+          // SyntaxError and emits the raw broken expression. Stripping the
+          // comment here just traded that for an unprefixed binding, because
+          // Vue's own expression pass had already failed. What Bakery adds
+          // instead is failing the compile loudly (see `compileVueFile`)
+          // rather than serving a module that cannot parse.
           if (content.type === 4) {
             const rawContent = content.content.trim()
             if (rawContent && !rawContent.startsWith('_ctx.$fmt(')) {
@@ -143,14 +164,19 @@ export async function compileTemplateBlock(
     },
   })
 
-  if (result.errors?.length) {
-    logger.log(`Template compile errors: ${result.errors.join(', ')}`, 'error')
-  }
+  // Reported to the caller, not merely logged: a template Vue cannot compile
+  // emits the raw unparseable expression into the render function, so the
+  // module *cannot run* — `{{ total // pesos }}` is the measured example, and
+  // Vue-alone behaves identically. Serving it anyway was a browser-side
+  // SyntaxError with a healthy-looking 200.
+  const errors = (result.errors ?? []).map(e =>
+    e instanceof Error ? e.message : String(e),
+  )
 
   let code = result.code
   code = code.replace(/^export\s+/m, '')
   code = await compileText(code)
-  return code
+  return { code, errors }
 }
 
 export async function compileStyleBlock(
@@ -167,7 +193,7 @@ export async function compileStyleBlock(
 }
 
 export function assembleComponent(options: AssembleComponentOptions): string {
-  const { scriptCode, renderCode, isRoot, scopeId } = options
+  const { scriptCode, renderCode, isRoot, scopeId, layoutRoute } = options
   const COMPONENT_VAR = '__sfc__'
   let output = scriptCode.replace(
     /\bexport\s+default\s*/,
@@ -186,10 +212,30 @@ export function assembleComponent(options: AssembleComponentOptions): string {
   output += `\nexport default ${COMPONENT_VAR};`
 
   if (isRoot) {
+    if (layoutRoute) {
+      // The page renders into the layout's default <slot />. The import is a
+      // plain `.vue` specifier so `rewriteVueImports` gives it the same
+      // `?__vue_script=module` treatment as any component import — the layout
+      // is just a component that happens to be discovered by convention.
+      output +=
+        `\nimport { createApp, h as __h } from 'vue';` +
+        `\nimport __layout from ${JSON.stringify(layoutRoute)};` +
+        `\nconst __app = createApp({ render: () => __h(__layout, null, { default: () => __h(${COMPONENT_VAR}) }) });`
+    } else {
+      output +=
+        `\nimport { createApp } from 'vue';` +
+        `\nconst __app = createApp(${COMPONENT_VAR});`
+    }
+
+    // Full build only. `app.config.compilerOptions` is read exclusively by the
+    // in-browser template compiler, which the runtime build does not carry —
+    // there, the assignment does nothing except make Vue log a warning about
+    // itself on every page, even for apps that configured nothing.
+    if (vueBuildVariant() === 'full') {
+      output += `\n__app.config.compilerOptions.isCustomElement = ${buildRuntimeCustomElementCheck()};`
+    }
+
     output +=
-      `\nimport { createApp } from 'vue';` +
-      `\nconst __app = createApp(${COMPONENT_VAR});` +
-      `\n__app.config.compilerOptions.isCustomElement = ${buildRuntimeCustomElementCheck()};` +
       `\n__app.config.globalProperties.$fmt = (v) => globalThis.$fmt ? globalThis.$fmt(v) : v;` +
       `\n__app.mount('#app');`
   }
@@ -216,7 +262,7 @@ function buildRuntimeCustomElementCheck(): string {
 export async function compileVueFile(
   options: CompileVueFileOptions,
 ): Promise<CompileVueFileResult> {
-  const { content, filename, id, isRootScript } = options
+  const { content, filename, id, isRootScript, layoutRoute } = options
   const { descriptor, errors: parseErrors } = await parseVue({
     content,
     filename,
@@ -226,7 +272,7 @@ export async function compileVueFile(
     descriptor,
     id,
   })
-  const renderCode = await compileTemplateBlock({
+  const template = await compileTemplateBlock({
     descriptor,
     id,
     filename,
@@ -234,14 +280,19 @@ export async function compileVueFile(
   })
   const code = assembleComponent({
     scriptCode,
-    renderCode,
+    renderCode: template?.code ?? null,
     isRoot: isRootScript,
     scopeId: hasScoped ? id : undefined,
+    layoutRoute,
   })
 
   const styles = await Promise.all(
     descriptor.styles.map(style => compileStyleBlock({ style, id })),
   )
 
-  return { code, styles, errors: parseErrors }
+  return {
+    code,
+    styles,
+    errors: [...parseErrors, ...(template?.errors ?? [])],
+  }
 }

package/src/handler.ts

@@ -1,3 +1,4 @@
+import { readdirSync } from 'node:fs'
 import { LRUCache } from '@bakery-framework/core/cache/lru'
 import { Bakery, hostKey } from '@bakery-framework/core/core/bakery'
 import type { Handler } from '@bakery-framework/core/handlers'
@@ -5,8 +6,10 @@ import {
   beginPageRoute,
   DynamicErrorHandler,
   DynamicHandler,
+  RX_CATCHALL,
+  RX_DYNAMIC,
+  RX_OPT_CATCHALL,
 } from '@bakery-framework/core/handlers'
-import { Logger } from '@bakery-framework/core/logger'
 import {
   fs,
   JsonResponseData,
@@ -15,17 +18,20 @@ import {
 } from '@bakery-framework/core/utils'
 import { ETag, injectIfHtml } from '@bakery-framework/core/utils/http'
 
-const logger = new Logger('vue')
-
 import {
   resolveActionTarget,
   validateActionRequest,
   validateActionTarget,
 } from './actions'
 import { serveVueChunk, VUE_CHUNK_PREFIX } from './chunks'
-import { compileStyleBlock, compileVueFile, parseVue } from './compile'
+import {
+  compileStyleBlock,
+  compileVueFile,
+  parseVue,
+  vueBuildVariant,
+} from './compile'
 import { VUE_HTML_SHELL } from './shell'
-import type { ParsedCacheEntry } from './types'
+import type { ParsedCacheEntry, VueMeta } from './types'
 import {
   cacheDir,
   collectExportedFunctionNames,
@@ -34,6 +40,7 @@ import {
   extractServerScripts,
   getServerResponse,
   parsedCache,
+  parseSkeleton,
   parseVueMeta,
   RX_EXPORT_BRACE,
   RX_EXPORT_HANGING,
@@ -75,6 +82,96 @@ function buildActionStub(fn: string, relPath: string) {
   )
 }
 
+/**
+ * Route path of the nearest `layout.vue`, walking from the page **file** up
+ * to the serve root — the file, not the URL, so a catch-all page
+ * (`admin/[...slug!].vue`) is wrapped by `admin/layout.vue` no matter how
+ * deep the request path goes. Null when nothing is found, when the page
+ * opted out with `<meta no-layout />`, or when the page *is* a layout —
+ * layouts do not nest in v1, deliberately: nesting needs an ordering story
+ * (which slot, whose styles win) that should be designed, not implied.
+ */
+function findLayoutRoute(filePath: string, meta: VueMeta): string | null {
+  if (!meta.layout) return null
+
+  const root = fs.resolve(Bakery.serveRoot)
+  const file = fs.resolve(filePath)
+  if (!file.startsWith(`${root}/`)) return null
+  if (file.endsWith('/layout.vue')) return null
+
+  let dir = file.slice(0, file.lastIndexOf('/'))
+  while (dir === root || dir.startsWith(`${root}/`)) {
+    const candidate = `${dir}/layout.vue`
+    if (fs.isFileSync(candidate)) {
+      return `/${fs.relative(root, candidate)}`
+    }
+    if (dir === root) break
+    dir = dir.slice(0, dir.lastIndexOf('/'))
+  }
+
+  return null
+}
+
+/**
+ * What the catch-all's siblings claim, for the `defineLayout()` stamp.
+ *
+ * A catch-all owns only *what nothing else claims*: with
+ * `admin/[...slug].vue` beside `admin/faculty/[id].vue`, the URL
+ * `/admin/faculty/7` is under the base but belongs to `[id].vue` — so the
+ * client-side router must yield it to a real navigation, or a soft-nav shows
+ * the catch-all's rendering where a hard reload shows a different page.
+ *
+ * First-level granularity is exactly the server's precedence boundary: every
+ * more-specific route — an exact sibling file, a child index, a deeper
+ * catch-all — lives inside some sibling entry, so excluding the entry
+ * excludes the whole claim. A `[param]` sibling claims *every* single-segment
+ * path, which is what `claimedSingle` carries. `layout.vue` claims nothing (it
+ * is not routable), and the catch-all file itself is the page being served.
+ *
+ * Computed per page request, so files added or removed in dev are seen on the
+ * next load without cache ceremony.
+ */
+export function claimedBeside(catchAllFile: string): {
+  claimed: string[]
+  claimedSingle: boolean
+} {
+  const claimed = new Set<string>()
+  let claimedSingle = false
+
+  const dir = fs.resolve(catchAllFile).replace(/\/[^/]*$/, '')
+  const self = fs.resolve(catchAllFile).slice(dir.length + 1)
+
+  let entries: import('node:fs').Dirent[]
+  try {
+    entries = readdirSync(dir, { withFileTypes: true })
+  } catch {
+    // Unreadable directory: no visible siblings means nothing extra claimed,
+    // and a hard load still routes correctly — the stamp is an optimisation
+    // of honesty, not the source of it.
+    return { claimed: [], claimedSingle: false }
+  }
+
+  for (const entry of entries) {
+    const name = entry.name
+    if (name === self || name === 'layout.vue') continue
+    if (name.startsWith('.')) continue
+
+    if (RX_CATCHALL.test(name) || RX_OPT_CATCHALL.test(name)) continue
+    if (RX_DYNAMIC.test(name)) {
+      claimedSingle = true
+      continue
+    }
+
+    claimed.add(name)
+    // `reports.vue` also claims `/base/reports` — the extensionless spelling
+    // is the one links actually use.
+    const stem = name.replace(/\.[^.]+$/, '')
+    if (stem && stem !== name) claimed.add(stem)
+  }
+
+  return { claimed: [...claimed], claimedSingle }
+}
+
 export class VueHandler extends DynamicHandler {
   static get config() {
     return {
@@ -108,8 +205,9 @@ export class VueHandler extends DynamicHandler {
 
     const rawText = await diskFile.text()
     const { meta, clean: metaCleaned } = parseVueMeta(rawText)
+    const { skeleton, clean: withoutSkeleton } = parseSkeleton(metaCleaned)
     const { script: serverScript, clean: withoutServer } =
-      extractServerScripts(metaCleaned)
+      extractServerScripts(withoutSkeleton)
     let cleanContent = withoutServer
 
     if (serverScript.trim()) {
@@ -151,6 +249,20 @@ export class VueHandler extends DynamicHandler {
         cleanContent = `<script${langAttr}>\n${scriptInjections.join(
           '\n',
         )}\n</script>\n${cleanContent}`
+
+        // A component with a server block but no `<script setup>` used to
+        // render blank: the injected block above has no `export default`, so
+        // `assembleComponent` had nothing to rewrite into `const __sfc__ =`
+        // and the module died with `ReferenceError: __sfc__ is not defined`.
+        // The documented workaround was a setup block — so inject one. The
+        // comment inside is load-bearing: the SFC parser *discards* a block
+        // whose content is only whitespace, which is also why the workaround
+        // had to be a non-empty block. It also makes the server exports
+        // template-visible — compileScript only records plain-script bindings
+        // when a setup block exists.
+        if (!/<script\s[^>]*\bsetup\b|<script\s+setup/i.test(cleanContent)) {
+          cleanContent += `\n<script setup${langAttr}>\n// injected: carries the server-data bindings above\n</script>\n`
+        }
       }
     }
 
@@ -182,6 +294,8 @@ export class VueHandler extends DynamicHandler {
       styles: descriptor.styles,
       hasCss: descriptor.styles.length > 0,
       meta,
+      skeleton,
+      layoutRoute: findLayoutRoute(filePath, meta),
     }
     parsedCache.set(id, parsed)
     return parsed
@@ -200,10 +314,18 @@ export class VueHandler extends DynamicHandler {
       filename: routePath,
       id: scopeId || id,
       isRootScript,
+      layoutRoute: isRootScript ? parsed.layoutRoute : null,
     })
 
     if (compiled.errors.length) {
-      logger.log(`Compile errors: ${compiled.errors.join(', ')}`, 'error')
+      // Thrown, not logged-and-served: a template Vue could not compile has
+      // the raw unparseable expression in its render function, so serving it
+      // is a browser-side SyntaxError behind a 200 and an empty page — the
+      // report that surfaced this described exactly that. The throw lands in
+      // the error registry as a 500 that names the file and the error.
+      throw new Error(
+        `Vue compile failed (${routePath}): ${compiled.errors.join('; ')}`,
+      )
     }
 
     let code = compiled.code
@@ -246,7 +368,21 @@ export class VueHandler extends DynamicHandler {
     // data, so the built file can live on disk.
     if (!hasServerScript || isRootScript) {
       const dir = fs.resolve(cacheDir, 'js')
-      const fileName = `${id}${isRootScript ? '.root' : ''}.js`
+      // Root scripts carry the build variant in their name for the same reason
+      // the chunk does (`vueChunkPath`): the cache is keyed on the *source's*
+      // mtime, and flipping `build` in server.config.ts touches no source file
+      // — measured serving a root compiled under 'runtime' after the flip to
+      // 'full', missing the isCustomElement bridge the full build exists for.
+      // Only roots: the variant changes nothing in a subcomponent's output.
+      // The layout joins the name for the same reason the variant does: the
+      // cache is keyed on the page's mtime, and creating, deleting or moving
+      // a layout.vue touches no page file.
+      const layoutTag = parsed.layoutRoute
+        ? `.${toHash(parsed.layoutRoute)}`
+        : ''
+      const fileName = isRootScript
+        ? `${id}.root.${vueBuildVariant()}${layoutTag}.js`
+        : `${id}.js`
       const replacement =
         isRootScript && hasServerScript
           ? '(globalThis.__vue_server || {})'
@@ -295,12 +431,36 @@ export class VueHandler extends DynamicHandler {
     })
   }
 
+  /**
+   * The layout's stylesheet link, or ''. Emitted ahead of the page's own link
+   * so a page can override its layout the way source order implies.
+   */
+  private static async layoutCssLink(parsed: ParsedCacheEntry) {
+    if (!parsed.layoutRoute) return ''
+
+    const layoutFile = fs.resolve(Bakery.serveRoot, `.${parsed.layoutRoute}`)
+    const layoutBun = Bun.file(layoutFile)
+    if (!fs.exists(layoutBun)) return ''
+
+    const layoutId = toHash(hostKey(parsed.layoutRoute.slice(1)))
+    const layoutParsed = await VueHandler.parseVueFile(
+      layoutId,
+      layoutBun,
+      layoutFile,
+      layoutBun.lastModified,
+    )
+    if (!layoutParsed.hasCss) return ''
+
+    return `<link rel="stylesheet" id="__vu_css_${layoutId}" href="${parsed.layoutRoute}?__vue_css=true">\n`
+  }
+
   static async handleHtml(
     id: string,
     params: any,
     routePath: string,
     serverParams: any,
     parsed: ParsedCacheEntry,
+    route?: { catchAll: boolean; base: string; param: string | null },
   ) {
     const { hasCss, serverScript } = parsed
     const hasServerData =
@@ -317,11 +477,30 @@ export class VueHandler extends DynamicHandler {
       ? `<script>globalThis.__vue_server = ${escapeScriptJson(payload)};</script>`
       : ''
 
+    // The route's shape, for `defineLayout()` (`client.ts`): the guard that
+    // restricts it to catch-all pages reads `catchAll` from here, so the
+    // stamp is the enforcement, not a convenience. Stamped on every page —
+    // a non-catch-all page carries `catchAll: false`, which is what makes
+    // the client-side error message possible instead of a bare undefined.
+    const routeDecl = route
+      ? `<script>globalThis.__vue_route = ${escapeScriptJson(route)};</script>`
+      : ''
+
     let hydrated = VUE_HTML_SHELL.replace(
       '/*__SERVER_VARIABLES__*/',
-      () => serverDecl,
+      () => serverDecl + routeDecl,
     )
 
+    // Static markup, injected verbatim — see parseSkeleton for why it is
+    // never rendered. mount() replaces the container children, so it
+    // disappears the moment the real component is up.
+    if (parsed.skeleton) {
+      hydrated = hydrated.replace(
+        '<div id="app"></div>',
+        () => `<div id="app">${parsed.skeleton}</div>`,
+      )
+    }
+
     if (parsed.meta.title) {
       const title = escapeHtml(parsed.meta.title)
       hydrated = hydrated.replace(
@@ -331,6 +510,7 @@ export class VueHandler extends DynamicHandler {
     }
 
     const prio =
+      (await VueHandler.layoutCssLink(parsed)) +
       (hasCss
         ? `<link rel="stylesheet" id="__vu_css_${id}" href="${routePath}?__vue_css=true">\n`
         : '') +
@@ -432,6 +612,13 @@ async function sharedHandler(
     return response.error('Not Found', 404)
   }
 
+  // A layout is scaffolding, not a destination: /admin/layout must not render
+  // as a page. Script and css requests pass — they are how the root script of
+  // every page under it imports the thing.
+  if (routePath.endsWith('/layout.vue') && !isScript && !isCss) {
+    return response.error('Not Found', 404)
+  }
+
   // page-only: block module imports (allow root scripts, page, and css)
   if (parsed.meta.pageOnly && isScript && vueScriptParam === 'module') {
     return response.error('Not Found', 404)
@@ -534,5 +721,20 @@ async function sharedHandler(
     return VueHandler.handleScript(id, routePath, false, parsed, serverValues)
   }
 
-  return VueHandler.handleHtml(id, finalParams, routePath, serverParams, parsed)
+  // `base` is the URL prefix the page owns: the file's directory. For
+  // `wiki/[...page!].vue` that is `/wiki`; for a root-level catch-all it is
+  // the empty string, which `defineLayout` treats as "everything".
+  return VueHandler.handleHtml(
+    id,
+    finalParams,
+    routePath,
+    serverParams,
+    parsed,
+    {
+      catchAll: Boolean(info.catchAll),
+      base: routePath.slice(0, routePath.lastIndexOf('/')),
+      param: info.params.length ? info.params[info.params.length - 1] : null,
+      ...claimedBeside(diskFile.name ?? ''),
+    },
+  )
 }

package/src/setup.ts

@@ -1,7 +1,8 @@
 import { Bakery } from '@bakery-framework/core/core/bakery'
 import { Logger } from '@bakery-framework/core/logger'
+import { vueChunkPath } from './chunks'
 import { VueErrorHandler, VueHandler } from './handler'
-import { initVueVersion, VUE_VERSION } from './utils'
+import { initVueVersion } from './utils'
 
 const logger = new Logger('vue')
 
@@ -19,5 +20,8 @@ export function setupVue() {
   initVueVersion()
   Bakery.handlers.fetch.set(VueHandler, 58)
   Bakery.handlers.error.set(VueErrorHandler, 18)
-  Bakery.config.importMap.vue = `/_vue/${VUE_VERSION}.js`
+  // `vueChunkPath` is the single writer of this URL — it carries the build
+  // variant (`<version>.runtime.js` / `<version>.full.js`), and the serving
+  // check in `chunks.ts` reads the same function.
+  Bakery.config.importMap.vue = vueChunkPath()
 }

package/src/types.d.ts

@@ -41,6 +41,8 @@ export interface AssembleComponentOptions {
   renderCode: string | null
   isRoot: boolean
   scopeId?: string
+  /** Route path of the layout to wrap a root component in, if any. */
+  layoutRoute?: string | null
 }
 
 export interface CompileVueFileOptions {
@@ -48,6 +50,8 @@ export interface CompileVueFileOptions {
   filename: string
   id: string
   isRootScript: boolean
+  /** Route path of the nearest layout.vue; only read for root scripts. */
+  layoutRoute?: string | null
 }
 
 export interface CompileVueFileResult {
@@ -60,6 +64,8 @@ export interface VueMeta {
   moduleOnly: boolean
   pageOnly: boolean
   title: string | null
+  /** False when the page opted out with `<meta no-layout />`. */
+  layout: boolean
 }
 
 export interface ParsedCacheEntry {
@@ -71,6 +77,17 @@ export interface ParsedCacheEntry {
   styles: SFCStyleBlock[]
   hasCss: boolean
   meta: VueMeta
+  /**
+   * Inner markup of a `<template skeleton>` block, or null. Static by
+   * construction — extracted before compilation, never rendered on the
+   * server — so nothing request- or user-derived can reach it.
+   */
+  skeleton: string | null
+  /**
+   * Route path of the nearest `layout.vue` (e.g. `/admin/layout.vue`), or
+   * null when there is none or the page opted out.
+   */
+  layoutRoute: string | null
 }
 
 export interface ServerResponseOptions {
@@ -89,4 +106,16 @@ export type CustomElementsOption = string[] | ((tag: string) => boolean)
 export interface VuePluginOptions {
   customElements?: CustomElementsOption
   compilerOptions?: Record<string, any>
+  /**
+   * Which Vue build the plugin serves at `/_vue/<version>.<build>.js`.
+   *
+   * `'runtime'` (the default) is ~170KB smaller and is all a Bakery app
+   * normally needs: SFC templates are compiled to render functions on the
+   * server, and `customElements` is applied there too, so the browser never
+   * compiles a template. Opt into `'full'` only for components that hand Vue a
+   * raw `template:` string at runtime — those are compiled in the browser and
+   * fail on the runtime build with Vue's "runtime compilation is not
+   * supported" error.
+   */
+  build?: 'runtime' | 'full'
 }

package/src/utils.ts

@@ -570,8 +570,44 @@ export function rewriteVueImports(code: string): string {
 export const RX_VUE_META = /^<meta(?![\w-])((?:"[^"]*"|'[^']*'|[^>])*?)\/>/i
 const RX_META_SKIPPABLE = /^\s+|^<!--[\s\S]*?-->/
 
+/**
+ * Extract a `<template skeleton>` block: its inner markup goes into the HTML
+ * shell's `#app` so the user sees something before the bundle hydrates, and
+ * the block is removed from the SFC — the compiler allows only one template.
+ *
+ * **Static by design, and the design is a security decision.** The markup is
+ * injected verbatim: never compiled, never rendered on the server, so
+ * interpolations do not evaluate and nothing request- or session-derived can
+ * end up in it. A server-rendered skeleton cached across requests would serve
+ * one user's data to another. Scoped styles do not reach it either — the
+ * scope attributes are stamped by the compiler this block never meets.
+ *
+ * One block per file; nested `<template>` elements inside it are not
+ * supported (the lazy match ends at the first closing tag).
+ */
+export function parseSkeleton(raw: string): {
+  skeleton: string | null
+  clean: string
+} {
+  const match = raw.match(
+    /<template\s+skeleton(?:\s(?:"[^"]*"|'[^']*'|[^>])*)?>([\s\S]*?)<\/template>/i,
+  )
+  if (!match) return { skeleton: null, clean: raw }
+
+  const skeleton = match[1].trim()
+  return {
+    skeleton: skeleton || null,
+    clean: raw.replace(match[0], ''),
+  }
+}
+
 export function parseVueMeta(raw: string): { meta: VueMeta; clean: string } {
-  const meta: VueMeta = { moduleOnly: false, pageOnly: false, title: null }
+  const meta: VueMeta = {
+    moduleOnly: false,
+    pageOnly: false,
+    title: null,
+    layout: true,
+  }
 
   // Directives live in the file prologue only. Walking forward from the start
   // (rather than scanning the whole file) keeps a `<meta />` inside a template
@@ -595,6 +631,7 @@ export function parseVueMeta(raw: string): { meta: VueMeta; clean: string } {
     const attrs = tag[1]
     if (/\bmodule-only\b/i.test(attrs)) meta.moduleOnly = true
     if (/\bpage-only\b/i.test(attrs)) meta.pageOnly = true
+    if (/\bno-layout\b/i.test(attrs)) meta.layout = false
 
     const titleMatch = attrs.match(
       /\btitle\s*=\s*"([^"]*)"|\btitle\s*=\s*'([^']*)'/i,