@uniweb/build 1.10.0 → 1.10.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "1.10.0",
+  "version": "1.10.2",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -57,14 +57,14 @@
     "sharp": "^0.35.5",
     "yaml": "^2.5.0",
     "@uniweb/content-reader": "~1.5.7",
-    "@uniweb/content-writer": "~1.3.1",
-    "@uniweb/projections": "~1.2.0",
-    "@uniweb/theming": "~1.2.1",
+    "@uniweb/projections": "~1.2.1",
+    "@uniweb/semantic-parser": "~1.13.0",
     "@uniweb/schemas": "~1.6.5",
-    "@uniweb/semantic-parser": "~1.13.0"
+    "@uniweb/theming": "~1.2.1",
+    "@uniweb/content-writer": "~1.3.1"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "~1.2.2"
+    "@uniweb/runtime": "~1.2.3"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -73,8 +73,8 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/runtime": "~1.2.2",
-    "@uniweb/core": "~1.4.6"
+    "@uniweb/core": "~1.4.7",
+    "@uniweb/runtime": "~1.2.3"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/prerender.js

@@ -34,7 +34,7 @@ import { getAdapter } from './hosts/index.js'
 import { detectCiContext } from './hosts/detect-ci-context.js'
 import { stripBasePath } from './site/extension-urls.js'
 import { isSiteRelative, resolveExtensionDist } from './site/emit-extensions.js'
-import { crawlerFiles, sitemapEntry } from './site/seo-files.js'
+import { crawlerFiles, sitemapEntriesOf } from './site/seo-files.js'
 import { absoluteUrl } from '@uniweb/core/site-address'
 
 /**
@@ -879,7 +879,7 @@ export async function prerenderSite(siteDir, options = {}) {
 
   // Pre-render each locale
   const renderedFiles = []
-  // Each written page's sitemap entry, every locale's: the sitemap lists what this build serves.
+  // Each locale's sitemap entries, for the pages it wrote: the sitemap lists what this build serves.
   const sitemapEntries = []
   // A redirect stub names its target as the target's own pages do: absolutely, on the site's address.
   const stubCanonical = (target) => absoluteUrl(defaultSiteContent.config?.url, target) || target
@@ -908,6 +908,10 @@ export async function prerenderSite(siteDir, options = {}) {
     // Store fetchedData on siteContent for runtime DataStore pre-population
     siteContent.fetchedData = fetchedData
 
+    // The pages as authored, each parametric page its template: what the sitemap reads, with the
+    // record pages written from it (`./site/seo-files.js`).
+    const authoredPages = siteContent.pages
+
     // Expand dynamic pages (e.g., /blog/:slug → /blog/post-1, /blog/post-2)
     if (siteContent.pages?.some(p => p.isDynamic)) {
       onProgress('Expanding dynamic routes...')
@@ -998,7 +1002,9 @@ export async function prerenderSite(siteDir, options = {}) {
      * ⭐ A PAGE RENDERS AGAINST WHAT IT CARRIES — the entries its HTML embeds, which are all the
      * browser's store holds when it boots on that page (`initUniweb` hydrates from them). The
      * browser renders over the prerendered page, so a render that reads more paints content the
-     * browser does not have, and the browser replaces it with a loading state at boot.
+     * browser does not have, and the browser replaces it with a loading state at boot. Each page
+     * hands them to `renderer.render` as `fetchedData`, as a host's isolate does; the 404 page,
+     * rendered on its own below, holds them the same way.
      *
      * ⛔ Until 2026-10-25 the store was hydrated once for the whole locale and then took every
      * page's answers in turn, so a page could render data that only other pages carried. A
@@ -1007,11 +1013,9 @@ export async function prerenderSite(siteDir, options = {}) {
      * the record pages before it had fetched, carried none of them, and showed "loading…" at
      * boot (measured).
      */
-    const holdOnly = (carried) => {
-      website.dataStore.clear()
-      hydrateDataStore(website, carried)
-    }
 
