uniweb 0.56.10 → 0.56.12

package/package.json

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

package/partials/agents.md

@@ -661,18 +661,37 @@ Decimals insert between: `2.5-testimonials.md` goes between `2-` and `3-`. **Ign
 title: About Us
 id: about                   # Stable identity (for page: links, survives moves)
 order: 2                    # Navigation sort position
-pages: [team, history, ...] # Child page order (... = rest). Without ... = strict (hides unlisted)
+sections: [hero, team, ...] # Section order within this page (same ... rule)
+pages: [team, history, ...] # Child page order, when this page has child folders
 redirect: academic          # Redirect to a child page (relative/absolute path, or URL)
 slug: { fr: a-propos }      # Localized URL segment per language
 
+# folder.yml  — a folder OF PAGES, where page.yml means a page built from sections
+title: Getting Started
+pages: [quickstart, app-tour, ...]  # Child page order (... = rest)
+
 # site.yml
 index: home                 # Just set the homepage
-pages: [home, about, ...]   # Order pages (... = rest, first = homepage); without ... = strict
+pages: [home, about, ...]   # Order pages (... = rest, first = homepage)
 foundation: '@acme/ui@1.2.0'  # The component system (see Part 2, step 1)
 extensions: ['@acme/fx@0.3.1'] # Secondary foundations — same shapes as foundation:
-runtime: 0.9.6              # Optional runtime pin; omit and the host chooses
 ```
 
+**The trailing `...` is not decoration — dropping it changes behaviour.** `pages:`
+in `folder.yml` and `site.yml`, and `sections:` in `page.yml`, all read it the same way:
+
+| written | means |
+|---|---|
+| `[a, b, ...]` | **inclusive** — `a` and `b` pinned in that order, **everything else follows** |
+| `['...']` | identical to omitting the key |
+| `[a, b]` — no `...` | **strict** — and every unlisted sibling is dropped from **every** menu |
+
+⚠️ **Strict is a navigation filter, not a delete, which is what makes it easy to
+miss.** Unlisted pages stay routed, stay in `dist/`, stay in `llms.txt` and still
+resolve by URL — only the links to them disappear. Your route count does not
+change and nothing warns. **If you list pages in order and mean "these first",
+end the list with `...`.**
+
 **Configuration cascades: `page.yml` → `folder.yml` → `site.yml` → foundation defaults.** Each level inherits from the one above and overrides specific values, the way CSS specificity works. This is what makes bulk assignment natural — put `layout: marketing` in a `folder.yml` and every page in that folder inherits it, while one page can still override with its own `page.yml`. Reach for `folder.yml` before editing the same key into a dozen `page.yml` files.
 
 **Route mapping:** folder structure maps 1:1 to routes. Every folder keeps its natural route — `pages:` controls **order only**, not which child "becomes" the parent. The only exception is the site root, where `index:` (or first in `pages:`) sets `/`.
@@ -2513,6 +2532,7 @@ npx uniweb@latest update          # Align @uniweb/* deps + AGENTS.md (--dry-run,
 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 snapshot --compare         # Several looks on one sheet; take one with its flags + --save (site/snapshot.yml)
 
 uniweb <command> --help           # Per-command flags — no side effects. Prefer this over guessing.
 ```

package/src/backend/foundation-bring-along.js

@@ -40,6 +40,7 @@ import { detectFoundationType, isExtensionUrl } from '@uniweb/build'
 import { computeFoundationDigest } from '../utils/code-upload.js'
 import { readFlagValue } from '../utils/args.js'
 import { isNonInteractive } from '../utils/interactive.js'
