uniweb 0.56.7 → 0.56.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.56.7",
+  "version": "0.56.9",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -43,10 +43,10 @@
     "tar": "^7.0.0",
     "@uniweb/core": "^0.29.4",
     "@uniweb/runtime": "^0.26.4",
-    "@uniweb/schemas": "^0.3.1",
+    "@uniweb/semantic-parser": "^1.4.1",
+    "@uniweb/schemas": "^0.3.2",
     "@uniweb/content-writer": "^0.3.4",
-    "@uniweb/kit": "^0.19.3",
-    "@uniweb/semantic-parser": "^1.4.1"
+    "@uniweb/kit": "^0.19.3"
   },
   "peerDependencies": {
     "@uniweb/build": "^0.52.6",

package/partials/agents.md

@@ -2511,6 +2511,8 @@ uniweb validate                   # Check file-based data against declared schem
 npx uniweb@latest update          # Align @uniweb/* deps + AGENTS.md (--dry-run, --yes)
                                   #   bare `uniweb update` aligns to the CLI you ALREADY have
 uniweb inspect <path>             # Show parsed content for a section or page (--raw for the AST)
+uniweb snapshot                   # Compose site/public/preview.webp from the site; sets preview: if unset
+                                  #   needs `pnpm add -D -w @uniweb/snapshot` and Chrome or Edge
 
 uniweb <command> --help           # Per-command flags — no side effects. Prefer this over guessing.
 ```

package/src/backend/site-sync.js

@@ -17,6 +17,7 @@ import yaml from 'js-yaml'
 import { hasUncommittedContent } from '../utils/git.js'
 import { recordSiteBackend } from '../utils/site-identity.js'
 import { humanBytes } from '../utils/bytes.js'
+import { isAuthoredPreview } from '../utils/preview.js'
 import {
   backfillEntityUuids,
   writeSiteEntityUuid,
@@ -364,11 +365,6 @@ export function dropSiteBoundValues(siteDir) {
   return dropped
 }
 
-// An author's preview is an address — a URL, or a site-root / relative path. Anything
-// else is the app's generated-image token.
-const isAuthoredPreview = (v) =>
-  typeof v === 'string' && (/^https?:\/\//i.test(v) || /^\.{0,2}\//.test(v))
-
 export function readSyncCache(siteDir) {
   return readMap(siteDir, 'hashes')
 }

package/src/commands/snapshot.js

@@ -0,0 +1,349 @@
+/**
+ * Snapshot Command
+ *
+ * Captures a site in a real browser and composes a preview image from the
+ * captures — by default the site's card image, recorded as `preview:` in
+ * site.yml.
+ *
+ * The capturing and composing is `@uniweb/snapshot`, a separate package so that
+ * nobody who never takes a snapshot installs a browser driver. This command finds
+ * the site, puts it behind a URL, and records the result:
+ *
+ *   uniweb snapshot                 build the site, serve dist/, capture it
+ *   uniweb snapshot --dev           capture the site's Vite dev server (no build)
+ *   uniweb snapshot --url <url>     capture a site that is already running
+ *
+ * The layout is chosen from the page: one that scrolls gets `split` (the first
+ * view in a browser window, overlapped by a long strip of the page); one that
+ * does not — a documentation shell, an app — gets `device` (desktop and phone).
+ *
+ * `preview:` is written only when site.yml has none, or holds the app's generated
+ * token. An address the author wrote is never replaced.
+ */
+
+import { spawn } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { isAbsolute, join, relative, resolve, sep } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import yaml from 'js-yaml'
+import { upsertYamlScalar } from '@uniweb/build/uwx'
+
+import { didYouMean } from '../utils/args.js'
+import { humanBytes } from '../utils/bytes.js'
+import { discoverSites } from '../utils/discover.js'
+import { detectWorkspacePm } from '../utils/pm.js'
+import { isAuthoredPreview } from '../utils/preview.js'
+import { findWorkspaceRoot } from '../utils/workspace.js'
+
+const RED = '\x1b[31m'
+const GREEN = '\x1b[32m'
+const YELLOW = '\x1b[33m'
+const CYAN = '\x1b[36m'
+const DIM = '\x1b[2m'
+const RESET = '\x1b[0m'
+
+const VALUE_FLAGS = ['--site', '--url', '--route', '--layout', '--tone', '--size', '--scale', '--quality', '--out', '--hide']
+const BOOLEAN_FLAGS = ['--dev', '--no-build', '--no-set-preview']
+const GLOBAL_FLAGS = ['--non-interactive', '--help', '-h']
+const ALL_FLAGS = [...VALUE_FLAGS, ...BOOLEAN_FLAGS, ...GLOBAL_FLAGS]
+
+export const DEFAULT_OUTPUT = join('public', 'preview.webp')
+
+class UsageError extends Error {}
+
+const camel = (flag) => flag.replace(/^--/, '').replace(/-([a-z])/g, (_, c) => c.toUpperCase())
+
+/**
+ * Parse `uniweb snapshot` arguments. Throws a UsageError naming the first problem.
+ *
+ * @param {string[]} args
+ */
+export function parseSnapshotArgs(args = []) {
+  const options = { hide: [], positionals: [] }
+  for (let i = 0; i < args.length; i++) {
+    const raw = args[i]
+    if (raw === '--') {
+      options.positionals.push(...args.slice(i + 1))
+      break
+    }
+    if (!raw.startsWith('-') || raw === '-') {
+      options.positionals.push(raw)
+      continue
+    }
+    const eq = raw.indexOf('=')
+    const name = eq === -1 ? raw : raw.slice(0, eq)
+    if (VALUE_FLAGS.includes(name)) {
+      const value = eq === -1 ? args[++i] : raw.slice(eq + 1)
+      if (value === undefined || value === '' || (eq === -1 && value.startsWith('--'))) {
+        throw new UsageError(`\`${name}\` needs a value.`)
+      }
+      if (name === '--hide') options.hide.push(value)
+      else options[camel(name)] = value
+    } else if (BOOLEAN_FLAGS.includes(name)) {
+      options[camel(name)] = true
+    } else if (!GLOBAL_FLAGS.includes(name)) {
+      const suggestion = didYouMean(name, ALL_FLAGS)
+      throw new UsageError(
+        `Unknown flag \`${name}\` for \`uniweb snapshot\`.` + (suggestion ? ` Did you mean \`${suggestion}\`?` : '')
+      )
+    }
+  }
+
+  if (options.dev && options.url) throw new UsageError('Pass `--dev` or `--url`, not both.')
+  if (options.layout && !['auto', 'split', 'device'].includes(options.layout)) {
+    throw new UsageError('`--layout` is auto, split or device.')
+  }
+  if (options.tone && !['auto', 'light', 'deep'].includes(options.tone)) {
+    throw new UsageError('`--tone` is auto, light or deep.')
+  }
+  if (options.size !== undefined) {
+    const match = /^(\d+)x(\d+)$/.exec(options.size)
+    const [width, height] = match ? [Number(match[1]), Number(match[2])] : []
+    if (!match || width < 320 || height < 200 || width > 4096 || height > 4096) {
+      throw new UsageError('`--size` is WIDTHxHEIGHT, e.g. 1600x1000 (320–4096 wide, 200–4096 tall).')
+    }
+    options.canvas = { width, height }
+  }
+  if (options.scale !== undefined) {
+    if (!['1', '2'].includes(options.scale)) throw new UsageError('`--scale` is 1 or 2.')
+    options.scale = Number(options.scale)
+  }
+  if (options.quality !== undefined) {
+    const quality = Number(options.quality)
+    if (!Number.isInteger(quality) || quality < 1 || quality > 100) {
+      throw new UsageError('`--quality` is a whole number from 1 to 100.')
+    }
+    options.quality = quality
+  }
+  return options
+}
+
+/**
+ * The `preview:` value that names `output`, or null when it cannot be named — an
+ * image outside the site's `public/` folder has no site-root path.
+ */
+export function previewValueFor(siteDir, output) {
+  const rel = relative(join(siteDir, 'public'), output)
+  if (!rel || rel.startsWith('..') || isAbsolute(rel)) return null
+  return '/' + rel.split(sep).join('/')
+}
+
+/**
+ * What to do with site.yml's `preview:` given the value we would write.
+ * @returns {'set'|'unchanged'|'replace'|'keep'}
+ */
+export function previewDecision(current, next) {
+  if (current === undefined || current === null || current === '') return 'set'
+  if (current === next) return 'unchanged'
+  return isAuthoredPreview(current) ? 'keep' : 'replace'
+}
+
+/** The site the command applies to: named, else the one containing cwd, else the only one. */
+export function pickSite(sites, rootDir, { requested, cwd }) {
+  if (requested) {
+    return { site: sites.find((s) => s.name === requested || s.path === requested) ?? null }
+  }
+  const containing = sites.find((s) => {
+    const rel = relative(join(rootDir, s.path), cwd)
+    return !rel.startsWith('..') && !isAbsolute(rel)
+  })
+  if (containing) return { site: containing }
+  return { site: sites[0] ?? null, ambiguous: sites.length > 1 }
+}
+
+/** Import `@uniweb/snapshot` from the site, the workspace, or next to this CLI. */
+async function loadSnapshotPackage(dirs) {
+  for (const dir of dirs) {
+    if (!dir) continue
+    let entry
+    try {
+      entry = createRequire(join(dir, 'package.json')).resolve('@uniweb/snapshot')
+    } catch {
+      continue
+    }
+    return import(pathToFileURL(entry).href)
+  }
+  try {
+    return await import('@uniweb/snapshot')
+  } catch (err) {
+    if (err.code === 'ERR_MODULE_NOT_FOUND') return null
+    throw err
+  }
+}
+
+function installHint(rootDir) {
+  switch (detectWorkspacePm(rootDir)) {
+    case 'npm':
+      return 'npm install --save-dev @uniweb/snapshot'
+    case 'yarn':
+      return 'yarn add --dev -W @uniweb/snapshot'
+    default:
+      return 'pnpm add -D -w @uniweb/snapshot'
+  }
+}
+
+/**
+ * `uniweb build` in the site, with this same CLI. Its output is held back and
+ * shown only if it fails: on success it ends in shipping advice that has nothing
+ * to do with taking a snapshot.
+ */
+function runBuild(siteDir) {
+  return new Promise((done, fail) => {
+    const child = spawn(process.execPath, [process.argv[1], 'build'], {
+      cwd: siteDir,
+      stdio: ['ignore', 'pipe', 'pipe']
+    })
+    const output = []
+    child.stdout.on('data', (chunk) => output.push(chunk))
+    child.stderr.on('data', (chunk) => output.push(chunk))
+    child.on('error', fail)
+    child.on('close', (code) => {
+      if (code === 0) return done()
+      process.stderr.write(Buffer.concat(output))
+      fail(new Error(`The site build failed (exit ${code}).`))
+    })
+  })
+}
+
+function readSiteYml(siteDir) {
+  const file = join(siteDir, 'site.yml')
+  if (!existsSync(file)) return { file, data: {} }
+  try {
+    return { file, data: yaml.load(readFileSync(file, 'utf8')) || {} }
+  } catch {
+    return { file, data: {} }
+  }
+}
+
+function fail(message, ...details) {
+  const [first, ...rest] = String(message).split('\n')
+  console.error(`${RED}✗${RESET} ${first}`)
+  for (const line of [...rest, ...details]) console.error(`  ${line.replace(/^ {2}/, '')}`)
+  process.exit(1)
+}
+
+export async function snapshot(args = []) {
+  let options
+  try {
+    options = parseSnapshotArgs(args)
+  } catch (err) {
+    if (!(err instanceof UsageError)) throw err
+    fail(err.message, 'Run `uniweb snapshot --help` for the accepted flags.')
+  }
+
+  const cwd = process.cwd()
+  const rootDir = findWorkspaceRoot(cwd)
+  const sites = rootDir ? await discoverSites(rootDir).catch(() => []) : []
+  const requested = options.site ?? options.positionals[0] ?? null
+  const { site, ambiguous } = pickSite(sites, rootDir ?? cwd, { requested, cwd })
+
+  if (requested && !site) {
+    fail(`Site "${requested}" not found.`, `Available: ${sites.map((s) => s.name).join(', ') || '(none)'}`)
+  }
+  if (!site && !options.url) {
+    fail('No site found here.', 'Run this inside a Uniweb workspace, or pass `--url <address> --out <file>`.')
+  }
+  if (!site && !options.out) {
+    fail('`--out <file>` is needed outside a site: there is no public/ folder to write to.')
+  }
+  if (ambiguous) {
+    console.error(`${YELLOW}⚠${RESET} Multiple sites found; using ${CYAN}${site.name}${RESET}. Pick one with \`--site <name>\`.`)
+  }
+
+  const siteDir = site ? join(rootDir, site.path) : null
+  const output = options.out ? resolve(cwd, options.out) : join(siteDir, DEFAULT_OUTPUT)
+
+  const lib = await loadSnapshotPackage([siteDir, rootDir])
+  if (!lib) {
+    fail(
+      '`uniweb snapshot` needs `@uniweb/snapshot`, which is not installed here.',
+      'Add it as a dev dependency of the workspace:',
+      `  ${CYAN}${installHint(rootDir)}${RESET}`
+    )
+  }
+
+  // Put the site behind a URL.
+  let source
+  try {
+    if (options.url) {
+      source = { url: options.url, label: options.url, close: async () => {} }
+    } else if (options.dev) {
+      console.error(`${DIM}→ starting the dev server for ${site.name}${RESET}`)
+      const dev = await lib.startDevServer(siteDir)
+      source = { url: dev.url, label: `dev server (${dev.url})`, close: dev.close }
+    } else {
+      if (!options.noBuild) {
+        console.error(`${DIM}→ building ${site.name}${RESET}`)
+        await runBuild(siteDir)
+      }
+      const dist = join(siteDir, 'dist')
+      if (!existsSync(join(dist, 'index.html'))) {
+        fail(`No built site at ${relative(cwd, dist) || dist}.`, 'Run without `--no-build`, or build the site first.')
+      }
+      const server = await lib.serveDirectory(dist, { base: readSiteYml(siteDir).data.base })
+      source = { url: server.url, label: 'the built site', close: server.close }
+    }
+  } catch (err) {
+    fail(err.message)
+  }
+
+  let result
+  try {
+    result = await lib.snapshot({
+      url: source.url,
+      route: options.route,
+      layout: options.layout,
+      tone: options.tone,
+      canvas: options.canvas,
+      scale: options.scale,
+      quality: options.quality,
+      hide: options.hide,
+      output,
+      onStep: (step) => {
+        if (step === 'capture') {
+          const page = options.route && options.route !== '/' ? ` · ${options.route}` : ''
+          console.error(`${DIM}→ capturing ${source.label}${page}${RESET}`)
+        }
+        if (step === 'compose') console.error(`${DIM}→ composing${RESET}`)
+      },
+    })
+  } catch (err) {
+    await source.close().catch(() => {})
+    fail(err.message)
+  }
+  await source.close()
+
+  const shown = relative(cwd, output) || output
+  console.log(
+    `${GREEN}✓${RESET} ${shown} ${DIM}(${result.width}×${result.height}, ${humanBytes(result.bytes)} — ${result.layout} layout, ${result.tone} background)${RESET}`
+  )
+
+  if (!siteDir || options.noSetPreview) return
+
+  const value = previewValueFor(siteDir, output)
+  const siteYml = readSiteYml(siteDir)
+  if (!value) {
+    console.log(`  ${DIM}site.yml not changed: the image is outside ${join(site.path, 'public')}/, so it has no site path.${RESET}`)
+    return
+  }
+  const current = siteYml.data.preview
+  switch (previewDecision(current, value)) {
+    case 'set':
+      upsertYamlScalar(siteYml.file, 'preview', value)
+      console.log(`  site.yml: ${CYAN}preview: ${value}${RESET}`)
+      break
+    case 'replace':
+      upsertYamlScalar(siteYml.file, 'preview', value)
+      console.log(`  site.yml: ${CYAN}preview: ${value}${RESET} ${DIM}(replaces the app-generated preview)${RESET}`)
+      break
+    case 'unchanged':
+      console.log(`  ${DIM}site.yml already has preview: ${value}${RESET}`)
+      break
+    case 'keep':
+      console.log(`  ${YELLOW}site.yml keeps preview: ${current}${RESET} ${DIM}— set it to ${value} to use this image.${RESET}`)
+      break
+  }
+}
+
+export default snapshot