+    // The route of each page written, as its head states it (`Page#getNavRoute`).
+    const written = new Set()
     for (const page of website.pages) {
       // Skip dynamic template pages — they exist in the content for runtime
       // route matching but can't be pre-rendered (no concrete route)
@@ -1109,7 +1113,7 @@ export async function prerenderSite(siteDir, options = {}) {
       const scopeRoutes = new Set([page.route, page.parent?.route, page.dynamicContext?.templateRoute].filter(Boolean))
       // The same call `injectBuildData` makes below for this page's HTML, so the render holds what
       // the HTML embeds — the page's own data step's answers among them.
-      holdOnly(scopeFetchedData(siteContent.fetchedData, splitContent ? scopeRoutes : null, page.route))
+      const carried = scopeFetchedData(siteContent.fetchedData, splitContent ? scopeRoutes : null, page.route)
 
       onProgress(`Rendering ${outputRoute}...`)
 
@@ -1120,7 +1124,7 @@ export async function prerenderSite(siteDir, options = {}) {
       // is how the two lanes drift. This lane passes the Page it already holds; the
       // isolate passes a route. See `runtime/src/page-renderer.js` for what it leaves
       // to the host.
-      const result = renderer.render(page)
+      const result = renderer.render(page, { fetchedData: carried })
 
       if (result.outcome === 'failed') {
         const { type, message } = result.error
@@ -1165,10 +1169,15 @@ export async function prerenderSite(siteDir, options = {}) {
       renderedFiles.push(outputPath)
       onProgress(`  → ${outputPath.replace(distDir, 'dist')}`)
       // The page whose head was written — a content-less folder renders its index child.
-      const entry = sitemapEntry(result.page || page)
-      if (entry) sitemapEntries.push(entry)
+      written.add((result.page || page).getNavRoute())
     }
 
+    sitemapEntries.push(...sitemapEntriesOf({ ...siteContent, pages: authoredPages }, {
+      locale,
+      records: (siteContent.pages || []).filter((page) => page.dynamicContext),
+      written,
+    }))
+
     // Write 404.html — shared logic from @uniweb/runtime/ssr
     const fallbackBaseHtml = injectBuildData(htmlShell, siteContent, {
       splitContent,
@@ -1176,7 +1185,8 @@ export async function prerenderSite(siteDir, options = {}) {
       scopeRoutes: new Set(),  // SPA fallback carries site-level fetched data only
     })
     // The 404 page renders against what 404.html carries, as every page above does.
-    holdOnly(scopeFetchedData(siteContent.fetchedData, splitContent ? new Set() : null, null))
+    website.forgetData()
+    hydrateDataStore(website, scopeFetchedData(siteContent.fetchedData, splitContent ? new Set() : null, null))
     const { html: notFoundHtml, hasNotFoundPage } = generate404Html({
       baseHtml: fallbackBaseHtml,
       website,
@@ -1213,12 +1223,7 @@ export async function prerenderSite(siteDir, options = {}) {
 
   // ⭐ The crawler files, from the pages just written (`./site/seo-files.js`). A site's own
   // `public/robots.txt` or `public/sitemap.xml` is its author's, and is left as it is.
-  const crawl = crawlerFiles({
-    address: defaultSiteContent.config?.url || null,
-    base: defaultSiteContent.config?.base || '/',
-    entries: sitemapEntries,
-    robots: defaultSiteContent.config?.seo?.robots,
-  })
+  const crawl = crawlerFiles({ content: defaultSiteContent, entries: sitemapEntries })
   for (const [file, body] of [['sitemap.xml', crawl.sitemap], ['robots.txt', crawl.robots]]) {
     if (!body) continue
     if (existsSync(join(siteDir, 'public', file))) {

package/src/site/seo-files.js

@@ -1,171 +1,56 @@
 /**
  * `sitemap.xml` and `robots.txt` — the two files a crawler reads about a statically served site,
- * written by the prerender from the pages it wrote.
+ * written by the prerender once it has written the pages.
  *
- * ⭐ THE SITEMAP LISTS THE PAGES A STATIC HOST WILL ANSWER WITH, BY THE URLS THEY STATE. An entry is
- * a page the prerender wrote — the static ones and each record's own — at its canonical URL with its
- * alternates, read off `Page#getHeadMeta`, the source its `<head>` was written from, so the sitemap
- * and the page cannot disagree. ⛔ Until 2026-10-25 the plugin wrote it at bundle time, before
- * parametric pages were expanded: it listed `/books/:slug` and no book, at URLs that left the base
- * path out.
+ * ⭐ BOTH ARE `@uniweb/projections`', made from the site's content alone (`sitemapEntries`,
+ * `renderSitemap`, `renderRobotsTxt`), so a host serving the site from its content serves the same
+ * files. A page's entry is the canonical and the alternates its `<head>` states, by the rules
+ * `Page#getHeadMeta` states them with (guarded by projections' `tests/sitemap-heads.test.js`).
+ * ⛔ Until 2026-10-25 the build read each entry off the rendered page instead, and until earlier
+ * that day the plugin wrote the sitemap at bundle time, before parametric pages were expanded: it
+ * listed `/books/:slug` and no book, at URLs that left the base path out.
  *
- * ⭐ `robots.txt` IS READ ONLY AT A HOST'S ROOT. A site served under a base path — a GitHub project
- * site — cannot have one; it is not written there, and the build says so, rather than shipping a file
- * no crawler reads that points at a sitemap where none is.
- */
-
-/** The three defined Content Signals, in the order they are emitted. */
-const CONTENT_SIGNAL_KEYS = ['search', 'ai-input', 'ai-train']
-
-/**
- * Format the `Content-Signal:` directive from `seo.robots.contentSignals`.
- *
- * Content Signals express what a site permits its content to be *used for*,
- * which is a different axis from `Disallow:` — that governs fetching, this
- * governs use after fetching. The three defined signals:
- *
- * - `search`    — appear in search results
- * - `ai-input`  — be retrieved at inference time (RAG, grounding)
- * - `ai-train`  — be used to train a model
- *
- * **Emitted only when declared.** There is no default: a preference the site
- * owner did not state is not ours to assert, in either direction. An absent
- * signal means "unstated", which is not the same as `no`.
- *
- * Unknown keys are ignored rather than passed through — the vocabulary is a
- * closed set, and forwarding an invented signal would produce a directive no
- * crawler honors while reading as though it were doing something.
- *
- * @param {Object|null} signals - e.g. `{ search: true, 'ai-input': true, 'ai-train': false }`
- * @returns {string} The directive line, or `''` when nothing is declared
- */
-export function formatContentSignals(signals) {
-  if (!signals || typeof signals !== 'object') return ''
-
-  const parts = []
-  for (const key of CONTENT_SIGNAL_KEYS) {
-    if (!(key in signals)) continue
-    const value = signals[key]
-    const yes = value === true || value === 'yes'
-    const no = value === false || value === 'no'
-    if (!yes && !no) continue
-    parts.push(`${key}=${yes ? 'yes' : 'no'}`)
-  }
-
-  return parts.length ? `Content-Signal: ${parts.join(', ')}` : ''
-}
-
-/**
- * `robots.txt` — the site's rules, and where its sitemap is.
+ * ⭐ THE SITEMAP LISTS THE PAGES A STATIC HOST WILL ANSWER WITH: the pages this build wrote, each
+ * record's own among them. A page it wrote no file for — one whose render failed — is answered with
+ * the not-found page, so it is left out, where a host that renders on request lists it.
  *
- * @param {Object} [robots] - `seo.robots`: `allow`, `disallow`, `crawlDelay`, `additionalSitemaps`,
- *   `contentSignals`
- * @param {Object} [options]
- * @param {string|null} [options.sitemap] - the sitemap's absolute URL, when there is one
- * @returns {string}
+ * ⭐ A site served under a base path — a GitHub project site — gets no `robots.txt`, since a crawler
+ * reads it only at a host's root, and the build says so.
  */
-export function generateRobotsTxt(robots = {}, { sitemap = null } = {}) {
-  const { disallow = [], allow = [], crawlDelay = null, additionalSitemaps = [], contentSignals = null } = robots || {}
 
-  let content = 'User-agent: *\n'
-
-  const signals = formatContentSignals(contentSignals)
-  if (signals) {
-    // Inside the User-agent group, before the rules — the directive applies to
-    // the group it sits in.
-    content += `${signals}\n`
-  }
-  for (const path of allow) content += `Allow: ${path}\n`
-  for (const path of disallow) content += `Disallow: ${path}\n`
-  if (crawlDelay) content += `Crawl-delay: ${crawlDelay}\n`
-
-  const sitemaps = [sitemap, ...additionalSitemaps].filter(Boolean)
-  if (sitemaps.length) content += `\n${sitemaps.map((url) => `Sitemap: ${url}`).join('\n')}\n`
-  return content
-}
-
-/** Whether `seo.robots` says anything a crawler would act on. */
-function hasRules(robots) {
-  if (!robots || typeof robots !== 'object') return false
-  return Boolean(
-    robots.allow?.length ||
-      robots.disallow?.length ||
-      robots.crawlDelay ||
-      robots.additionalSitemaps?.length ||
-      formatContentSignals(robots.contentSignals)
-  )
-}
-
-/**
- * A rendered page's sitemap entry — its canonical URL, with its alternates — or null when it is not
- * one to list: kept out of search (`noindex`), naming another URL as its canonical, or on a site
- * whose address is unknown.
- *
- * @param {Object} page - a Page of the Website the prerender rendered it from
- * @returns {{ loc: string, alternates: Array, lastmod: string|null, changefreq: string|null, priority: (string|number)|null }|null}
- */
-export function sitemapEntry(page) {
-  const meta = page?.getHeadMeta?.()
-  if (!meta?.canonical || meta.robots?.includes('noindex')) return null
-  const own = page.website?.getPageUrl?.(page)
-  if (!own || meta.canonical !== own) return null
-  return {
-    loc: own,
-    alternates: meta.alternates || [],
-    // A record's page has no file of its own, so no date of its own: none is better than its template's.
-    lastmod: !page.dynamicContext && page.lastModified ? String(page.lastModified).split('T')[0] : null,
-    changefreq: page.seo?.changefreq || null,
-    priority: page.seo?.priority ?? null,
-  }
-}
-
-/** Escape a value for XML text or a double-quoted attribute. */
-function escapeXml(str) {
-  return String(str)
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;')
-    .replace(/'/g, '&apos;')
-}
+import { renderRobotsTxt, renderSitemap, sitemapEntries } from '@uniweb/projections'
 
 /**
- * `sitemap.xml` for entries (`sitemapEntry`), each with its alternates when the site has several
- * locales.
+ * One language's sitemap entries, for the pages this build wrote: `sitemapEntries` for its content
+ * and its record pages, less any page the build wrote no file for.
  *
- * @param {Array} entries
- * @returns {string}
+ * @param {Object} content - the language's content, as authored: each parametric page its template
+ * @param {Object} options
+ * @param {string} options.locale - the language
+ * @param {Object[]} [options.records] - its record pages, as expanded (`expandDynamicPages`)
+ * @param {Set<string>} options.written - the route of each page written, as its head states it
+ *   (`Page#getNavRoute`)
+ * @returns {Array} `sitemapEntries` results
  */
-export function renderSitemap(entries) {
-  const alternated = entries.some((entry) => entry.alternates?.length)
-  const urls = entries.map((entry) => {
-    const lines = [`    <loc>${escapeXml(entry.loc)}</loc>`]
-    if (entry.lastmod) lines.push(`    <lastmod>${escapeXml(entry.lastmod)}</lastmod>`)
-    if (entry.changefreq) lines.push(`    <changefreq>${escapeXml(entry.changefreq)}</changefreq>`)
-    if (entry.priority !== null && entry.priority !== undefined) lines.push(`    <priority>${escapeXml(entry.priority)}</priority>`)
-    for (const { hreflang, url } of entry.alternates || []) {
-      lines.push(`    <xhtml:link rel="alternate" hreflang="${escapeXml(hreflang)}" href="${escapeXml(url)}" />`)
-    }
-    return `  <url>\n${lines.join('\n')}\n  </url>`
-  })
-  const xmlns = alternated ? ' xmlns:xhtml="http://www.w3.org/1999/xhtml"' : ''
-  return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"${xmlns}>\n${urls.join('\n')}\n</urlset>\n`
+export function sitemapEntriesOf(content, { locale, records = [], written }) {
+  const entries = sitemapEntries(content, { locale, records: records.map((page) => ({ type: 'record', route: page.route })) })
+  return entries.filter((entry) => written.has(entry.route))
 }
 
 /**
  * The site's crawler files, for what this build serves: the sitemap when the site's address is
- * known and it has pages to list, `robots.txt` when the site is at its host's root and has rules or a
- * sitemap to name.
+ * known and it has pages to list, and `robots.txt` (`renderRobotsTxt`), naming that sitemap.
  *
  * @param {Object} options
- * @param {string|null} options.address - the site's address (`config.url`)
- * @param {string} [options.base] - the base the site is built for
- * @param {Array} options.entries - `sitemapEntry` results
- * @param {Object} [options.robots] - `seo.robots`
+ * @param {Object} options.content - the site's content: its address (`config.url`), the base it is
+ *   built for (`config.base`) and its rules (`config.seo.robots`)
+ * @param {Array} options.entries - every language's entries (`sitemapEntriesOf`)
  * @returns {{ sitemap: string|null, robots: string|null, notes: string[] }} what to write, and why
  *   anything was not
  */
-export function crawlerFiles({ address, base = '/', entries = [], robots = {} }) {
+export function crawlerFiles({ content, entries = [] }) {
+  const config = content?.config || {}
+  const address = config.url || null
   const notes = []
   let sitemap = null
   if (!address) {
@@ -175,16 +60,14 @@ export function crawlerFiles({ address, base = '/', entries = [], robots = {} })
   } else {
     sitemap = renderSitemap(entries)
   }
-  const atRoot = !base || base === '/'
-  const sitemapUrl = sitemap ? new URL('sitemap.xml', address).href : null
-  let robotsTxt = null
-  if (atRoot) {
-    if (sitemapUrl || hasRules(robots)) robotsTxt = generateRobotsTxt(robots, { sitemap: sitemapUrl })
-  } else {
+  const robots = renderRobotsTxt(content, { sitemap: Boolean(sitemap) })
+  const base = config.base || '/'
+  if (base !== '/') {
+    const sitemapUrl = sitemap ? new URL('sitemap.xml', address).href : null
     notes.push(
       `No robots.txt: crawlers read it only at a host's root, and this site is served under ${base}.` +
         (sitemapUrl ? ` Submit ${sitemapUrl} to search engines directly.` : '')
     )
   }
-  return { sitemap, robots: robotsTxt, notes }
+  return { sitemap, robots, notes }
 }

package/src/uwx/backfill.js

@@ -4,13 +4,19 @@
 // `$id` with no `$uuid` on first sync; the backend mints `$uuid` and returns it;
 // this writes it into the record in its source file (docs/reference/entity-content.md).
 //
-// Write-back RE-RENDERS the parsed record with `$uuid` as the leading key, rather
-// than surgically patching the text. It does not preserve comments or incidental
-// formatting (accepted) — in exchange it is one uniform path across YAML, JSON, and
-// markdown frontmatter, and it converges to a fixpoint: a pristine file gains only
-// a `$uuid`, and a no-op re-sync is byte-identical (render(parse(x)) == x once
-// canonical). It reads from the SOURCE file (not the backend's finalized document),
-// so field values round-trip untouched and no inverse decode is needed in v1.
+// ⭐ Write-back ADDS ONE LINE: `$uuid` as the record's leading key, in a YAML file or a
+// markdown file's frontmatter (`yaml-edit.js::setYamlKeyFirst`), and changes nothing else
+// the author wrote — comments, quotes, blank lines, line breaks, `[a, b]` lists. A re-sync
+// with the same `$uuid` is byte-identical. It reads from the SOURCE file (not the backend's
+// finalized document), so field values round-trip untouched. A file that cannot be edited
+// in place (an alias, a flow-style map) is re-rendered whole and the caller is warned; JSON,
+// which holds no comments, is re-rendered as before.
+//
+// ⛔ Until 2026-10-25 every file was re-rendered whole, which the first push of a site's
+// records made into a commit of every record file: on a site's first publish, measured on
+// 16 hand-written records, every comment was deleted, every long line refolded, every
+// `[a, b]` list exploded and every blank line between keys removed — the price of "one
+// uniform path", written down as accepted before `yaml-edit.js` could edit in place.
 //
 // ⛔ A PUSH NEVER RENDERS THE BACKEND'S DOCUMENT OVER THE AUTHOR'S FILE. It did, for
 // a record's first push, from 2026-05-29 to 2026-09-23 ("variant A"), and that
@@ -34,6 +40,7 @@ import yaml from 'js-yaml'
 import { YAML_OPTIONS } from '../utils/yaml-schema.js'
 import { proseMirrorToMarkdown } from '@uniweb/content-writer'
 import { parseFrontmatter } from './entity-source.js'
+import { setYamlKeyFirst } from './yaml-edit.js'
 import { isProseMirrorField, isOpenMapSection, openMapFromRows } from './data-schema.js'
 import { recordFileLayout, contentBodyTarget } from './record-layout.js'
 import { unwrapLocalizedContent } from './locale-sync.js'
@@ -63,13 +70,16 @@ function withUuidFirst(obj, uuid) {
 }
 
 /**
- * Insert `$uuid` into a single-record source file by re-rendering the parsed
- * record with `$uuid` leading. Idempotent — if the render equals the file's
- * current bytes, nothing is written.
+ * Insert `$uuid` into a single-record source file as its leading key, editing nothing else
+ * in a YAML file or a markdown file's frontmatter (`setYamlKeyFirst`): an author's comments,
+ * quotes, blank lines and line breaks stay as written. A file that cannot be edited in place
+ * (an alias, a flow-style map) is re-rendered whole, and the result says so. Idempotent: the
+ * same `$uuid` leaves the file untouched.
  *
  * @param {string} filePath
  * @param {string} uuid
- * @returns {{ status: 'updated'|'unchanged'|'deferred'|'error', message?: string }}
+ * @returns {{ status: 'updated'|'unchanged'|'deferred'|'error', message?: string, warning?: string }}
+ *   `warning` when the file was re-rendered whole
  */
 export function backfillUuid(filePath, uuid) {
   const dot = filePath.lastIndexOf('.')
@@ -83,6 +93,7 @@ export function backfillUuid(filePath, uuid) {
   }
 
   let next
+  let rewritten = false
   if (ext === '.json') {
     let obj
     try {
@@ -104,17 +115,32 @@ export function backfillUuid(filePath, uuid) {
     if (Array.isArray(obj)) {
       return { status: 'deferred', message: 'array-form YAML (many records) not handled in v1' }
     }
-    next = yaml.dump(withUuidFirst(obj && typeof obj === 'object' ? obj : {}, uuid))
+    next = setYamlKeyFirst(text, '$uuid', uuid)
+    if (next === null) {
+      next = yaml.dump(withUuidFirst(obj && typeof obj === 'object' ? obj : {}, uuid))
+      rewritten = true
+    }
   } else if (ext === '.md') {
     const { frontmatter, body } = parseFrontmatter(text, filePath)
-    next = `---\n${yaml.dump(withUuidFirst(frontmatter, uuid))}---\n${body}`
+    // Split as `parseFrontmatter` splits, so the frontmatter edited is the one it reads and
+    // everything around it stays byte for byte.
+    const parts = text.split('---\n')
+    const edited = text.trimStart().startsWith('---') && parts.length >= 3 ? setYamlKeyFirst(parts[1], '$uuid', uuid) : null
+    if (edited !== null) next = [parts[0], edited, ...parts.slice(2)].join('---\n')
+    else {
+      next = `---\n${yaml.dump(withUuidFirst(frontmatter, uuid))}---\n${body}`
+      // A file with no frontmatter gains one, which loses nothing.
+      rewritten = text.trimStart().startsWith('---')
+    }
   } else {
     return { status: 'deferred', message: `${ext || '(no extension)'} back-fill is not yet implemented` }
   }
 
   if (next === text) return { status: 'unchanged' }
   writeFileSync(filePath, next)
-  return { status: 'updated' }
+  return rewritten
+    ? { status: 'updated', warning: 'rewritten whole to record its $uuid — it could not be edited in place, so its comments and layout are gone' }
+    : { status: 'updated' }
 }
 
 /**
@@ -473,6 +499,7 @@ export function backfillEntityUuids({ index, finalized }) {
 
     // The uuid, into the author's own file — never the returned document (header ⛔).
     const res = backfillUuid(entry.sourceFile, uuid)
+    if (res.warning) warnings.push(`${entry.sourceFile}: ${res.warning}`)
     if (res.status === 'updated') updated.push(entry.sourceFile)
     else if (res.status === 'unchanged') unchanged.push(entry.sourceFile)
     else if (res.status === 'deferred') deferred.push({ index: i, id: entry.id, file: entry.sourceFile, reason: res.message })

package/src/uwx/link-records.js

@@ -132,6 +132,7 @@ export function backfillLinkUuids({ links = [], folderDoc }) {
       warnings.push(`${link.sourceFile}: ${res.message}`)
       continue
     }
+    if (res.warning) warnings.push(`${link.sourceFile}: ${res.warning}`)
     if (res.status === 'updated') updated.push(link.sourceFile)
     mapped[item.$uuid] = item.$uuid
   }

package/src/uwx/yaml-edit.js

@@ -289,6 +289,47 @@ export function setYamlKey(text, key, value) {
   return before ? editYamlText(text, before, { ...before, [key]: value }) : null
 }
 
+/**
+ * Set top-level `key` to `value` as the map's FIRST key — a line of its own before the first
+ * key, so after any comments that head the file — editing nothing else. A key already there is
+ * set where it stands (`editYamlText`).
+ *
+ * For an identity a sync writes into a file an author wrote (`$uuid`, `backfill.js`), which leads
+ * a record by convention, as a record a pull writes has it.
+ *
+ * @param {string} text - the file's contents (a record's frontmatter, for a markdown record)
+ * @param {string} key
+ * @param {*} value
+ * @returns {string|null} the new contents; null when the text cannot be edited in place — not a
+ *   block map, an alias or merge key, a parse error, or a result that reads differently
+ */
+export function setYamlKeyFirst(text, key, value) {
+  const before = readMap(text)
+  if (!before) return null
+  if (Object.hasOwn(before, key)) return editYamlText(text, before, { ...before, [key]: value })
+  let doc
+  try {
+    doc = parseDocument(text)
+  } catch {
+    return null
+  }
+  if (doc.errors.length || usesReferences(doc)) return null
+  const line = yaml.dump({ [key]: value }, YAML_DUMP_OPTS)
+  let out
+  if (doc.contents === null || doc.contents === undefined) {
+    // Comments and nothing else: the key goes after them.
+    out = text + (text && !text.endsWith('\n') ? '\n' : '') + line
+  } else {
+    if (!isMap(doc.contents) || doc.contents.flow || !doc.contents.items[0]?.key?.range) return null
+    const first = doc.contents.items[0].key
+    if (columnOf(text, first) !== 0) return null
+    const at = lineStart(text, first.range[0])
+    out = text.slice(0, at) + line + text.slice(at)
+  }
+  const read = readMap(out)
+  return read && sameValue(read, { [key]: value, ...before }) ? out : null
+}
+
 /**
  * Replace entries of the top-level list `key` — each `from` entry becomes its `to` — where
  * they stand, in the quotes they were written in. An entry that only CONTAINS `from` is