+import { compareSemverPrecedence } from '../utils/semver-precedence.js'
 
 /**
  * Resolve the site's LOCAL foundation — the one publish should bring along — or
@@ -117,13 +118,19 @@ export function resolveLocalExtensions(siteDir, siteYml) {
 }
 
 // The foundation's scoped catalog name (`@org/name`) from its package.json — an
-// already-scoped `name`, else `uniweb.scope` + a bare `name`. Null when neither
+// already-scoped name, else `uniweb.scope` + a bare one. Null when neither
 // yields a scoped name (then we can't look up the registered version, so the
 // caller treats the foundation as "release it and let register pick the scope").
+//
+// ⛔ The name is `uniweb.id` when set, exactly as the build reads it for the
+// schema that `register` submits (`build/src/schema.js`). Reading `name` alone —
+// as this did until 2026-09-17 — looked a `uniweb.id` foundation up under a name
+// the catalog does not have, so every push re-released it, and pinned the site
+// to that same wrong name.
 function foundationScopedName(dir) {
   try {
     const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'))
-    const name = pkg?.name
+    const name = pkg?.uniweb?.id || pkg?.name
     if (typeof name === 'string' && name.startsWith('@')) return name
     const scope = pkg?.uniweb?.scope
     if (scope && name) return `${String(scope).replace(/\/+$/, '')}/${name}`
@@ -344,8 +351,18 @@ async function bringLocalCodeAlong({
       )
       return { released: false, proceed: true, ref: registeredRef(reg) }
     }
+    // ⚖️ The registry takes a NEW version only when it is greater than every one
+    // it holds — but an older local version may be one it already has, and
+    // re-registering that resumes. The CLI cannot tell which from here, so it
+    // does not refuse: it submits, says what will decide, and `register` prints
+    // the registry's answer if it is a no.
+    const order = compareSemverPrecedence(local.version, reg.latest_version)
     say.info(
-      `Releasing the ${kind} ${label} (new version; registered latest is ${reg.latest_version})…`
+      order === 1
+        ? `Releasing the ${kind} ${label} (new version; registered latest is ${reg.latest_version})…`
+        : order === null
+          ? `Releasing the ${kind} ${label} (registered latest is ${reg.latest_version})…`
+          : `Releasing the ${kind} ${label} — not newer than the registered latest ${reg.latest_version}, so the registry takes it only if ${local.version} is already registered with this code…`
     )
     return {
       released: releaseFoundation(local, args, cliBin, say),

package/src/backend/site-sync.js

@@ -328,16 +328,17 @@ export function clearRemoteSyncStateIfUnbound(siteDir) {
 /**
  * Drop the `site.yml` values that describe ONE PARTICULAR backend site, when this
  * project is bound to none (no `$uuid`) — a brand-new site, or the state our own
- * "clear `$uuid` to re-publish as a new site" recovery puts you in:
- *
- *   · `$url` — where the PREVIOUS site was live. The new one is not live anywhere
- *     yet; its first publish records its own.
- *   · `preview` in the APP's form — a timestamp naming the previous site's generated
- *     card image, which is keyed by that site's uuid and would dangle on this one.
+ * "clear `$uuid` to re-publish as a new site" recovery puts you in. Today that is
+ * one value: `preview` in the APP's form — a timestamp naming the previous site's
+ * generated card image, which is keyed by that site's uuid and would dangle on this
+ * one.
  *
  * ⛔ An AUTHOR's preview is theirs and stays: a URL, or a path to an image in the
  * project, is as good for the new site as for the old.
  *
+ * (`$url`, where the previous site was live, was dropped here too until it was
+ * retired on 2026-09-17. A leftover line is inert — nothing reads or sends it.)
+ *
  * The site.yml sibling of `clearRemoteSyncStateIfUnbound`, called beside it for the
  * same reason — before the create mints a uuid and makes the project look bound.
  *
@@ -354,7 +355,6 @@ export function dropSiteBoundValues(siteDir) {
   }
   if (!y || typeof y !== 'object' || typeof y.$uuid === 'string') return []
   const dropped = []
-  if (y.$url !== undefined && removeYamlScalar(file, '$url')) dropped.push('$url')
   if (
     y.preview !== undefined &&
     !isAuthoredPreview(y.preview) &&

package/src/commands/publish.js

@@ -124,26 +124,6 @@ const say = {
   dim: (m) => console.log(`  ${c.dim}${m}${c.reset}`)
 }
 
-// Origin-relative serve path → clickable absolute URL.
-//
-// ⭐ THE TWO SHAPES ARE A CONTRACT, NOT AN INCONSISTENCY — ratified 2026-08-29 and
-// documented in the backend's `wire-layer.md` rather than merely observed. A publish
-// returns an ABSOLUTE url when Cloudflare hosts the site (another origin entirely)
-// and an ORIGIN-RELATIVE path when the backend serves it itself, where its own
-// external origin is not reliably self-reportable from behind an ALB.
-//
-// ⇒ So this branch is implementing the contract, not defending against drift. I
-// reported the two shapes as a violation of "finished values only" in collab
-// framework↔backend; the backend checked, found the adjacent ruling that
-// explains the relative arm, and ratified both. Do not "fix" it by demanding one
-// shape — the caller's own origin is the missing half on the relative arm, and we
-// are the caller.
-function absolutizeServeUrl(origin, url) {
-  if (!url || typeof url !== 'string') return null
-  if (/^https?:\/\//.test(url)) return url
-  return `${origin.replace(/\/$/, '')}${url.startsWith('/') ? '' : '/'}${url}`
-}
-
 function readSiteYml(path) {
   if (!existsSync(path)) return {}
   try {
@@ -1020,7 +1000,12 @@ export async function publish(args = []) {
   } catch {
     result = {}
   }
-  const serveUrl = absolutizeServeUrl(client.origin, result.url)
+  // Where the site went live — a finished, absolute address, taken verbatim: shown,
+  // and recorded in deploy.yml, never composed onto. Until 2026-09-17 a backend
+  // serving the site itself answered with an origin-relative path, which this
+  // prefixed with our own origin; the reply is absolute now, so a path from an
+  // older backend is simply shown as one.
+  const serveUrl = typeof result.url === 'string' && result.url ? result.url : null
 
   // 8. Persist deploy.yml memory — a record of what went live (and so a re-run
   //    reuses the resolved target without re-asking). One identity:
@@ -1113,11 +1098,10 @@ export async function publish(args = []) {
     say.dim(`  site.yml lists ${unserved.join(', ')}, and ${unserved.length === 1 ? 'it was' : 'they were'} not published.`)
   }
   if (serveUrl) console.log(`  ${c.cyan}${serveUrl}${c.reset}`)
-  // ⛔ No site.yml write for where it went live. The backend records the reply's
-  // `url` on `info.url` at every publish, and pull brings it into `site.yml::$url`
-  // like any other key. A copy written here was a second writer that had to match
-  // the backend's byte for byte (the address printed above is made absolute, so it
-  // did not), and it left site.yml modified — which a plain `pull` refuses over.
+  // ⛔ No site.yml write for where it went live. That is a fact about this deploy,
+  // not about the site, and it is recorded where deploy facts live: deploy.yml's
+  // `lastDeploy.<target>.url` (step 8 above). site.yml carried it as `$url` ⇄
+  // `info.url` from 2026-09-10 until the field was retired on 2026-09-17.
   if (result.deploy_uuid) say.dim(`deploy: ${result.deploy_uuid}`)
   return { exitCode: 0 }
 }

package/src/commands/register.js

@@ -633,8 +633,8 @@ async function runRegister(args = []) {
     // Resume path: a registered version is immutable, so re-running after a
     // partial code delivery hits the duplicate rejection here — a STRUCTURED
     // 409 (problem+json, title "Conflict") — and proceeds to phase 2 (the
-    // code-uploads plan authorizes against the REGISTERED version; completed
-    // files are idempotent no-ops).
+    // code-uploads plan authorizes against the REGISTERED version; files it
+    // already stores come back `present` and are skipped).
     const isDuplicate = !standalone && res.status === 409
     if (isDuplicate) {
       alreadyRegistered = true
@@ -712,14 +712,18 @@ async function runRegister(args = []) {
           )
         }
         log(
-          `  ${colors.dim}Re-run \`uniweb register\` to resume — completed files are safe no-ops.${colors.reset}`
+          `  ${colors.dim}Re-run \`uniweb register\` to resume — files already stored are skipped.${colors.reset}`
         )
         return { exitCode: 1 }
       }
+      // "4 files" on a first upload; "1 uploaded, 3 already stored" on a resume.
+      const delivered = result.stored?.length
+        ? `${result.uploaded.length} uploaded, ${result.stored.length} already stored`
+        : `${result.uploaded.length} files`
       if (result.verified === true) {
         // serveBase is guaranteed here — it is what gated the check.
         success(
-          `Code delivered (${result.uploaded.length} files) — entry verified live at ${colors.dim}${result.serveBase}${colors.reset}`
+          `Code delivered (${delivered}) — entry verified live at ${colors.dim}${result.serveBase}${colors.reset}`
         )
       } else if (result.verified === false) {
         error(
@@ -727,9 +731,7 @@ async function runRegister(args = []) {
         )
         return { exitCode: 1 }
       } else {
-        success(
-          `Code delivered (${result.uploaded.length} files, ${result.mode} mode)`
-        )
+        success(`Code delivered (${delivered}, ${result.mode} mode)`)
         // Say WHY nothing was checked, rather than skipping in silence. The CLI
         // never reconstructs a serve URL (see utils/code-upload.js), so a plan
         // without `serve_base` means the location is not ours to know — name it
@@ -741,6 +743,16 @@ async function runRegister(args = []) {
         }
       }
     } catch (err) {
+      // ⚖️ A 4xx is the registry REFUSING the plan — e.g. a stored file
+      // declared at a different size (`version_content_changed`). Running the
+      // same command again gets the same answer, so do not suggest it: print
+      // the refusal's own sentence, which says what does help.
+      if (err.status >= 400 && err.status < 500 && err.detail) {
+        error(`Code delivery refused: HTTP ${err.status}`)
+        log(`  ${err.detail}`)
+        if (err.code) log(`  ${colors.dim}(${err.code})${colors.reset}`)
+        return { exitCode: 1 }
+      }
       error(`Code delivery failed: ${err.message}`)
       log(
         `  ${colors.dim}The schema registration above succeeded; re-run \`uniweb register\` to deliver the code.${colors.reset}`

package/src/commands/snapshot.js

@@ -12,10 +12,16 @@
  *   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
+ *   uniweb snapshot --compare       one capture, several looks, on one sheet
  *
  * 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).
+ * view in a browser window, beside a long strip of the page); one that does not
+ * — a documentation shell, an app — gets `device` (desktop and phone). How the
+ * two frames sit together is the look: `--gap`/`--overlap`, `--strip`, `--side`,
+ * `--frame`, `--tone`.
+ *
+ * A site keeps its chosen look in `site/snapshot.yml` (utils/snapshot-settings.js):
+ * the command's defaults for that site, which flags override and `--save` writes.
  *
  * `preview:` is written only when site.yml has none, or holds the app's generated
  * token. An address the author wrote is never replaced.
@@ -34,6 +40,13 @@ 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 {
+  SETTINGS_FILE,
+  SettingsError,
+  mergeSettings,
+  readSnapshotSettings,
+  saveSnapshotSettings
+} from '../utils/snapshot-settings.js'
 import { findWorkspaceRoot } from '../utils/workspace.js'
 
 const RED = '\x1b[31m'
@@ -43,45 +56,78 @@ 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']
+/** Flags that choose the image, by the `snapshot.yml` setting each one sets. */
+const SETTING_FLAGS = {
+  '--route': 'route',
+  '--layout': 'layout',
+  '--tone': 'tone',
+  '--gap': 'gap',
+  '--overlap': 'overlap',
+  '--strip': 'strip',
+  '--side': 'side',
+  '--frame': 'frame',
+  '--size': 'size',
+  '--scale': 'scale',
+  '--quality': 'quality',
+  '--hide': 'hide',
+  '--out': 'out'
+}
+const NUMBER_SETTINGS = ['gap', 'overlap', 'scale', 'quality']
+/** Flags that choose where the site comes from and what the run does. */
+const CONTROL_VALUE_FLAGS = ['--site', '--url']
+const CONTROL_BOOLEAN_FLAGS = ['--dev', '--no-build', '--no-set-preview', '--compare', '--save']
 const GLOBAL_FLAGS = ['--non-interactive', '--help', '-h']