package/src/framework-index.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-09-16T20:57:12.370Z",
+  "generatedAt": "2026-09-17T03:24:18.741Z",
   "packages": {
     "@uniweb/api": {
       "version": "0.3.6",
@@ -96,7 +96,7 @@
       "deps": []
     },
     "@uniweb/schemas": {
-      "version": "0.3.1",
+      "version": "0.3.2",
       "path": "framework/schemas",
       "deps": []
     },
@@ -110,8 +110,13 @@
       "path": "framework/semantic-parser",
       "deps": []
     },
+    "@uniweb/snapshot": {
+      "version": "0.1.1",
+      "path": "framework/snapshot",
+      "deps": []
+    },
     "@uniweb/templates": {
-      "version": "0.14.5",
+      "version": "0.14.7",
       "path": "framework/templates",
       "deps": []
     },

package/src/index.js

@@ -731,6 +731,15 @@ async function main() {
     return
   }
 
+  // Handle snapshot command (dynamic import — depends on @uniweb/build; loads
+  // @uniweb/snapshot itself, from the workspace, and says how to add it if absent)
+  if (command === 'snapshot') {
+    const { snapshot } = await importProjectCommand('./commands/snapshot.js')
+    await snapshot(args.slice(1))
+    await showUpdateNotification()
+    return
+  }
+
   // Handle docs command (dynamic import — depends on @uniweb/build)
   if (command === 'docs') {
     const { docs } = await importProjectCommand('./commands/docs.js')
@@ -1479,6 +1488,42 @@ script (\`pnpm --filter <site> dev\` or \`npm -w <site> run dev\`). Picks
 the single site automatically; for multi-site workspaces the first
 site runs by default with a notice pointing at \`--site\` for explicit
 selection.
+`,
+    snapshot: `
+${colors.cyan}${colors.bright}uniweb snapshot${colors.reset} ${colors.dim}— Compose a preview image of a site${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  uniweb snapshot [<site>] [options]
+
+Opens the site in a headless Chrome, captures it, and composes the captures into
+one image: by default ${colors.bright}site/public/preview.webp${colors.reset}, recorded as ${colors.cyan}preview:${colors.reset} in site.yml
+when site.yml has none, or only the app's generated one. A URL or image path you
+wrote is never replaced.
+
+A page that scrolls gets the ${colors.bright}split${colors.reset} layout: the first view in a browser window,
+overlapped by a long strip of the page. A page that does not scroll as a page (a
+docs shell, an app) gets ${colors.bright}device${colors.reset}: a desktop window and a phone.
+
+Needs ${colors.cyan}@uniweb/snapshot${colors.reset} in the workspace (\`pnpm add -D -w @uniweb/snapshot\`) and
+Google Chrome, Microsoft Edge, or a Chromium named by $UNIWEB_SNAPSHOT_BROWSER.
+
+${colors.bright}Where the site comes from:${colors.reset}
+  (default)           Build the site, then capture dist/
+  --no-build          Capture the existing dist/ as is
+  --dev               Capture the site's Vite dev server (no build)
+  --url <address>     Capture a site that is already running
+
+${colors.bright}Options:${colors.reset}
+  --site <name>       The site (default: the one you are in, or the only one)
+  --route <path>      The page to capture (default: the home page)
+  --layout <name>     auto (default), split, device
+  --tone <name>       Background: auto (default), light, deep
+  --size <WxH>        Image size in CSS pixels (default: 1600x1000)
+  --scale <n>         1 (default) or 2 for a double-density image
+  --quality <n>       Encoder quality, 1–100 (default: 82)
+  --out <file>        Where to write it; .webp, .png, .jpg or .avif
+  --hide <selector>   Hide matching elements before capturing (repeatable)
+  --no-set-preview    Write the image without touching site.yml
 `,
     build: `
 ${colors.cyan}${colors.bright}uniweb build${colors.reset} ${colors.dim}— Build the current project${colors.reset}
@@ -1917,6 +1962,7 @@ ${colors.bright}Commands:${colors.reset}
   rename <type>      Rename a foundation, site, or extension across the workspace
   dev                Start a dev server for a site
   build              Build the current project
+  snapshot           Compose a preview image of a site (its site.yml preview:)
   publish            Publish a site to Uniweb hosting (smart: foundation + sync + go live)
   deploy             Ship a site to a host (asks where, if not yet configured)
   export             Export a self-contained site for third-party hosting

package/src/utils/preview.js

@@ -0,0 +1,20 @@
+/**
+ * `site.yml::preview` — the site's card image — has two writers: an author, who
+ * writes an address (a URL, or a path to an image in the project), and the app,
+ * which writes a token naming an image it generated. This is the one test that
+ * tells them apart.
+ *
+ * It recognizes the author's shapes rather than the app's, so it does not depend
+ * on the token's format: a URL, a path starting `/`, `./` or `../`, or a relative
+ * path to an image file (`images/card.png`).
+ */
+
+const IMAGE_FILE = /\.(avif|gif|jpe?g|png|svg|webp)$/i
+
+/**
+ * @param {unknown} value
+ * @returns {boolean} true when `value` is an author's address rather than the app's token
+ */
+export const isAuthoredPreview = (value) =>
+  typeof value === 'string' &&
+  (/^https?:\/\//i.test(value) || /^\.{0,2}\//.test(value) || IMAGE_FILE.test(value.trim()))

package/src/utils/scaffold.js

@@ -178,10 +178,22 @@ export async function applyContent(
     '.gitignore'
   ])
 
-  // Config files that should be merged, not overwritten.
-  // Keys listed here are preserved from the scaffolded version.
+  // Config files that should be merged, not overwritten: for each listed
+  // key, when the scaffolded version's value is used.
+  //
+  //   foundation  ALWAYS — the CLI resolved it for this project, and a
+  //               content template cannot know it.
+  //   name        ONLY WHEN THE TEMPLATE SETS NONE. A template's own name is
+  //               the default name of a site made from it — the same thing
+  //               cloning a template in an app gives — so a literal
+  //               `name: Product Launch` survives, and the project name fills
+  //               in for a template with no name, or only the
+  //               `{{projectName}}` placeholder.
   const MERGE_FILES = {
-    'site.yml': ['name', 'foundation']
+    'site.yml': [
+      ['name', 'when-template-has-none'],
+      ['foundation', 'always']
+    ]
   }
 
   await copyContentRecursive(
@@ -267,8 +279,9 @@ async function copyContentRecursive(
       // educational structure of the content template survive) and
       // override only the specific top-level keys listed in
       // preserveKeys with the values from the already-scaffolded base
-      // file (so the user's chosen project name and foundation ref
-      // don't get replaced by whatever the content template hardcoded).
+      // file (so the resolved foundation ref is never replaced by whatever
+      // the content template hardcoded, and a project name fills in for a
+      // template that names nothing).
       //
       // Earlier versions of this code parsed both files through
       // js-yaml, merged the objects, and re-emitted the result via
@@ -283,17 +296,21 @@ async function copyContentRecursive(
         const existing = yaml.load(existingContent) || {}
         let merged = newContent ?? (await fs.readFile(sourcePath, 'utf-8'))
 
-        for (const key of preserveKeys) {
+        for (const [key, when] of preserveKeys) {
           if (existing[key] === undefined) continue
           const baseLine = matchTopLevelLine(existingContent, key)
           if (!baseLine) continue
           // If the new content carries the key, replace its line with
-          // the scaffolded value (preserving the user's project/foundation
-          // choice). Otherwise insert the line — older content templates
-          // (notably `docs/site/site.yml.hbs`) omit `foundation:` entirely,
-          // and dropping it leaves the site without a foundation ref so
-          // the entry's `import '#foundation/styles'` fails at build time.
+          // the scaffolded value — unless the key only fills in, and the
+          // template set a value of its own. Otherwise insert the line —
+          // older content templates (notably `docs/site/site.yml.hbs`) omit
+          // `foundation:` entirely, and dropping it leaves the site without a
+          // foundation ref so the entry's `import '#foundation/styles'` fails
+          // at build time.
           if (matchTopLevelLine(merged, key)) {
+            if (when === 'when-template-has-none' && hasOwnValue(merged, key)) {
+              continue
+            }
             merged = replaceTopLevelLine(merged, key, baseLine)
           } else {
             merged = insertTopLevelLine(merged, baseLine)
@@ -358,6 +375,22 @@ function escapeRegex(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
 }
 
+/**
+ * Whether a content template sets `key` to a value of its own: a non-empty
+ * string that is not an unrendered `{{placeholder}}` (a plain `site.yml`, not
+ * `.hbs`, is copied without rendering). Content that does not parse counts as
+ * setting nothing, so the scaffolded value fills in, as it always did.
+ */
+function hasOwnValue(content, key) {
+  let value
+  try {
+    value = (yaml.load(content) || {})[key]
+  } catch {
+    return false
+  }
+  return typeof value === 'string' && value.trim() !== '' && !value.includes('{{')
+}
+
 /**
  * Find the verbatim text of a single-line top-level YAML entry like
  * `name: foo bar` or `foundation: my-foundation`. Returns the matched