uniweb 0.56.6 → 0.56.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.56.6",
+  "version": "0.56.8",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,17 +41,17 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/content-writer": "^0.3.4",
     "@uniweb/core": "^0.29.4",
     "@uniweb/kit": "^0.19.3",
-    "@uniweb/semantic-parser": "^1.4.1",
     "@uniweb/schemas": "^0.3.1",
-    "@uniweb/runtime": "^0.26.4"
+    "@uniweb/runtime": "^0.26.4",
+    "@uniweb/semantic-parser": "^1.4.1",
+    "@uniweb/content-writer": "^0.3.4"
   },
   "peerDependencies": {
-    "@uniweb/semantic-parser": "^1.4.1",
-    "@uniweb/build": "^0.52.5",
-    "@uniweb/content-reader": "^1.2.5"
+    "@uniweb/build": "^0.52.6",
+    "@uniweb/content-reader": "^1.2.5",
+    "@uniweb/semantic-parser": "^1.4.1"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

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/add.js

@@ -209,11 +209,6 @@ export async function add(rawArgs) {
   const nonInteractive = isNonInteractive(rawArgs)
   const args = stripNonInteractiveFlag(rawArgs)
 
-  if (args[0] === '--help' || args[0] === '-h') {
-    showAddHelp()
-    return
-  }
-
   const pm = detectPackageManager()
   const prefix = getCliPrefix()
 
@@ -1821,98 +1816,3 @@ function parseNodeMajor(engines) {
   return match ? match[1] : null
 }
 
-/**
- * Show help for the add command.
- *
- * ⚠️ CURRENTLY UNREACHABLE, and the second copy of this text is the cost.
- * `src/index.js` short-circuits ANY `--help` in the args before dispatching
- * (its comment says why — `deploy --help` used to open a browser), and `add`
- * has a dedicated block in that file's HELP map, so `printCommandHelp('add')`
- * always wins and the `args[0] === '--help'` guard above never fires.
- *
- * ⛔ Which means a flag documented here and not there is documented nowhere.
- * Measured 2026-09-16, when `--starter` was added to both: this copy's
- * unescaped backticks around \`content:\` closed the template literal and broke
- * the WHOLE module — every `uniweb add` subcommand failed with "missing ) after
- * argument list" — and `uniweb add --help` printed correctly throughout,
- * because it never reaches this function.
- */
-function showAddHelp() {
-  log(`
-${colors.cyan}${colors.bright}Uniweb Add${colors.reset}
-
-Add projects, foundations, sites, extensions, section types, or CI workflows to your workspace.
-
-${colors.bright}Usage:${colors.reset}
-  uniweb add project [name] [options]
-  uniweb add foundation [name] [options]
-  uniweb add site [name] [options]
-  uniweb add extension <name> [options]
-  uniweb add section <name> [options]
-  uniweb add ci [options]
-
-${colors.bright}Common Options:${colors.reset}
-  --from <template>  Apply content from a template after scaffolding
-  --path <dir>       Custom directory for the package
-
-${colors.bright}Foundation Options:${colors.reset}
-  --project <name>   Group under a project directory (co-located layout)
-
-${colors.bright}Site Options:${colors.reset}
-  --foundation <n>   Foundation to wire to (prompted if multiple exist)
-  --project <name>   Group under a project directory (co-located layout)
-
-${colors.bright}Extension Options:${colors.reset}
-  --site <name>      Site to wire extension URL into
-
-${colors.bright}Section Options:${colors.reset}
-  --foundation <n>   Foundation to add section to (prompted if multiple exist)
-  --starter          Generate starter content from the section's \`content:\`
-                     declaration — what an author would begin editing. Works on
-                     a section that already exists (nothing is written), and on
-                     a new one (the scaffold gets a matching declaration)
-  --preset <name>    Frontmatter the starter content with this preset's params
-  --write <file>     Write the starter markdown to a file instead of printing it
-  --json             Emit the content structure and ProseMirror doc instead
-
-${colors.bright}CI Options:${colors.reset}
-  --host <name>          github-pages | cloudflare-pages | netlify | vercel
-                         (prompted when omitted)
-  --target <what>        site (default) | foundation
-                         'foundation' publishes built foundations at permanent
-                         versioned URLs — the free alternative to the catalog
-  --site <name>          Site the workflow builds (prompted if multiple exist)
-  --foundation <name>    With --target foundation: publish just this one
-  --domain <host>        Custom domain (GitHub Pages: writes CNAME, serves at root)
-  --project-name <name>  Name to register under on the host (default: the
-                         workspace name; Cloudflare Pages project, etc.)
-  --no-previews          Skip the per-PR preview workflow
-  --force                Overwrite an existing workflow file
-
-${colors.dim}Hosts that support PR previews: cloudflare-pages, netlify, vercel.
-GitHub Pages has no preview environment, so it scaffolds a deploy workflow only.${colors.reset}
-
-${colors.bright}Examples:${colors.reset}
-  uniweb add project docs                              # Create docs/foundation/ + docs/site/
-  uniweb add project docs --from academic              # Co-located pair + academic content
-  uniweb add foundation                                # Create ./foundation/ at root
-  uniweb add foundation ui                             # Create ./foundations/ui/
-  uniweb add site                                      # Create ./site/ at root
-  uniweb add site blog --foundation marketing          # Create ./sites/blog/ wired to marketing
-  uniweb add extension effects --site site             # Create ./extensions/effects/
-  uniweb add section Hero                              # Create Hero section type
-  uniweb add section Hero --foundation ui              # Target specific foundation
-  uniweb add section Hero --starter                    # Starter content for an existing Hero
-  uniweb add section Pricing --starter                 # Scaffold Pricing + content that fills it
-  uniweb add section Hero --starter --preset split     # Frontmatter it with the 'split' preset
-  uniweb add section Hero --starter --json             # The structure + ProseMirror, for a script
-  uniweb add foundation --project docs                 # Create ./docs/foundation/ (co-located)
-  uniweb add site --project docs                       # Create ./docs/site/ (co-located)
-  uniweb add ci                                        # Pick a host, add a deploy workflow
-  uniweb add ci --host github-pages --site marketing   # Pick host + site explicitly
-  uniweb add ci --host netlify                         # Deploy + PR-preview workflows
-  uniweb add ci --host vercel --no-previews            # Deploy workflow only
-  uniweb add ci --domain mysite.com                    # Custom domain → writes CNAME + UNIWEB_BASE=/
-  uniweb add ci --target foundation                    # Publish foundations at versioned URLs
-`)
-}

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:35:26.755Z",
+  "generatedAt": "2026-09-16T23:53:23.238Z",
   "packages": {
     "@uniweb/api": {
       "version": "0.3.6",
@@ -10,7 +10,7 @@
       ]
     },
     "@uniweb/build": {
-      "version": "0.52.5",
+      "version": "0.52.6",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -18,6 +18,7 @@
         "@uniweb/core",
         "@uniweb/projections",
         "@uniweb/runtime",
+        "@uniweb/runtime",
         "@uniweb/schemas",
         "@uniweb/semantic-parser",
         "@uniweb/theming"
@@ -109,8 +110,13 @@
       "path": "framework/semantic-parser",
       "deps": []
     },
+    "@uniweb/snapshot": {
+      "version": "0.1.0",
+      "path": "framework/snapshot",
+      "deps": []
+    },
     "@uniweb/templates": {
-      "version": "0.14.5",
+      "version": "0.14.6",
       "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}
@@ -1498,31 +1543,82 @@ ${colors.bright}Options:${colors.reset}
   --platform <name>  (Deprecated alias for --host)
 `,
     add: `
-${colors.cyan}${colors.bright}uniweb add${colors.reset} ${colors.dim}— Add a foundation, site, or extension${colors.reset}
+${colors.cyan}${colors.bright}Uniweb Add${colors.reset}
 
-${colors.bright}Subcommands:${colors.reset}
-  add project [name]      Add a co-located foundation + site pair
-  add foundation [name]   Add a foundation (--from, --path, --project)
-  add site [name]         Add a site (--from, --foundation, --path, --project)
-  add extension <name>    Add an extension (--from, --site, --path)
-  add section <name>      Add a section type to a foundation (--foundation, --starter)
-  add ci                  Add a CI workflow so every push deploys (--host, --target)
+Add projects, foundations, sites, extensions, section types, or CI workflows to your workspace.
+
+${colors.bright}Usage:${colors.reset}
+  uniweb add project [name] [options]
+  uniweb add foundation [name] [options]
+  uniweb add site [name] [options]
+  uniweb add extension <name> [options]
+  uniweb add section <name> [options]
+  uniweb add ci [options]
+
+${colors.bright}Common Options:${colors.reset}
+  --from <template>  Apply content from a template after scaffolding
+  --path <dir>       Custom directory for the package
+  --non-interactive  Fail with usage info instead of prompting
+
+${colors.bright}Foundation Options:${colors.reset}
+  --project <name>   Group under a project directory (co-located layout)
+
+${colors.bright}Site Options:${colors.reset}
+  --foundation <n>   Foundation to wire to (prompted if multiple exist)
+  --project <name>   Group under a project directory (co-located layout)
+
+${colors.bright}Extension Options:${colors.reset}
+  --site <name>      Site to wire extension URL into
+
+${colors.bright}Section Options:${colors.reset}
+  --foundation <n>   Foundation to add section to (prompted if multiple exist)
+  --starter          Generate starter content from the section's \`content:\`
+                     declaration — what an author would begin editing. Works on
+                     a section that already exists (nothing is written), and on
+                     a new one (the scaffold gets a matching declaration)
+  --preset <name>    Frontmatter the starter content with this preset's params
+  --write <file>     Write the starter markdown to a file instead of printing it
+  --json             Emit the content structure and ProseMirror doc instead
+
+${colors.bright}CI Options:${colors.reset}
+  --host <name>          github-pages | cloudflare-pages | netlify | vercel
+                         (prompted when omitted)
+  --target <what>        site (default) | foundation
+                         'foundation' publishes built foundations at permanent
+                         versioned URLs — the free alternative to the catalog
+  --site <name>          Site the workflow builds (prompted if multiple exist)
+  --foundation <name>    With --target foundation: publish just this one
+  --domain <host>        Custom domain (GitHub Pages: writes CNAME, serves at root)
+  --project-name <name>  Name to register under on the host (default: the
+                         workspace name; Cloudflare Pages project, etc.)
+  --no-previews          Skip the per-PR preview workflow
+  --force                Overwrite an existing workflow file
+
+${colors.dim}Hosts that support PR previews: cloudflare-pages, netlify, vercel.
+GitHub Pages has no preview environment, so it scaffolds a deploy workflow only.${colors.reset}
 
-${colors.bright}Common options:${colors.reset}
-  --from <template>       Source content from a template
-  --path <dir>            Override default folder location
-  --foundation <name>     Wire site/extension to this foundation (CI-friendly)
-  --site <name>           Wire extension to this site (CI-friendly)
-  --non-interactive       Fail with usage info instead of prompting
-
-${colors.bright}Starter content (add section):${colors.reset}
-  --starter               Generate starter content from the section's
-                          \`content:\` declaration — what an author would begin
-                          editing. Works on an existing section (writes nothing)
-                          and on a new one (the scaffold gets a declaration)
-  --preset <name>         Frontmatter it with this preset's params
-  --write <file>          Write the markdown to a file instead of printing
-  --json                  Emit the structure + ProseMirror doc instead
+${colors.bright}Examples:${colors.reset}
+  uniweb add project docs                              # Create docs/foundation/ + docs/site/
+  uniweb add project docs --from academic              # Co-located pair + academic content
+  uniweb add foundation                                # Create ./foundation/ at root
+  uniweb add foundation ui                             # Create ./foundations/ui/
+  uniweb add site                                      # Create ./site/ at root
+  uniweb add site blog --foundation marketing          # Create ./sites/blog/ wired to marketing
+  uniweb add extension effects --site site             # Create ./extensions/effects/
+  uniweb add section Hero                              # Create Hero section type
+  uniweb add section Hero --foundation ui              # Target specific foundation
+  uniweb add section Hero --starter                    # Starter content for an existing Hero
+  uniweb add section Pricing --starter                 # Scaffold Pricing + content that fills it
+  uniweb add section Hero --starter --preset split     # Frontmatter it with the 'split' preset
+  uniweb add section Hero --starter --json             # The structure + ProseMirror, for a script
+  uniweb add foundation --project docs                 # Create ./docs/foundation/ (co-located)
+  uniweb add site --project docs                       # Create ./docs/site/ (co-located)
+  uniweb add ci                                        # Pick a host, add a deploy workflow
+  uniweb add ci --host github-pages --site marketing   # Pick host + site explicitly
+  uniweb add ci --host netlify                         # Deploy + PR-preview workflows
+  uniweb add ci --host vercel --no-previews            # Deploy workflow only
+  uniweb add ci --domain mysite.com                    # Custom domain → writes CNAME + UNIWEB_BASE=/
+  uniweb add ci --target foundation                    # Publish foundations at versioned URLs
 `,
     export: `
 ${colors.cyan}${colors.bright}uniweb export${colors.reset} ${colors.dim}— Export a self-contained site for third-party hosting${colors.reset}
@@ -1866,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()))