-const ALL_FLAGS = [...VALUE_FLAGS, ...BOOLEAN_FLAGS, ...GLOBAL_FLAGS]
+const ALL_FLAGS = [...Object.keys(SETTING_FLAGS), ...CONTROL_VALUE_FLAGS, ...CONTROL_BOOLEAN_FLAGS, ...GLOBAL_FLAGS]
+const LOOK_SETTINGS = ['gap', 'overlap', 'strip', 'side', 'frame']
 
 export const DEFAULT_OUTPUT = join('public', 'preview.webp')
+export const COMPARE_OUTPUT = join('.uniweb', 'snapshot', 'compare.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.
+ * Parse `uniweb snapshot` arguments into the image settings they choose and the
+ * run controls. Checks the shape of each value; what a value may be (a layout
+ * name, a range) is checked by the package, before anything is built.
  *
  * @param {string[]} args
+ * @param {string} [cwd] - `--out` is relative to it
  */
-export function parseSnapshotArgs(args = []) {
-  const options = { hide: [], positionals: [] }
+export function parseSnapshotArgs(args = [], cwd = process.cwd()) {
+  const settings = {}
+  const control = {}
+  const positionals = []
   for (let i = 0; i < args.length; i++) {
     const raw = args[i]
     if (raw === '--') {
-      options.positionals.push(...args.slice(i + 1))
+      positionals.push(...args.slice(i + 1))
       break
     }
     if (!raw.startsWith('-') || raw === '-') {
-      options.positionals.push(raw)
+      positionals.push(raw)
       continue
     }
     const eq = raw.indexOf('=')
     const name = eq === -1 ? raw : raw.slice(0, eq)
-    if (VALUE_FLAGS.includes(name)) {
+    const takesValue = name in SETTING_FLAGS || CONTROL_VALUE_FLAGS.includes(name)
+    if (takesValue) {
       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
+      const key = SETTING_FLAGS[name]
+      if (!key) control[camel(name)] = value
+      else if (key === 'hide') settings.hide = [...(settings.hide ?? []), value]
+      else if (key === 'out') settings.out = resolve(cwd, value)
+      else if (NUMBER_SETTINGS.includes(key)) {
+        const number = Number(value)
+        if (!Number.isFinite(number)) throw new UsageError(`\`${name}\` needs a number.`)
+        settings[key] = number
+      } else settings[key] = value
+    } else if (CONTROL_BOOLEAN_FLAGS.includes(name)) {
+      control[camel(name)] = true
     } else if (!GLOBAL_FLAGS.includes(name)) {
       const suggestion = didYouMean(name, ALL_FLAGS)
       throw new UsageError(
@@ -90,35 +136,41 @@ export function parseSnapshotArgs(args = []) {
     }
   }
 
-  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 (control.dev && control.url) throw new UsageError('Pass `--dev` or `--url`, not both.')
+  if (settings.gap !== undefined && settings.overlap !== undefined) {
+    throw new UsageError('Pass `--gap` or `--overlap`, not both.')
   }
-  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 (control.compare && control.save) {
+    throw new UsageError('`--save` keeps the look of a snapshot; choose a look from the sheet, then save that.')
   }
-  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 { settings, control, positionals }
+}
+
+/**
+ * The package's options for a set of settings. `size` is the one setting whose
+ * shape the package does not take as written.
+ */
+export function libraryOptions({ size, out, scale, quality, ...rest }) {
+  const options = { ...rest }
+  if (size !== undefined) {
+    const match = /^(\d+)x(\d+)$/.exec(String(size))
+    if (!match) throw new UsageError('`size` is WIDTHxHEIGHT, e.g. 1600x1000.')
+    options.canvas = { width: Number(match[1]), height: Number(match[2]) }
   }
+  if (scale !== undefined) options.scale = Number(scale)
+  if (quality !== undefined) options.quality = Number(quality)
+  if (out !== undefined) options.output = out
   return options
 }
 
+/** A variant's changes as the flags that apply them; `current` for none. */
+export function flagsFor(changes) {
+  const parts = Object.entries(changes)
+    .filter(([, value]) => value !== undefined)
+    .map(([key, value]) => `--${key} ${value}`)
+  return parts.length ? parts.join(' ') : 'current'
+}
+
 /**
  * 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.
@@ -172,14 +224,14 @@ async function loadSnapshotPackage(dirs) {
   }
 }
 
-function installHint(rootDir) {
+function installHint(rootDir, command = 'add') {
   switch (detectWorkspacePm(rootDir)) {
     case 'npm':
-      return 'npm install --save-dev @uniweb/snapshot'
+      return 'npm install --save-dev @uniweb/snapshot@latest'
     case 'yarn':
-      return 'yarn add --dev -W @uniweb/snapshot'
+      return `yarn ${command} --dev -W @uniweb/snapshot@latest`
     default:
-      return 'pnpm add -D -w @uniweb/snapshot'
+      return `pnpm ${command} -D -w @uniweb/snapshot@latest`
   }
 }
 
@@ -224,35 +276,59 @@ function fail(message, ...details) {
 }
 
 export async function snapshot(args = []) {
-  let options
+  const cwd = process.cwd()
+  let parsed
   try {
-    options = parseSnapshotArgs(args)
+    parsed = parseSnapshotArgs(args, cwd)
   } catch (err) {
     if (!(err instanceof UsageError)) throw err
     fail(err.message, 'Run `uniweb snapshot --help` for the accepted flags.')
   }
+  const { settings: flagSettings, control, positionals } = parsed
 
-  const cwd = process.cwd()
   const rootDir = findWorkspaceRoot(cwd)
   const sites = rootDir ? await discoverSites(rootDir).catch(() => []) : []
-  const requested = options.site ?? options.positionals[0] ?? null
+  const requested = control.site ?? 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) {
+  if (!site && !control.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 (!site && !flagSettings.out) {
+    fail('`--out <file>` is needed outside a site: there is no site folder to write to.')
   }
+  if (!site && control.save) fail(`\`--save\` writes ${SETTINGS_FILE} into a site, and there is none here.`)
   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)
+
+  // The site's saved look, under this run's flags. For a comparison, the file's
+  // `out` names the preview image, not the sheet.
+  let fileSettings = {}
+  if (siteDir) {
+    try {
+      fileSettings = readSnapshotSettings(siteDir).settings
+    } catch (err) {
+      if (!(err instanceof SettingsError)) throw err
+      fail(err.message)
+    }
+  }
+  const base = { ...fileSettings }
+  if (control.compare) delete base.out
+  const merged = mergeSettings(base, flagSettings)
+  let options
+  try {
+    options = libraryOptions(merged)
+  } catch (err) {
+    if (!(err instanceof UsageError)) throw err
+    fail(err.message)
+  }
+  options.output ??= join(siteDir, control.compare ? COMPARE_OUTPUT : DEFAULT_OUTPUT)
 
   const lib = await loadSnapshotPackage([siteDir, rootDir])
   if (!lib) {
@@ -262,18 +338,33 @@ export async function snapshot(args = []) {
       `  ${CYAN}${installHint(rootDir)}${RESET}`
     )
   }
+  const chosesLook = LOOK_SETTINGS.some((key) => options[key] !== undefined)
+  if ((control.compare || chosesLook) && typeof lib.compare !== 'function') {
+    fail(
+      'The installed `@uniweb/snapshot` predates looks and comparisons.',
+      'Update it:',
+      `  ${CYAN}${installHint(rootDir)}${RESET}`
+    )
+  }
+  if (typeof lib.normalizeOptions === 'function') {
+    try {
+      lib.normalizeOptions(options)
+    } catch (err) {
+      fail(err.message, `Check the flags${Object.keys(fileSettings).length ? ` and ${SETTINGS_FILE}` : ''}.`)
+    }
+  }
 
   // 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) {
+    if (control.url) {
+      source = { url: control.url, label: control.url, close: async () => {} }
+    } else if (control.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) {
+      if (!control.noBuild) {
         console.error(`${DIM}→ building ${site.name}${RESET}`)
         await runBuild(siteDir)
       }
@@ -288,40 +379,52 @@ export async function snapshot(args = []) {
     fail(err.message)
   }
 
+  const 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}`)
+  }
+
   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}`)
-      },
-    })
+    result = control.compare
+      ? await lib.compare({ ...options, url: source.url, label: flagsFor, onStep })
+      : await lib.snapshot({ ...options, url: source.url, onStep })
   } catch (err) {
     await source.close().catch(() => {})
     fail(err.message)
   }
   await source.close()
 
-  const shown = relative(cwd, output) || output
+  const shown = relative(cwd, options.output) || options.output
+
+  if (control.compare) {
+    console.log(
+      `${GREEN}✓${RESET} ${shown} ${DIM}(${result.width}×${result.height}, ${result.variants.length} looks from one capture)${RESET}`
+    )
+    result.variants.forEach((variant, i) => {
+      console.log(`  ${String(i + 1).padStart(2)}  ${i === 0 ? `${DIM}current${RESET}` : `${CYAN}${variant.label}${RESET}`}`)
+    })
+    console.log(`  ${DIM}Take one with its flags, and add --save to keep it: uniweb snapshot ${result.variants[1]?.label ?? ''} --save${RESET}`)
+    return
+  }
+
   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
+  if (control.save) {
+    const { saved } = saveSnapshotSettings(siteDir, flagSettings, fileSettings)
+    const where = relative(cwd, join(siteDir, SETTINGS_FILE))
+    if (saved.length) console.log(`  ${where}: ${CYAN}saved ${saved.join(', ')}${RESET}`)
+    else console.log(`  ${DIM}${where}: nothing to save — pass the flags you want to keep.${RESET}`)
+  }
+
+  if (!siteDir || control.noSetPreview) return
 
-  const value = previewValueFor(siteDir, output)
+  const value = previewValueFor(siteDir, options.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}`)

package/src/framework-index.json

@@ -1,16 +1,16 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-09-17T03:53:59.364Z",
+  "generatedAt": "2026-09-18T05:17:28.321Z",
   "packages": {
     "@uniweb/api": {
-      "version": "0.3.6",
+      "version": "0.3.7",
       "path": "framework/api",
       "deps": [
         "@uniweb/core"
       ]
     },
     "@uniweb/build": {
-      "version": "0.52.6",
+      "version": "0.52.7",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -111,7 +111,7 @@
       "deps": []
     },
     "@uniweb/snapshot": {
-      "version": "0.1.1",
+      "version": "0.1.2",
       "path": "framework/snapshot",
       "deps": []
     },

package/src/index.js

@@ -1494,6 +1494,7 @@ ${colors.cyan}${colors.bright}uniweb snapshot${colors.reset} ${colors.dim}— Co
 
 ${colors.bright}Usage:${colors.reset}
   uniweb snapshot [<site>] [options]
+  uniweb snapshot --compare [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
@@ -1501,8 +1502,8 @@ 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.
+beside 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.
@@ -1513,11 +1514,23 @@ ${colors.bright}Where the site comes from:${colors.reset}
   --dev               Capture the site's Vite dev server (no build)
   --url <address>     Capture a site that is already running
 
+${colors.bright}The look:${colors.reset}
+  --layout <name>     auto (default), split, device
+  --gap <px>          Space between the two frames (split default: 48)
+  --overlap <px>      Overlap them instead (device default: 31)
+  --strip <width>     split: fit (default), or 1:N — narrower shows more of a long page
+  --side <side>       Where the strip or phone goes: right (default), left
+  --frame <style>     browser (default, with a title bar), plain
+  --tone <name>       Background: auto (default), light, deep
+
+${colors.bright}Choosing and keeping a look:${colors.reset}
+  --compare           One capture, several looks on one sheet, each captioned with
+                      its flags (site/.uniweb/snapshot/compare.webp)
+  --save              Keep this run's flags in site/snapshot.yml, the site's defaults
+
 ${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)

package/src/utils/code-upload.js

@@ -7,10 +7,12 @@
  *
  *   1. PLAN   — POST {apiBase}/dev/registry/code-uploads with the file list
  *               ({ path, content_type, size, sha256? }). The response carries
- *               one upload target per file ({ path, method, url, headers })
- *               plus mode: 'direct' (dev — URLs point back at the backend) or
- *               'presigned' (prod — storage PUTs; bytes never transit the
- *               backend). The CLI never branches on the mode.
+ *               one entry per file: `present: true` for a file the backend
+ *               already stores for this version (no URL — it is skipped), or an
+ *               upload target ({ path, method, url, headers }). Plus mode:
+ *               'direct' (dev — URLs point back at the backend) or 'presigned'
+ *               (prod — storage PUTs; bytes never transit the backend). The CLI
+ *               never branches on the mode.
  *   2. UPLOAD — PUT each file's raw bytes to its URL with the given headers.
  *               The ENTRY uploads LAST: a partial upload never yields a
  *               loadable version (practical atomicity — there is no server
@@ -35,7 +37,8 @@
  *     plan step's per-version file cap — the cap is an abuse guard, the maps
  *     simply don't belong on the CDN.)
  *   - a registered version is immutable, code included — changed bytes mean
- *     a new version (re-PUTting identical bytes is a safe no-op)
+ *     a new version. A stored file is never re-sent (the plan marks it
+ *     `present`), and one declared at a different size is refused (422)
  */
 
 import { createHash } from 'node:crypto'
@@ -215,7 +218,10 @@ export function computeFoundationDigest(distDir) {
  * @param {string} opts.distDir  - the built dist/ directory
  * @param {Array}  [opts.files]  - pre-collected file list (default: collect)
  * @param {(msg: string) => void} [opts.onProgress]
- * @returns {Promise<{ mode: string, uploaded: string[], failed: Array<{path, status, detail}>, verified: boolean|null, serveBase: string|null }>}
+ * @returns {Promise<{ mode: string, uploaded: string[], stored: string[], failed: Array<{path, status, detail}>, verified: boolean|null, serveBase: string|null }>}
+ *   `stored` — files the plan reported as already stored (`present: true`), not re-sent.
+ * @throws {Error} when the plan is refused — with `status`, and the problem+json
+ *   `detail` and `code` when the body carries them
  */
 export async function uploadFoundationCode({
   apiBase,
@@ -259,10 +265,22 @@ export async function uploadFoundationCode({
   })
   if (!planRes.ok) {
     const body = await planRes.text().catch(() => '')
+    // A refusal is problem+json, and its `detail` is a sentence written for the
+    // person reading — for a changed file it says what to do. Carry it (and the
+    // `code`) instead of a raw body the reader has to dig the sentence out of.
+    let problem = null
+    try {
+      problem = JSON.parse(body)
+    } catch {
+      problem = null
+    }
+    const detail = typeof problem?.detail === 'string' ? problem.detail : null
     const err = new Error(
-      `code-uploads plan rejected: HTTP ${planRes.status}${body ? ` — ${body.slice(0, 300)}` : ''}`
+      `code-uploads plan rejected: HTTP ${planRes.status}${detail ? ` — ${detail}` : body ? ` — ${body.slice(0, 300)}` : ''}`
     )
     err.status = planRes.status
+    err.detail = detail
+    err.code = typeof problem?.code === 'string' ? problem.code : null
     throw err
   }
   const plan = await planRes.json()
@@ -275,6 +293,7 @@ export async function uploadFoundationCode({
     plan.mode === 'direct' ? { Authorization: `Bearer ${token}` } : {}
 
   const uploaded = []
+  const stored = []
   const failed = []
   for (const file of uploadOrder(list)) {
     const target = targets.get(file.path)
@@ -286,6 +305,27 @@ export async function uploadFoundationCode({
       })
       continue
     }
+    // ⭐ A file the backend already stores for this version comes back
+    // `present: true`, with no URL — a stored file of a registered version is
+    // never overwritten. Skip it. This is what lets an interrupted upload
+    // resume, and a re-run on a fully uploaded version pass.
+    //
+    // ⛔ Before this branch existed, a present entry was PUT to
+    // `new URL(undefined, origin)`, which does not throw — it resolves to
+    // `<origin>/undefined` — and came back as a failed upload.
+    if (target.present === true) {
+      stored.push(file.path)
+      onProgress(`${file.path} (already stored)`)
+      continue
+    }
+    if (!target.url) {
+      failed.push({
+        path: file.path,
+        status: 0,
+        detail: 'the plan gave no upload URL'
+      })
+      continue
+    }
     const bytes = readFileSync(join(distDir, file.path))
     try {
       // ⭐ **Retried.** A single connection-level failure used to fail the whole
@@ -350,5 +390,5 @@ export async function uploadFoundationCode({
     }
   }
 
-  return { mode: plan.mode || 'direct', uploaded, failed, verified, serveBase }
+  return { mode: plan.mode || 'direct', uploaded, stored, failed, verified, serveBase }
 }

package/src/utils/semver-precedence.js

@@ -0,0 +1,57 @@
+/**
+ * SemVer 2.0.0 precedence — how a registry orders a foundation's versions.
+ *
+ * A pre-release sorts below its release (`1.0.0-rc.1` < `1.0.0`), and build
+ * metadata carries no order (`1.2.0+b` equals `1.2.0`).
+ *
+ * ⚖️ Not `compareSemver` in `dep-survey.js`: that one reads dependency specs
+ * (`^1.2.3`) for `uniweb update` and compares major.minor.patch only. This one
+ * is strict — anything that is not a SemVer version is `null`, never a guess.
+ */
+
+// The regex published with the SemVer 2.0.0 specification (semver.org, §FAQ).
+const SEMVER =
+  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/
+
+/**
+ * @param {unknown} version
+ * @returns {{ major: number, minor: number, patch: number, pre: string[] }|null}
+ */
+export function parseSemver(version) {
+  if (typeof version !== 'string') return null
+  const m = SEMVER.exec(version)
+  if (!m) return null
+  return { major: +m[1], minor: +m[2], patch: +m[3], pre: m[4] ? m[4].split('.') : [] }
+}
+
+/**
+ * @param {string} a
+ * @param {string} b
+ * @returns {-1|0|1|null} how `a` sorts against `b`; null when either is not SemVer
+ */
+export function compareSemverPrecedence(a, b) {
+  const x = parseSemver(a)
+  const y = parseSemver(b)
+  if (!x || !y) return null
+  for (const part of ['major', 'minor', 'patch']) {
+    if (x[part] !== y[part]) return x[part] > y[part] ? 1 : -1
+  }
+  // A version with a pre-release sorts below the same version without one.
+  if (!x.pre.length || !y.pre.length) {
+    return x.pre.length === y.pre.length ? 0 : x.pre.length ? -1 : 1
+  }
+  for (let i = 0; i < Math.max(x.pre.length, y.pre.length); i++) {
+    const p = x.pre[i]
+    const q = y.pre[i]
+    if (p === undefined) return -1
+    if (q === undefined) return 1
+    if (p === q) continue
+    const pNum = /^\d+$/.test(p)
+    const qNum = /^\d+$/.test(q)
+    // Numeric identifiers compare numerically and sort below alphanumeric ones.
+    if (pNum && qNum) return BigInt(p) > BigInt(q) ? 1 : -1
+    if (pNum !== qNum) return pNum ? -1 : 1
+    return p > q ? 1 : -1
+  }
+  return 0
+}

package/src/utils/snapshot-settings.js

@@ -0,0 +1,112 @@
+/**
+ * `site/snapshot.yml` — how `uniweb snapshot` composes a site's preview image,
+ * kept with the site so the next run reproduces the same look.
+ *
+ * It is the command's defaults for this site, and flags override it. Nothing else
+ * reads it: the build, `push` and `pull` all leave a site's root files alone
+ * unless they name them.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { isAbsolute, join, relative, resolve, sep } from 'node:path'
+import yaml from 'js-yaml'
+
+import { didYouMean } from './args.js'
+
+export const SETTINGS_FILE = 'snapshot.yml'
+
+/** In the order they are written. */
+export const SETTING_KEYS = [
+  'route',
+  'layout',
+  'tone',
+  'gap',
+  'overlap',
+  'strip',
+  'side',
+  'frame',
+  'size',
+  'scale',
+  'quality',
+  'hide',
+  'out'
+]
+
+const HEADER = [
+  '# How `uniweb snapshot` composes this site\'s preview image.',
+  '# Flags override these; `uniweb snapshot <flags> --save` writes them here.',
+  ''
+].join('\n')
+
+export class SettingsError extends Error {}
+
+/**
+ * The settings in `<siteDir>/snapshot.yml`, or `{}` when there is none. `out` comes
+ * back absolute, resolved against the site folder.
+ */
+export function readSnapshotSettings(siteDir) {
+  const file = join(siteDir, SETTINGS_FILE)
+  if (!existsSync(file)) return { file, settings: {} }
+
+  let data
+  try {
+    data = yaml.load(readFileSync(file, 'utf8'))
+  } catch (err) {
+    throw new SettingsError(`${SETTINGS_FILE} is not valid YAML: ${err.message.split('\n')[0]}`)
+  }
+  if (data === undefined || data === null) return { file, settings: {} }
+  if (typeof data !== 'object' || Array.isArray(data)) {
+    throw new SettingsError(`${SETTINGS_FILE} should be a list of settings, like \`gap: 48\`.`)
+  }
+
+  const settings = {}
+  for (const [key, value] of Object.entries(data)) {
+    if (!SETTING_KEYS.includes(key)) {
+      const suggestion = didYouMean(key, SETTING_KEYS)
+      throw new SettingsError(
+        `${SETTINGS_FILE} has an unknown setting \`${key}\`.` + (suggestion ? ` Did you mean \`${suggestion}\`?` : '')
+      )
+    }
+    if (value === null || value === undefined) continue
+    if (key === 'hide') settings.hide = Array.isArray(value) ? value.map(String) : [String(value)]
+    else if (key === 'out') settings.out = resolve(siteDir, String(value))
+    else settings[key] = value
+  }
+  return { file, settings }
+}
+
+/** Flags over the file. A gap or an overlap from the flags replaces either from the file. */
+export function mergeSettings(fromFile = {}, fromFlags = {}) {
+  const merged = { ...fromFile }
+  if (fromFlags.gap !== undefined || fromFlags.overlap !== undefined) {
+    delete merged.gap
+    delete merged.overlap
+  }
+  for (const [key, value] of Object.entries(fromFlags)) {
+    if (value !== undefined) merged[key] = value
+  }
+  return merged
+}
+
+/**
+ * Write the flags of this run into `<siteDir>/snapshot.yml`, over what it already
+ * holds. The file is rewritten in full, in `SETTING_KEYS` order, under a header.
+ *
+ * @returns {{ file: string, saved: string[] }} the keys this run set
+ */
+export function saveSnapshotSettings(siteDir, fromFlags, fromFile = readSnapshotSettings(siteDir).settings) {
+  const file = join(siteDir, SETTINGS_FILE)
+  const merged = mergeSettings(fromFile, fromFlags)
+  const ordered = {}
+  for (const key of SETTING_KEYS) {
+    if (merged[key] === undefined) continue
+    ordered[key] = key === 'out' ? toSitePath(siteDir, merged.out) : merged[key]
+  }
+  writeFileSync(file, HEADER + yaml.dump(ordered, { lineWidth: -1 }))
+  return { file, saved: SETTING_KEYS.filter((key) => fromFlags[key] !== undefined) }
+}
+
+function toSitePath(siteDir, path) {
+  const rel = relative(siteDir, path)
+  return isAbsolute(rel) ? path : rel.split(sep).join('/')
+}