@jasonshimmy/vite-plugin-cer-app 0.23.0 → 0.23.2

package/src/plugin/build-ssg.ts

@@ -1,6 +1,12 @@
 import { writeFile, mkdir, readFile } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
 import { join } from 'pathe'
+import {
+  injectFaviconLink,
+  injectCanonicalLink,
+  addNoopenerToExternalLinks,
+  generateRobotsTxt,
+} from './html-post-process.js'
 import { createServer, type UserConfig } from 'vite'
 import type { ResolvedCerConfig } from './dev-server.js'
 import type { ContentItem } from '../types/content.js'
@@ -255,13 +261,59 @@ export async function writeRenderedPath(
   await writeFile(outputPath, html, 'utf-8')
 }
 
+/**
+ * Detects which favicon href to use from the project's public directory.
+ * Prefers .svg > .ico > .png. Returns null when none is found.
+ */
+function detectFaviconHref(root: string): string | null {
+  const candidates = ['/favicon.svg', '/favicon.ico', '/favicon.png']
+  for (const href of candidates) {
+    if (existsSync(join(root, 'public', href.slice(1)))) return href
+  }
+  return null
+}
+
+/**
+ * Applies all HTML post-processing transforms to a rendered page.
+ *
+ * - Injects `<link rel="icon">` when a favicon exists in public/ and none
+ *   is already declared in the HTML.
+ * - Injects `<link rel="canonical">` when `config.siteUrl` is set and none
+ *   is already declared.
+ * - Adds `rel="noopener noreferrer"` to every `<a target="_blank">` link
+ *   that is missing it.
+ */
+function postProcessHtml(
+  html: string,
+  path: string,
+  config: ResolvedCerConfig,
+  faviconHref: string | null,
+): string {
+  let out = html
+
+  if (faviconHref) {
+    out = injectFaviconLink(out, faviconHref)
+  }
+
+  if (config.siteUrl) {
+    const canonicalUrl = config.siteUrl + (path === '/' ? '' : path)
+    out = injectCanonicalLink(out, canonicalUrl)
+  }
+
+  out = addNoopenerToExternalLinks(out)
+
+  return out
+}
+
 /**
  * Full SSG build pipeline:
  * 1. Run the SSR dual-build (client + server bundles)
  * 2. Enumerate all paths to generate
  * 3. Render each path using the server bundle
- * 4. Write HTML files to dist/
- * 5. Write ssg-manifest.json
+ * 4. Post-process HTML (favicon, canonical, noopener)
+ * 5. Write HTML files to dist/
+ * 6. Write robots.txt (when not already present in public/)
+ * 7. Write ssg-manifest.json
  */
 export async function buildSSG(
   config: ResolvedCerConfig,
@@ -281,7 +333,10 @@ export async function buildSSG(
   const paths = await collectSsgPaths(config, viteUserConfig)
   console.log(`[cer-app] Found ${paths.length} path(s) to generate:`, paths)
 
-  // Step 3+4: Render and write paths with bounded concurrency.
+  // Detect favicon once for use in every page's post-processing pass.
+  const faviconHref = detectFaviconHref(config.root)
+
+  // Step 3+4+5: Render, post-process, and write paths with bounded concurrency.
   // The server bundle uses per-request router instances (initRouter returns the
   // router; the factory passes it to createStreamingSSRHandler as { vnode, router })
   // so concurrent renders are safe — each request carries its own router with its
@@ -299,7 +354,8 @@ export async function buildSSG(
     const results = await Promise.allSettled(
       chunk.map(async (path) => {
         console.log(`[cer-app] Generating: ${path}`)
-        const html = await renderPath(path, serverBundlePath)
+        const raw = await renderPath(path, serverBundlePath)
+        const html = postProcessHtml(raw, path, config, faviconHref)
         await writeRenderedPath(path, html, distDir)
         return path
       }),
@@ -316,7 +372,18 @@ export async function buildSSG(
     }
   }
 
-  // Step 5: Write SSG manifest
+  // Step 6: Write robots.txt unless the project supplies its own via public/robots.txt,
+  // which Vite copies to dist/ as-is. Always overwrite any previously generated file so
+  // that siteUrl changes (e.g. adding the Sitemap directive) take effect on rebuild.
+  const publicRobots = join(config.root, 'public', 'robots.txt')
+  if (!existsSync(publicRobots)) {
+    const distRobots = join(distDir, 'robots.txt')
+    await mkdir(distDir, { recursive: true })
+    await writeFile(distRobots, generateRobotsTxt(config.siteUrl), 'utf-8')
+    console.log('[cer-app] Generated robots.txt')
+  }
+
+  // Step 7: Write SSG manifest
   const manifest: SsgManifest = {
     generatedAt: new Date().toISOString(),
     paths: generatedPaths,

package/src/plugin/dev-server.ts

@@ -9,6 +9,8 @@ export interface ResolvedCerConfig {
   mode: 'spa' | 'ssr' | 'ssg'
   srcDir: string
   root: string
+  /** Canonical site origin (no trailing slash). Null when not configured. */
+  siteUrl: string | null
   contentDir: string
   pagesDir: string
   layoutsDir: string

package/src/plugin/generated-dir.ts

@@ -107,7 +107,7 @@ export function writeGeneratedDir(config: ResolvedCerConfig): void {
   // Always write the generated app.ts — this is the framework entry point and
   // is never user-owned. Regenerating it on every dev/build ensures consumers
   // automatically get the latest bootstrap code on plugin update (Nuxt-style).
-  writeFileSync(join(dir, 'app.ts'), generateAppEntryTemplate(config.jitCss.customColors), 'utf-8')
+  writeFileSync(join(dir, 'app.ts'), generateAppEntryTemplate(), 'utf-8')
 
   // Always write the SSR entry — used by the dev server's ssrLoadModule call.
   // The production build injects this as a virtual module, but the dev server

package/src/plugin/html-post-process.ts

@@ -0,0 +1,96 @@
+/**
+ * HTML post-processing transforms applied to every SSG-rendered page.
+ *
+ * Each function is a pure string → string transform. They are composed in
+ * build-ssg.ts after the server bundle renders each path.
+ */
+
+// ---------------------------------------------------------------------------
+// Favicon injection
+// ---------------------------------------------------------------------------
+
+/**
+ * Injects `<link rel="icon" href="${faviconHref}">` before `</head>` when no
+ * `<link rel="icon">` or `<link rel="shortcut icon">` is already present.
+ */
+export function injectFaviconLink(html: string, faviconHref: string): string {
+  if (/<link[^>]+rel=["'](?:shortcut )?icon["']/i.test(html)) return html
+  const tag = `<link rel="icon" href="${faviconHref}">`
+  return insertBeforeHead(html, tag)
+}
+
+// ---------------------------------------------------------------------------
+// Canonical link injection
+// ---------------------------------------------------------------------------
+
+/**
+ * Injects `<link rel="canonical" href="${url}">` before `</head>` when no
+ * `<link rel="canonical">` is already present.
+ */
+export function injectCanonicalLink(html: string, url: string): string {
+  if (/<link[^>]+rel=["']canonical["']/i.test(html)) return html
+  const tag = `<link rel="canonical" href="${escapeAttr(url)}">`
+  return insertBeforeHead(html, tag)
+}
+
+// ---------------------------------------------------------------------------
+// noopener / noreferrer on external target="_blank" links
+// ---------------------------------------------------------------------------
+
+/**
+ * Adds `rel="noopener noreferrer"` to every `<a target="_blank">` element
+ * that does not already have a `rel` attribute containing both values.
+ *
+ * Only touches anchor tags — not `<form>` or other elements with `target`.
+ */
+export function addNoopenerToExternalLinks(html: string): string {
+  return html.replace(
+    /(<a\b[^>]*\btarget\s*=\s*["']_blank["'][^>]*)(>)/gi,
+    (match, attrs: string, close: string) => {
+      const relMatch = attrs.match(/\brel\s*=\s*["']([^"']*)["']/i)
+      if (relMatch) {
+        const existing = relMatch[1]
+        const hasNoopener = /\bnoopener\b/i.test(existing)
+        const hasNoreferrer = /\bnoreferrer\b/i.test(existing)
+        if (hasNoopener && hasNoreferrer) return match
+        const parts = existing.trim().split(/\s+/).filter(Boolean)
+        if (!hasNoopener) parts.push('noopener')
+        if (!hasNoreferrer) parts.push('noreferrer')
+        return attrs.replace(relMatch[0], `rel="${parts.join(' ')}"`) + close
+      }
+      return `${attrs} rel="noopener noreferrer"${close}`
+    },
+  )
+}
+
+// ---------------------------------------------------------------------------
+// robots.txt generation
+// ---------------------------------------------------------------------------
+
+/**
+ * Generates the content of a `robots.txt` file.
+ * When `siteUrl` is provided a `Sitemap:` directive is included.
+ */
+export function generateRobotsTxt(siteUrl: string | null): string {
+  const lines = ['User-agent: *', 'Allow: /']
+  if (siteUrl) {
+    lines.push('', `Sitemap: ${siteUrl}/sitemap.xml`)
+  }
+  return lines.join('\n') + '\n'
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function insertBeforeHead(html: string, tag: string): string {
+  const idx = html.indexOf('</head>')
+  if (idx !== -1) {
+    return html.slice(0, idx) + tag + '\n' + html.slice(idx)
+  }
+  return tag + '\n' + html
+}
+
+function escapeAttr(value: string): string {
+  return value.replace(/&/g, '&amp;').replace(/"/g, '&quot;')
+}

package/src/plugin/index.ts

@@ -36,6 +36,7 @@ const VIRTUAL_IDS = {
   error: 'virtual:cer-error',
   contentComponents: 'virtual:cer-content-components',
   i18n: 'virtual:cer-i18n',
+  jitInit: 'virtual:cer-jit-init',
 } as const
 
 // Resolved virtual module IDs (prefixed with \0)
@@ -62,6 +63,7 @@ export function resolveConfig(userConfig: CerAppConfig, root: string = process.c
     mode,
     srcDir,
     root,
+    siteUrl: userConfig.siteUrl ? userConfig.siteUrl.replace(/\/$/, '') : null,
     contentDir: resolve(root, userConfig.content?.dir ?? 'content'),
     pagesDir: join(srcDir, 'pages'),
     layoutsDir: join(srcDir, 'layouts'),
@@ -97,7 +99,10 @@ export function resolveConfig(userConfig: CerAppConfig, root: string = process.c
       runtime: userConfig.autoImports?.runtime ?? true,
     },
     runtimeConfig: {
-      public: userConfig.runtimeConfig?.public ?? {},
+      public: {
+        ...(userConfig.siteUrl ? { siteUrl: userConfig.siteUrl.replace(/\/$/, '') } : {}),
+        ...userConfig.runtimeConfig?.public,
+      },
       private: userConfig.runtimeConfig?.private ?? {},
     },
     auth: userConfig.auth ?? null,
@@ -144,6 +149,8 @@ async function generateVirtualModule(
       return generateContentComponentsCode(config.componentsDir, config.contentDir)
     case RESOLVED_IDS.i18n:
       return generateI18nModule(config.i18n)
+    case RESOLVED_IDS.jitInit:
+      return generateJitInitModule(config.jitCss)
     default:
       return null
   }
@@ -167,6 +174,30 @@ function generateI18nModule(
   )
 }
 
+/**
+ * Generates the virtual:cer-jit-init module that calls enableJITCSS() with the
+ * project's jitCss options. Imported as the first side-effect import in app.ts
+ * so JIT CSS is active before virtual:cer-layouts and virtual:cer-plugins run
+ * their static imports — which upgrade custom elements synchronously via
+ * customElements.define(). Without this, applyStyle() runs with _jitCSSEnabled=false
+ * and produces unstyled renders that replace the DSD pre-rendered content.
+ */
+export function generateJitInitModule(jitCss: ResolvedCerConfig['jitCss']): string {
+  const args: string[] = []
+  if (jitCss.extendedColors) {
+    args.push(`extendedColors: ${JSON.stringify(jitCss.extendedColors)}`)
+  }
+  if (jitCss.customColors && Object.keys(jitCss.customColors).length > 0) {
+    args.push(`customColors: ${JSON.stringify(jitCss.customColors)}`)
+  }
+  const callArgs = args.length > 0 ? `{ ${args.join(', ')} }` : ''
+  return (
+    `// AUTO-GENERATED by @jasonshimmy/vite-plugin-cer-app\n` +
+    `import { enableJITCSS } from '@jasonshimmy/custom-elements-runtime/jit-css'\n` +
+    `enableJITCSS(${callArgs})\n`
+  )
+}
+
 /**
  * Generates a virtual module that exports the resolved app config.
  * When `ssr` is true, also exports `_runtimePrivateDefaults` (server-only).
@@ -313,7 +344,7 @@ export function cerApp(userConfig: CerAppConfig = {}): Plugin[] {
     },
 
     async load(id: string, options?: { ssr?: boolean }) {
-      if (id === RESOLVED_APP_ENTRY) return generateAppEntryTemplate(config.jitCss.customColors)
+      if (id === RESOLVED_APP_ENTRY) return generateAppEntryTemplate()
 
       const allResolved = Object.values(RESOLVED_IDS) as string[]
       if (!allResolved.includes(id)) return null

package/src/runtime/app-template.ts

@@ -4,23 +4,18 @@
  * Always written to `.cer/app.ts` on every dev/build so consumers
  * automatically receive the latest bootstrap code on plugin update.
  * This file is gitignored and should never be edited directly.
- *
- * @param customColors - Project-specific color families to register in the JIT
- *   CSS engine at runtime. Serialized as a JSON literal in the generated source.
  */
-export function generateAppEntryTemplate(
-  customColors?: Record<string, Record<string, string>>,
-): string {
-  const enableJITCSSCall =
-    customColors && Object.keys(customColors).length > 0
-      ? `enableJITCSS({ customColors: ${JSON.stringify(customColors)} })`
-      : `enableJITCSS()`
-
+export function generateAppEntryTemplate(): string {
   return `// AUTO-GENERATED by @jasonshimmy/vite-plugin-cer-app — do not edit.
 // Regenerated automatically on every dev server start and build.
 
 import '@jasonshimmy/custom-elements-runtime/css'
 import 'virtual:cer-jit-css'
+// virtual:cer-jit-init must run before virtual:cer-layouts and virtual:cer-plugins
+// so JIT CSS is enabled before those modules upgrade custom elements via
+// customElements.define(). Static imports execute depth-first in module order,
+// so placing this import here guarantees enableJITCSS() fires first.
+import 'virtual:cer-jit-init'
 import 'virtual:cer-content-components'
 import routes from 'virtual:cer-routes'
 import layouts from 'virtual:cer-layouts'
@@ -38,7 +33,6 @@ import {
   registerBuiltinComponents,
 } from '@jasonshimmy/custom-elements-runtime'
 import { initRouter } from '@jasonshimmy/custom-elements-runtime/router'
-import { enableJITCSS } from '@jasonshimmy/custom-elements-runtime/jit-css'
 import { initRuntimeConfig } from '@jasonshimmy/vite-plugin-cer-app/composables'
 
 const _cerProcess = (globalThis).process
@@ -57,7 +51,6 @@ const _cerRuntimeDev =
 
 registerBuiltinComponents()
 setDevMode(_cerRuntimeDev)
-${enableJITCSSCall}
 initRuntimeConfig(runtimeConfig)
 
 const router = initRouter({ routes })
@@ -217,9 +210,13 @@ component('cer-layout-view', () => {
     // store.subscribe() synchronously pushes the current route once on
     // subscription. That initial callback is not a real navigation and must not
     // tear down the SSR slot before _doHydrate has pre-loaded the page.
-    // Subsequent callbacks are real navigations (including the initial _replace
-    // in _doHydrate), so if they arrive during the hydration gap we drop the
-    // slot immediately and let the live render take over.
+    // Subsequent callbacks may be real navigations, but initRouter() also fires
+    // a queueMicrotask(() => navigate(...)) to run guards on the entry URL.
+    // That startup microtask resolves during the await route.load() gap —
+    // before _currentPageTag is set — so we must not drop the slot until the
+    // page module has actually been loaded (_currentPageTag !== null).
+    // The explicit _cerHydrating.value = false in _doHydrate() fires after
+    // _loadPageForPath completes and is the authoritative hydration trigger.
     unsub = router.subscribe((s) => {
       const _isInitialSubscribePush = !_sawInitialRouteState
       _sawInitialRouteState = true
@@ -227,7 +224,7 @@ component('cer-layout-view', () => {
         current.value = s
         return
       }
-      if (_cerHydrating.value) _cerHydrating.value = false
+      if (_cerHydrating.value && _currentPageTag !== null) _cerHydrating.value = false
       current.value = s
     })
   })

package/src/runtime/composables/use-content-search.ts

@@ -1,7 +1,9 @@
 import {
   createComposable,
+  getCurrentComponentContext,
   ref,
   useOnConnected,
+  useOnDisconnected,
   watch,
 } from '@jasonshimmy/custom-elements-runtime'
 import type { ReactiveState } from '@jasonshimmy/custom-elements-runtime'
@@ -19,11 +21,14 @@ let _indexPromise: Promise<unknown> | null = null
  * Returns the same Promise on repeated calls — the index is built at most once
  * per session regardless of how many search components are mounted.
  *
+ * If the fetch fails the singleton is cleared so the next search attempt
+ * retries automatically (no page reload required after a transient error).
+ *
  * @internal Exported for unit testing only.
  */
-export async function loadIndex(): Promise<unknown> {
+export function loadIndex(): Promise<unknown> {
   if (_indexPromise) return _indexPromise
-  _indexPromise = (async () => {
+  const attempt = (async () => {
     const [{ default: MiniSearch }, raw] = await Promise.all([
       import('minisearch'),
       fetch(contentSearchIndexUrl()).then((r) => {
@@ -37,7 +42,13 @@ export async function loadIndex(): Promise<unknown> {
       idField: '_path',
     })
   })()
-  return _indexPromise
+  _indexPromise = attempt
+  // Clear the singleton on failure so the next call retries the fetch.
+  // The === guard ensures a newer concurrent attempt is not accidentally cleared.
+  attempt.catch(() => {
+    if (_indexPromise === attempt) _indexPromise = null
+  })
+  return attempt
 }
 
 /** Resets the module-level singleton. Used in tests only. @internal */
@@ -45,6 +56,33 @@ export function resetIndexSingleton(): void {
   _indexPromise = null
 }
 
+// ─── Per-component debounce state ────────────────────────────────────────────
+
+// Stores the debounce timer handle and stale-seq counter directly on the
+// component context object (non-enumerable, same pattern the runtime uses for
+// _hookCallbacks). This makes the values stable across re-renders — the context
+// object is fixed for the lifetime of the element instance — without leaking
+// into the reactive proxy or triggering spurious updates.
+
+interface DebounceState {
+  seq: number
+  timer: ReturnType<typeof setTimeout> | null
+}
+
+const _STATE_KEY = '_cerSearchDebounce'
+
+function getDebounceState(ctx: Record<string, unknown>): DebounceState {
+  if (!Object.prototype.hasOwnProperty.call(ctx, _STATE_KEY)) {
+    Object.defineProperty(ctx, _STATE_KEY, {
+      value: { seq: 0, timer: null } as DebounceState,
+      writable: false,    // object ref is fixed; its properties are still mutable
+      enumerable: false,  // invisible to the reactive proxy set-trap
+      configurable: false,
+    })
+  }
+  return (ctx as Record<string, DebounceState>)[_STATE_KEY]
+}
+
 // ─── Composable ───────────────────────────────────────────────────────────────
 
 export interface UseContentSearchReturn {
@@ -59,24 +97,45 @@ const _factory = createComposable((): UseContentSearchReturn => {
   const results = ref<ContentSearchResult[]>([])
   const loading = ref(false)
 
-  // Pre-warm index on mount
+  // Debounce state lives on the component context, not in local render-body variables.
+  // Local variables are re-created on every re-render; the context object is stable
+  // for the lifetime of the element.  Storing state here lets the render-body
+  // watch() (see below) pick up the same timer and sequence counter across re-renders
+  // without the watcher accumulation that occurs when watch() is placed inside
+  // useOnConnected() (which runs once per mount but is not registered for cleanup
+  // by the reactive system, leaking watchers on every disconnect + reconnect cycle).
+  const state = getDebounceState(getCurrentComponentContext()! as Record<string, unknown>)
+
+  // Pre-warm the index on first mount so the first real search is faster.
   useOnConnected(() => {
     loadIndex().catch(() => {/* silently ignore pre-warm errors */})
   })
 
-  // Monotonic counter to discard stale async results
-  let _seq = 0
-  let _debounceTimer: ReturnType<typeof setTimeout> | null = null
+  // Cancel any in-flight debounce on unmount so stale async work doesn't land
+  // after the component is gone.
+  useOnDisconnected(() => {
+    if (state.timer !== null) {
+      clearTimeout(state.timer)
+      state.timer = null
+    }
+    state.seq++ // discard any in-flight async search
+    loading.value = false
+  })
 
+  // watch() is in the render body so the reactive system registers it under the
+  // current component and tears it down automatically on re-render and disconnect.
+  // The mutable state (seq / timer) lives on the context (above) and persists
+  // across re-renders — new watcher instances see the same timer and counter,
+  // which is what makes debounce cancellation correct even after a re-render.
   watch(query, (q: string) => {
-    if (_debounceTimer !== null) {
-      clearTimeout(_debounceTimer)
-      _debounceTimer = null
+    if (state.timer !== null) {
+      clearTimeout(state.timer)
+      state.timer = null
     }
 
     if (!q) {
       // Increment seq so any in-flight async search is discarded when it resolves
-      _seq++
+      state.seq++
       loading.value = false
       results.value = []
       return
@@ -85,21 +144,21 @@ const _factory = createComposable((): UseContentSearchReturn => {
     // Signal loading immediately so the UI can respond before the debounce fires
     loading.value = true
 
-    _debounceTimer = setTimeout(async () => {
-      _debounceTimer = null
-      const seq = ++_seq
+    state.timer = setTimeout(async () => {
+      state.timer = null
+      const seq = ++state.seq
 
       try {
         const index = await loadIndex() as { search(q: string, opts?: { prefix?: boolean }): ContentSearchResult[] }
-        if (seq !== _seq) return // stale — a newer query is in flight
+        if (seq !== state.seq) return // stale — a newer query is in flight
         results.value = index.search(q, { prefix: true }) as ContentSearchResult[]
       } catch {
-        if (seq !== _seq) return
+        if (seq !== state.seq) return
         results.value = []
       } finally {
         // Only clear loading for the most recent search; a newer in-flight search
         // keeps loading=true until it settles.
-        if (seq === _seq) loading.value = false
+        if (seq === state.seq) loading.value = false
       }
     }, 200)
   })

package/src/runtime/composables/use-head.ts

@@ -152,7 +152,14 @@ export function useHead(input: HeadInput): void {
         const rel = link.rel
         const href = link.href
         if (rel && href) {
-          let el = document.querySelector(`link[rel="${rel}"][href="${href}"]`)
+          // Canonical and icon links are singletons — find by rel alone so that
+          // updating the URL overwrites the existing tag rather than adding a
+          // duplicate. All other link types are matched by rel+href (e.g.
+          // stylesheets, where multiple hrefs are valid).
+          const isSingleton = rel === 'canonical' || rel === 'icon' || rel === 'shortcut icon'
+          let el = isSingleton
+            ? document.querySelector(`link[rel="${rel}"]`)
+            : document.querySelector(`link[rel="${rel}"][href="${href}"]`)
           if (!el) {
             el = document.createElement('link')
             document.head.appendChild(el)
@@ -176,12 +183,27 @@ export function useHead(input: HeadInput): void {
           }
           document.head.appendChild(el)
         } else if (innerHTML && !src) {
-          const el = document.createElement('script')
-          el.textContent = innerHTML
-          for (const [k, v] of Object.entries(rest)) {
-            el.setAttribute(k, v)
+          const type = rest.type ?? ''
+          if (type === 'application/ld+json') {
+            // JSON-LD is a singleton — update existing content rather than
+            // appending a duplicate on re-render or SPA navigation.
+            let el = document.querySelector('script[type="application/ld+json"]')
+            if (!el) {
+              el = document.createElement('script')
+              document.head.appendChild(el)
+              for (const [k, v] of Object.entries(rest)) {
+                el.setAttribute(k, v)
+              }
+            }
+            ;(el as HTMLScriptElement).textContent = innerHTML
+          } else {
+            const el = document.createElement('script')
+            el.textContent = innerHTML
+            for (const [k, v] of Object.entries(rest)) {
+              el.setAttribute(k, v)
+            }
+            document.head.appendChild(el)
           }
-          document.head.appendChild(el)
         }
       }
     }

package/src/types/config.ts

@@ -241,6 +241,14 @@ export interface RuntimeConfig {
 export interface CerAppConfig {
   mode?: 'spa' | 'ssr' | 'ssg'
   srcDir?: string // defaults to 'app'
+  /**
+   * The canonical origin of the site (e.g. `'https://example.com'`).
+   * No trailing slash. When set, the SSG build automatically:
+   * - Injects `<link rel="canonical" href="${siteUrl}${path}">` into every page.
+   * - Writes a `robots.txt` to `dist/` (skipped when a `public/robots.txt` already exists).
+   * Also available at runtime via `useRuntimeConfig().public.siteUrl`.
+   */
+  siteUrl?: string
   /** File-based content layer configuration. Reads from `content/` at the project root by default. */
   content?: import('./content.js').CerContentConfig
   /**