@uniweb/build 0.63.4 → 0.64.1

package/src/uwx/site-project.js

@@ -32,6 +32,7 @@
 // we unwrap to the source locale for the file surface (other locales stay in
 // the i18n pipeline). Absent `info` keys are left untouched on disk.
 
+import { foldOpenGraph } from './open-graph.js'
 import { join, relative, extname, basename, dirname } from 'node:path'
 import { restoreAssetRefs } from './asset-map.js'
 import { readBackendState, updateBackendState } from './sync-store.js'
@@ -42,12 +43,19 @@ import yaml from 'js-yaml'
 import { YAML_OPTIONS } from '../utils/yaml-schema.js'
 import { writeSiteConfig, writeThemeFile, writeIfChanged, writeSectionFile, writeMergedYaml } from './project-writer.js'
 import { declarationsToQueriesYml } from './records-project.js'
+import { FILLED_SECTION_TYPE, buildRouteOf } from './site.js'
+import { translationContext, SITE_META_CONTEXT } from '../i18n/extract.js'
 import { authorableDeclaration, DECLARATION_KEYS } from '../site/fetch-shapes.js'
-import { createTranslationCollector, writeLocaleTranslations, writeFreeformTranslations, unwrapLocalizedContent } from './locale-sync.js'
-import { buildFreeformPath } from '../i18n/freeform.js'
+import { createTranslationCollector, writeLocaleTranslations, writeFreeformTranslations, unwrapLocalizedContent, localesDir } from './locale-sync.js'
+import { resolveLocaleList } from '../i18n/locales.js'
+import { buildFreeformPath, freeformPathsFor } from '../i18n/freeform.js'
 import { unwrapLocalized, unwrapLocalizedList } from './backfill.js'
 import { LOCALIZED_FIELD_ASSUMPTION } from './localize.js'
 import { siteContentDirs } from './site-dirs.js'
+import { layoutAreaRoute } from '../site/layout-folder.js'
+import { orderFolders, rootOrderConfig, parseNumericPrefix, parseWildcardArray, composeLocalizedRoute, stripAtPrefix, compareFilenames } from '../site/content-collector.js'
+import { parseFrontmatter } from '../utils/frontmatter.js'
+import { upsertYamlScalar } from './yaml-upsert.js'
 
 // The pull-side identity index: a per-clone, GITIGNORED `uuid → relative path`
 // map under `.uniweb/`, the home for the backend's per-item identity so that
@@ -226,7 +234,7 @@ function readAuthoredYaml(filePath) {
  * @returns {{ siteConfig: string, theme?: string, headHtml?: string }} per-file
  *          write status ('updated' | 'unchanged')
  */
-export function siteInfoToConfig({ document, siteRoot, backend = null, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale, collector, keepAuthoredFoundation = false }) {
+export function siteInfoToConfig({ document, siteRoot, backend = null, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale, collector, keepAuthoredFoundation = false, deferLanguages = false }) {
   const info = document?.info || {}
   const settingsSection = document?.settings || {}
 
@@ -275,6 +283,11 @@ export function siteInfoToConfig({ document, siteRoot, backend = null, sourceLoc
   for (const [settingsKey, ymlKey] of Object.entries(SETTINGS_TO_SITE_YML)) {
     if (settingsSection[settingsKey] !== undefined) siteChanges[ymlKey] = settingsSection[settingsKey]
   }
+  // ⭐ The site's Open Graph title and description, sent per language as `og_title` /
+  // `og_description` where the deployment takes them: back inside `seo`, the source language's,
+  // the others to the collector in the site's context (`uwx/open-graph.js`).
+  const siteSeo = foldOpenGraph(settingsSection, siteChanges.seo, sourceLocale, collector, SITE_META_CONTEXT)
+  if (siteSeo !== undefined) siteChanges.seo = siteSeo
 
   // `settings.keywords` is a LOCALIZED list (it renders into `<meta name="keywords">`)
   // → unwrap to the source locale; the target locales go to the collector.
@@ -332,7 +345,18 @@ export function siteInfoToConfig({ document, siteRoot, backend = null, sourceLoc
     }
   }
 
+  // ⭐ `languages` for a site whose `site.yml` declares none is judged once the pull has written the
+  // translation files (`deferLanguages`, `siteContentDocumentToProject`): a push sends the list those
+  // files make (`uwx/site.js::settingsNested`), and writing it back would turn "every translation
+  // file" into a fixed list.
+  let pendingLanguages
+  if (deferLanguages && siteChanges.languages !== undefined && !('languages' in (readAuthoredYaml(join(siteRoot, 'site.yml')) || {}))) {
+    pendingLanguages = siteChanges.languages
+    delete siteChanges.languages
+  }
+
   const result = { siteConfig: writeSiteConfig(siteRoot, siteChanges) }
+  if (pendingLanguages !== undefined) result.pendingLanguages = pendingLanguages
 
   // theme (whole object) → theme.yml.
   if (settingsSection.theme && typeof settingsSection.theme === 'object') {
@@ -416,14 +440,14 @@ function reinlineInsets(content, insets) {
  *        structural maps on a localized `content` field are captured into it
  * @returns {'updated'|'unchanged'}
  */
-export function sectionRecordToFile({ filePath, record, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale, collector, freeformRelPath }) {
+export function sectionRecordToFile({ filePath, record, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale, collector, freeformRelPath, freeformCandidates = null, writeId = true, context = null }) {
   const { type, stable_id, preset, input, params, content, insets, fetch, background, theme_override } = record || {}
 
   // A localized `content` field unwraps to the source-locale doc for the body; its
   // target-locale structural maps are captured into the locales/ collector, and any
   // free-form target body is captured with `freeformRelPath` for writing under
   // locales/freeform/. A bare doc (source-only / pre-localization) passes through.
-  const sourceContent = unwrapLocalizedContent(content, sourceLocale, collector, freeformRelPath)
+  const sourceContent = unwrapLocalizedContent(content, sourceLocale, collector, freeformRelPath, freeformCandidates, context)
 
   const frontmatter = {}
   if (type !== undefined) frontmatter.type = type
@@ -439,10 +463,13 @@ export function sectionRecordToFile({ filePath, record, sourceLocale = LOCALIZED
     const { key, value } = authorableDeclaration(fetch)
     frontmatter[key] = value
   }
-  if (stable_id !== undefined) frontmatter.id = stable_id
+  // `id:` only where the file's name does not already give it (`writeId`, `pageSectionsToFiles`).
+  if (stable_id !== undefined && writeId) frontmatter.id = stable_id
 
   const body = insets ? reinlineInsets(sourceContent, insets) : sourceContent
-  return writeSectionFile({ filePath, content: body, params: frontmatter })
+  // ⛔ Not `type: Content` into a file that names no type: it is what the push sent for it, and
+  // absent, the foundation's `defaultSection` renders it. Until 2026-09-26 a pull wrote it back.
+  return writeSectionFile({ filePath, content: body, params: frontmatter, implied: { type: FILLED_SECTION_TYPE } })
 }
 
 // ---------------------------------------------------------------------------
@@ -528,7 +555,9 @@ export function sectionFileBase(record) {
  */
 export function pageSectionsToFiles({ pageDir, pageSections, ctx, pageContext }) {
   const written = []
-  const buildEntries = (records) => {
+  const files = [] // the top level's file names, in the document's order
+  let nested = false
+  const buildEntries = (records, top) => {
     const entries = []
     for (const record of records || []) {
       // Filesystem-safe filename (= stableId when already safe; derived from `$uuid`
@@ -538,7 +567,9 @@ export function pageSectionsToFiles({ pageDir, pageSections, ctx, pageContext })
       const fileBase = sectionFileBase(record)
       if (!fileBase) continue // no stable id AND no `$uuid` → nothing to name it by
       const stableId = recordStableId(record) || fileBase
-      const filePath = join(pageDir, `${fileBase}.md`)
+      // The file the author keeps it in, else a new `<fileBase>.md` (`existingSectionFile`).
+      const filePath = existingSectionFile(pageDir, fileBase, stableId, { child: !top }) || join(pageDir, `${fileBase}.md`)
+      if (top) files.push(basename(filePath))
       // If this uuid's section moved (an app-side stableId rename), relocate its
       // `.md` in place before writing; then record its current path in the index.
       placeByUuid(ctx, record.$uuid, filePath)
@@ -547,14 +578,76 @@ export function pageSectionsToFiles({ pageDir, pageSections, ctx, pageContext })
       const freeformRelPath = pageContext
         ? buildFreeformPath({ stableId }, pageContext)
         : null
-      sectionRecordToFile({ filePath, record, sourceLocale: ctx?.sourceLocale, collector: ctx?.collector, freeformRelPath })
+      // Every path the renderer would find it at, so one the author keeps is written back in place.
+      const freeformCandidates = pageContext ? freeformPathsFor({ stableId }, pageContext) : null
+      sectionRecordToFile({
+        filePath,
+        record,
+        sourceLocale: ctx?.sourceLocale,
+        collector: ctx?.collector,
+        freeformRelPath,
+        freeformCandidates,
+        writeId: fileSectionName(filePath) !== stableId,
+        context: pageContext ? translationContext({ stableId }, pageContext.route) : null,
+      })
       written.push(filePath)
       const children = Array.isArray(record.$children) ? record.$children : []
-      entries.push(children.length > 0 ? { [fileBase]: buildEntries(children) } : fileBase)
+      if (children.length > 0) nested = true
+      // Listed by the name the build finds the file by — which is not the id for a file found by its `id:`.
+      const listed = fileSectionName(filePath)
+      entries.push(children.length > 0 ? { [listed]: buildEntries(children, false) } : listed)
     }
     return entries
   }
-  return { sections: buildEntries(pageSections), written }
+  const sections = buildEntries(pageSections, true)
+  // Kept for the prune, which must not take a file this pull wrote into for an orphan.
+  ctx?.sectionFiles?.set(pageDir, new Set(written.map((f) => basename(f, extname(f)))))
+  // ⭐ Whether the files give the document's order by themselves, as the build reads a page with no
+  // `sections:` list — by name, numeric prefixes first — so the page needs no list to say it.
+  const filesGiveOrder = !nested && files.every((f) => !f.startsWith('@')) && [...files].sort(compareFilenames).join('\n') === files.join('\n')
+  return { sections, written, filesGiveOrder }
+}
+
+// The name the build reads a section file's section by: its file name without the `@` child mark and
+// the numeric ordering prefix (`2-story.md` holds `story`) — unless its frontmatter names another.
+function fileSectionName(filePath) {
+  const base = stripAtPrefix(basename(filePath, extname(filePath)))
+  return parseNumericPrefix(base).name || base
+}
+
+// A `sections:` list with each entry as that name — `1-hero` and `hero` find the same file.
+function listedNames(list) {
+  return list.map((entry) =>
+    typeof entry === 'string'
+      ? fileSectionName(entry)
+      : entry && typeof entry === 'object'
+        ? Object.fromEntries(Object.entries(entry).map(([k, v]) => [fileSectionName(k), Array.isArray(v) ? listedNames(v) : v]))
+        : entry
+  )
+}
+
+// ⭐ THE FILE THE AUTHOR KEEPS A SECTION IN — found by the name the build reads it by (`1-hero.md` holds
+// `hero`), else by the `id:` in its frontmatter. ⛔ Until 2026-09-26 a pull wrote every section as
+// `<id>.md` and pruned the author's `1-hero.md` as an orphan: a pull into the copy that pushed renamed
+// every numbered section file, wrote its id into it, and added a `sections:` list to recover the order
+// the numbers had given (measured on the `international` template).
+//
+// ⛔ A top-level section never takes an `@` file: that is a child's name, and the build renders an
+// `@` file no `nest:` claims only as an orphan appended at the end — listed by name, it is not rendered.
+function existingSectionFile(pageDir, fileBase, stableId, { child = false } = {}) {
+  if (!existsSync(pageDir)) return null
+  const entries = readdirSync(pageDir).filter((e) => isMarkdownFile(e) && (child || !e.startsWith('@')))
+  const found =
+    entries.find((e) => basename(e, '.md') === fileBase) ||
+    entries.find((e) => fileSectionName(e) === fileBase) ||
+    entries.find((e) => {
+      try {
+        return parseFrontmatter(readFileSync(join(pageDir, e), 'utf8'), e).frontmatter?.id === stableId
+      } catch {
+        return false // unreadable — not this one
+      }
+    })
+  return found ? join(pageDir, found) : null
 }
 
 // Every key pageRecordToYml can emit — the keys the projector OWNS in a
@@ -570,14 +663,23 @@ const PAGE_YML_MANAGED_KEYS = new Set([
   'query', 'fetch', 'data', 'sections',
 ])
 
+// Keys a pull WRITES and never removes — kept out of the managed set on purpose. ⭐ `slug`, a page's
+// localized URL segments: a document pushed by a CLI from before 2026-09-26 carries none, and reading
+// that as "none" would delete the author's (`pageSlugToYml`). The cost is that one removed in the
+// backend stays in the file.
+const PAGE_YML_KEPT_KEYS = new Set(['slug'])
+
 // Inverse of site.js buildPageData → the `page.yml` / `folder.yml` object.
-// `slug`/`mode`/`is_dynamic`/`param_name` are NOT keys here — they shape the
-// directory (name, page.yml vs folder.yml, `[param]/`), not the config body.
+// `mode`/`is_dynamic`/`param_name` are NOT keys here — they shape the directory
+// (name, page.yml vs folder.yml, `[param]/`), not the config body. `slug`'s source
+// entry names the directory; its other locales are the page's `slug:` map.
 // Identity (the backend uuid) is NOT written here — it lives in the gitignored
 // `.uniweb/` index so authored files stay clean.
-function pageRecordToYml(record, sectionsArray, sourceLocale, existing = null) {
+function pageRecordToYml(record, sectionsArray, sourceLocale, existing = null, { isRoot = false, slug = null, filesGiveOrder = false } = {}) {
   const y = {}
   if (record.stable_id !== undefined) y.id = record.stable_id
+  // The page's localized URL segments, when the site keeps them here (`pageSlugToYml`).
+  if (slug) y.slug = slug
   const title = unwrapLocalized(record.title, sourceLocale)
   if (title !== undefined) y.title = title
   const description = unwrapLocalized(record.description, sourceLocale)
@@ -585,7 +687,9 @@ function pageRecordToYml(record, sectionsArray, sourceLocale, existing = null) {
   const label = unwrapLocalized(record.label, sourceLocale)
   if (label !== undefined) y.label = label
   if (record.keywords !== undefined) y.keywords = unwrapLocalizedList(record.keywords, sourceLocale)
-  if (record.is_index) y.index = true
+  // A ROOT page's homepage mark is the site's to carry (`site.yml`, below); on its own page.yml only
+  // where the author wrote it. ⛔ Until 2026-09-26 every pull added `index: true` to it, beside the site's.
+  if (record.is_index && (!isRoot || existing?.index === true)) y.index = true
   if (record.hidden !== undefined) y.hidden = record.hidden
   if (record.hide_in !== undefined) y.hideIn = record.hide_in
   if (record.knowledge !== undefined) y.knowledge = record.knowledge
@@ -598,7 +702,10 @@ function pageRecordToYml(record, sectionsArray, sourceLocale, existing = null) {
   if (record.redirect !== undefined) y.redirect = record.redirect
   if (record.rewrite !== undefined) y.rewrite = record.rewrite
   if (record.layout !== undefined) y.layout = record.layout
-  if (record.seo !== undefined) y.seo = record.seo
+  // Its Open Graph title and description, per language on the wire, back inside `seo`
+  // (`uwx/open-graph.js`); their other languages are collected with the page's metadata.
+  const seo = foldOpenGraph(record, record.seo, sourceLocale)
+  if (seo !== undefined) y.seo = seo
   // Invert the build's resolution rather than copy it — see fetch-shapes.js. Under
   // the key the file already uses (`existing`), else `query:` for names alone.
   if (record.fetch !== undefined) {
@@ -615,7 +722,20 @@ function pageRecordToYml(record, sectionsArray, sourceLocale, existing = null) {
   // The trailing `...` makes it inclusive: listed sections keep their order and
   // their nesting, and anything new is discovered and appended as it would be in a
   // page that was never pulled.
-  if (sectionsArray && sectionsArray.length > 0) y.sections = [...sectionsArray, '...']
+  // ⭐ The author's own list is kept when it gives the same order — its `...` stays where they put it.
+  // A page with no list gets none where its files' names give the order (`filesGiveOrder`).
+  if (sectionsArray && sectionsArray.length > 0) {
+    const authored = existing?.sections
+    if (Array.isArray(authored)) {
+      // Compared by the names the files are found by, so a list naming `1-hero` keeps naming it.
+      const same = JSON.stringify(listedNames(authored.filter((e) => e !== '...'))) === JSON.stringify(sectionsArray)
+      y.sections = same ? authored : [...sectionsArray, '...']
+    } else if (!filesGiveOrder) {
+      y.sections = [...sectionsArray, '...']
+    } else if (authored !== undefined) {
+      y.sections = authored // `'*'`, which says what no list says
+    }
+  }
   return y
 }
 
@@ -666,8 +786,8 @@ function pruneOrphanPageDirs(pagesDir, keepDirs, report) {
 // incoming level never nukes an existing one (a malformed/partial payload can't
 // wipe it).
 function projectPages(pages, pagesDir, sourceLocale, report, prune, ctx) {
-  writePagesTree(pages, pagesDir, sourceLocale, report, ctx)
-  if (prune) prunePagesTree(pages, pagesDir, sourceLocale, report)
+  writePagesTree(pages, pagesDir, sourceLocale, report, ctx, '', rootOrderList(ctx.siteRoot, pagesDir))
+  if (prune) prunePagesTree(pages, pagesDir, sourceLocale, report, ctx)
 }
 
 // The directory name for a page record (slug, or `[param]/` for a dynamic page).
@@ -688,29 +808,41 @@ export function pageDirName(record, sourceLocale) {
 // section files, recursing into children. No deletes happen here. `routePrefix`
 // accumulates the slug-path route (for the free-form translation path; matches the
 // producer's slugPath, normalizeRouteForPath strips any leading slash on both).
-function writePagesTree(pages, pagesDir, sourceLocale, report, ctx, routePrefix = '') {
+function writePagesTree(pages, pagesDir, sourceLocale, report, ctx, routePrefix = '', list = null, canonParent = '/') {
   for (const record of pages || []) {
     const slug = unwrapLocalized(record.slug, sourceLocale) // localized {lang:value} → canonical
+    // The route the build gives the page (`buildRouteOf`, the push's rule): an index page takes its
+    // parent's, a parametric one is `:<param>`.
+    const canon = buildRouteOf(record, canonParent, sourceLocale)
     const pageDir = join(pagesDir, pageDirName(record, sourceLocale))
     // Relocate the whole page dir if this uuid moved to a new slug, then record it.
     placeByUuid(ctx, record.$uuid, pageDir)
 
     // Capture target-locale translations of the page's localized scalars; the
-    // source value goes inline into page.yml below (pageRecordToYml unwraps it).
-    ctx.collector?.add(record.title)
-    ctx.collector?.add(record.label)
-    ctx.collector?.add(record.description)
+    // source value goes inline into page.yml below (pageRecordToYml unwraps it). In the page's
+    // context, as the build translates them (`<route>:_meta`), so an override for one page comes back.
+    const meta = { page: canon, section: '_meta' }
+    ctx.collector?.add(record.title, meta)
+    ctx.collector?.add(record.label, meta)
+    ctx.collector?.add(record.description, meta)
+    ctx.collector?.add(record.og_title, meta)
+    ctx.collector?.add(record.og_description, meta)
     // keywords is a localized ARRAY — capture each element's target locales.
-    if (Array.isArray(record.keywords)) record.keywords.forEach((kw) => ctx.collector?.add(kw))
-    else ctx.collector?.add(record.keywords)
+    if (Array.isArray(record.keywords)) record.keywords.forEach((kw) => ctx.collector?.add(kw, meta))
+    else ctx.collector?.add(record.keywords, meta)
 
     const route = routePrefix ? `${routePrefix}/${slug}` : slug
-    const pageContext = { route, id: record.stable_id }
+    // Addressed as the push addresses it: its free-form translations and its translations' contexts
+    // are keyed by the build's route. ⛔ Until 2026-09-26 this was the slug path — `home` for a
+    // homepage the build reads at `/`.
+    const pageContext = { route: canon, id: record.stable_id }
 
     let sectionsArray = []
+    let filesGiveOrder = false
     if (record.mode === 'page' && Array.isArray(record.page_sections)) {
       const r = pageSectionsToFiles({ pageDir, pageSections: record.page_sections, ctx, pageContext })
       sectionsArray = r.sections
+      filesGiveOrder = r.filesGiveOrder
       report.sections.push(...r.written)
     }
 
@@ -718,11 +850,124 @@ function writePagesTree(pages, pagesDir, sourceLocale, report, ctx, routePrefix
     const ymlPath = join(pageDir, ymlName)
     // Merge (not full-dump) so author-added keys survive a pull; the projector
     // owns only PAGE_YML_MANAGED_KEYS.
-    writeMergedYaml(ymlPath, pageRecordToYml(record, sectionsArray, sourceLocale, readAuthoredYaml(ymlPath)), PAGE_YML_MANAGED_KEYS)
+    const existing = readAuthoredYaml(ymlPath)
+    const pageSlug = pageSlugToYml(record, canon, existing, sourceLocale, ctx)
+    writeMergedYaml(ymlPath, pageRecordToYml(record, sectionsArray, sourceLocale, existing, { isRoot: !routePrefix, slug: pageSlug, filesGiveOrder }), PAGE_YML_MANAGED_KEYS)
     report.pages.push(ymlPath)
 
-    writePagesTree(record.$children || [], pageDir, sourceLocale, report, ctx, route)
+    writePagesTree(record.$children || [], pageDir, sourceLocale, report, ctx, route, parentOrderList(ymlPath), canon)
+  }
+  reconcileLevelOrder({ pages, pagesDir, sourceLocale, list, homepage: routePrefix ? null : ctx.homepage })
+}
+
+// ⭐ A PAGE'S LOCALIZED URL SEGMENTS — the other locales of its `slug` (`localizeRouteSlugs`, the push) —
+// go back where the site keeps them: the page's own `slug:` map, or `site.yml`'s `i18n.routeTranslations`
+// (`writeRouteTranslations`). A copy that keeps neither — a clone — gets the page's `slug:`, the form the
+// docs lead with. ⛔ Until 2026-09-26 they did not travel, and a clone lost every localized URL.
+//
+// ⚖️ A pull adds and changes these, and never removes one: a page pushed by a CLI from before carries
+// none, and reading that as "none" would delete what the author wrote.
+function pageSlugToYml(record, canon, existing, sourceLocale, ctx) {
+  if (record.is_dynamic) return null
+  const targets = localizedTargets(record.slug, sourceLocale)
+  const own = isPlainRecord(existing?.slug)
+  if (!own && ctx.routes?.siteMap && !record.is_index) {
+    if (Object.keys(targets).length) ctx.routes.slugs.set(canon, targets)
+    return null
   }
+  if (!Object.keys(targets).length) return null
+  const next = { ...(own ? existing.slug : {}), ...targets }
+  return own && stableJson(next) === stableJson(existing.slug) ? null : next
+}
+
+// The locales of a pulled localized `slug` other than the source one.
+function localizedTargets(slug, sourceLocale) {
+  if (!isPlainRecord(slug)) return {}
+  return Object.fromEntries(
+    Object.entries(slug).filter(([l, v]) => l !== sourceLocale && l !== '@' && !l.startsWith('$') && typeof v === 'string' && v)
+  )
+}
+
+// `site.yml`'s `i18n.routeTranslations`, from the segments the pages carried — each route composed
+// as the build composes it. Written only when that changes it, since the write re-dumps `site.yml`.
+function writeRouteTranslations(siteRoot, routes) {
+  if (!routes?.siteMap || routes.slugs.size === 0) return
+  const authored = routes.siteMap
+  const next = JSON.parse(JSON.stringify(authored))
+  for (const [route, targets] of routes.slugs) {
+    for (const locale of Object.keys(targets)) {
+      if (!isPlainRecord(next[locale])) next[locale] = {}
+      next[locale][route] = composeLocalizedRoute(route, locale, routes.slugs)
+    }
+  }
+  if (stableJson(next) !== stableJson(authored)) writeSiteConfig(siteRoot, { i18n: { routeTranslations: next } })
+}
+
+const isPlainRecord = (v) => v !== null && typeof v === 'object' && !Array.isArray(v)
+const stableJson = (value) =>
+  JSON.stringify(value, (_, v) => (isPlainRecord(v) ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, v[k]])) : v))
+
+// ⭐ A LEVEL'S ORDER IS THE BACKEND'S — the order the pulled document gives its pages, which is the
+// order a push read them in, or the one the app set since. A level whose own config already gives it
+// is left as it is; otherwise it is said the way the level says it: its `pages:` list, in that order,
+// or else `order:` on each page. ⛔ Until 2026-09-26 a pull wrote neither: a clone's menus came back in
+// filename order (measured on the `international` and `marketing` templates), and an order changed in
+// the app was undone by the next push.
+//
+// ⭐ `order:` goes on the fewest pages that give the order. The build puts the numbered pages first and
+// the rest after them by filename (`orderFolders`), so the pages at the END that are already in
+// filename order, and carry no `order:`, need none — the way `international` numbers four pages and
+// leaves `404` and `home` to follow. ⛔ The first version of this numbered every page of the level.
+function reconcileLevelOrder({ pages, pagesDir, sourceLocale, list, homepage = null }) {
+  const level = (pages || []).map((r) => {
+    const dirName = pageDirName(r, sourceLocale)
+    return { dirName, yml: join(pagesDir, dirName, r.mode === 'folder' ? 'folder.yml' : 'page.yml') }
+  })
+  if (level.length < 2) return
+  const folders = level.map(({ dirName, yml }) => {
+    const order = readAuthoredYaml(yml)?.order
+    return { dirName, name: parseNumericPrefix(dirName).name, order: typeof order === 'number' ? order : undefined }
+  })
+  const ordered = orderFolders(folders, list?.pages).map((f) => f.dirName)
+  if (ordered.join('\n') === level.map((l) => l.dirName).join('\n')) return
+  const parsed = Array.isArray(list?.pages) ? parseWildcardArray(list.pages) : null
+  if (parsed && parsed.mode !== 'all') {
+    const names = folders.map((f) => f.name)
+    // A root list's first entry is the homepage; when the backend's order does not open with it, the
+    // list opens with `...`, and `index:` names it (`siteContentDocumentToProject`).
+    if (homepage && names[0] !== homepage) list.write(['...', ...names])
+    else list.write(parsed.mode === 'strict' ? names : [...names, '...'])
+    return
+  }
+  // The unnumbered tail: the longest run at the end in filename order, none of it numbered.
+  const inWire = level.map(({ dirName }) => folders.find((f) => f.dirName === dirName))
+  let tail = inWire.length
+  while (tail > 0) {
+    const candidate = inWire.slice(tail - 1)
+    if (candidate[0].order !== undefined) break
+    const byName = orderFolders(candidate, null).map((f) => f.dirName)
+    if (byName.join('\n') !== candidate.map((f) => f.dirName).join('\n')) break
+    tail--
+  }
+  level.slice(0, tail).forEach(({ yml }, i) => writeMergedYaml(yml, { order: i + 1 }, ['order']))
+}
+
+// The `pages:` list a level is ordered by, and how to rewrite it. The root's is the site config's,
+// else the pages directory's own (`rootOrderConfig`, the build's rule); any other level's is its
+// parent page's.
+function rootOrderList(siteRoot, pagesDir) {
+  const site = readAuthoredYaml(join(siteRoot, 'site.yml')) || {}
+  const dirConfig = ['folder.yml', 'page.yml'].map((f) => join(pagesDir, f)).find((f) => existsSync(f)) || null
+  const { pages, homepage } = rootOrderConfig({ pages: site.pages, index: site.index }, (dirConfig && readAuthoredYaml(dirConfig)) || {})
+  const inSite = Array.isArray(site.pages) && site.pages.length > 0
+  return {
+    pages,
+    homepage,
+    write: (next) => (inSite || !dirConfig ? writeSiteConfig(siteRoot, { pages: next }) : writeMergedYaml(dirConfig, { pages: next }, ['pages'])),
+  }
+}
+function parentOrderList(ymlPath) {
+  return { pages: readAuthoredYaml(ymlPath)?.pages, write: (next) => writeMergedYaml(ymlPath, { pages: next }, ['pages']) }
 }
 
 // Every section FILE base in a page's section tree. Nested children are written as
@@ -743,16 +988,17 @@ function collectSectionFileBases(pageSections) {
 
 // Pass 2 — prune orphan section files (per page dir) and orphan page dirs (per
 // level), AFTER every relocation in pass 1. Guarded against wiping an empty level.
-function prunePagesTree(pages, pagesDir, sourceLocale, report) {
+function prunePagesTree(pages, pagesDir, sourceLocale, report, ctx = null) {
   const incomingDirs = new Set()
   for (const record of pages || []) {
     incomingDirs.add(pageDirName(record, sourceLocale))
     const pageDir = join(pagesDir, pageDirName(record, sourceLocale))
     if (record.mode === 'page') {
-      const keep = collectSectionFileBases(record.page_sections)
+      // The files pass 1 wrote into — the author's own names among them — else the names it would give.
+      const keep = ctx?.sectionFiles?.get(pageDir) || collectSectionFileBases(record.page_sections)
       if (keep.size > 0) pruneOrphanSectionFiles(pageDir, keep, report)
     }
-    prunePagesTree(record.$children || [], pageDir, sourceLocale, report)
+    prunePagesTree(record.$children || [], pageDir, sourceLocale, report, ctx)
   }
   if (incomingDirs.size > 0) pruneOrphanPageDirs(pagesDir, incomingDirs, report)
 }
@@ -842,7 +1088,19 @@ function projectLayout(layoutSections, layoutBaseDir, report, prune, ctx) {
     // A relocation into a new area folder needs the folder first.
     mkdirSync(dirname(filePath), { recursive: true })
     placeByUuid(ctx, record.$uuid, filePath)
-    sectionRecordToFile({ filePath, record, sourceLocale: ctx?.sourceLocale, collector: ctx?.collector })
+    // Its free-form translation lives at the area's route, as the build reads it (`layoutAreaRoute`).
+    const stableId = recordStableId(record)
+    const page = { route: layoutAreaRoute(record.layout_name, record.area || stableId) }
+    sectionRecordToFile({
+      filePath,
+      record,
+      sourceLocale: ctx?.sourceLocale,
+      collector: ctx?.collector,
+      writeId: fileSectionName(filePath) !== stableId,
+      freeformRelPath: stableId ? buildFreeformPath({ stableId }, page) : null,
+      freeformCandidates: stableId ? freeformPathsFor({ stableId }, page) : null,
+      context: translationContext({ stableId }, page.route),
+    })
     report.layout.push(filePath)
     written.push(filePath)
   }
@@ -871,14 +1129,17 @@ function projectLayout(layoutSections, layoutBaseDir, report, prune, ctx) {
  * @param {string|null} [params.scope] - the scope the push qualified a query's
  *        `@/x` schema with, so it is written back as `@/x` — see
  *        `declarationsToQueriesYml`, whose default it overrides.
+ * @param {Object<string,object>|null} [params.models] - the Models the site's queries name, as the
+ *        pull read them from the backend, keyed by the ref on the wire — what a clone, with no
+ *        foundation on disk, judges a query's derived `deferred:` by.
  * @returns {{ config: object, collections: object, locales: object, pages: string[], sections: string[], layout: string[], deleted: string[], renamed: object[] }}
  */
-export function siteContentDocumentToProject({ document, siteRoot, backend = null, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale, prune = false, keepAuthoredFoundation = false, scope }) {
+export function siteContentDocumentToProject({ document, siteRoot, backend = null, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale, prune = false, keepAuthoredFoundation = false, scope, models = null }) {
   const report = { config: null, collections: null, locales: null, assets: null, pages: [], sections: [], layout: [], deleted: [], renamed: [] }
 
   // Collects target-locale translations of localized scalars as they're projected;
   // flushed to locales/{locale}.json at the end (the manifest stays derivable).
-  const collector = createTranslationCollector(sourceLocale)
+  const collector = createTranslationCollector(sourceLocale, { siteRoot })
 
   // Put the author's own asset paths back before anything is serialized. Stored
   // content carries an id and a serve URL; only the committed map knows the ref
@@ -895,25 +1156,59 @@ export function siteContentDocumentToProject({ document, siteRoot, backend = nul
     backend ? readBackendState(siteRoot, backend).assets || {} : {}
   )
 
-  report.config = siteInfoToConfig({ document, siteRoot, backend, sourceLocale, collector, keepAuthoredFoundation })
-  report.queries = declarationsToQueriesYml({ document, siteRoot, scope })
+  report.config = siteInfoToConfig({ document, siteRoot, backend, sourceLocale, collector, keepAuthoredFoundation, deferLanguages: true })
+  report.queries = declarationsToQueriesYml({ document, siteRoot, scope, models })
 
   // The uuid identity index (gitignored `.uniweb/`): read the prior map to anchor
   // rename detection, build a fresh one as we project, then persist it. Items not
   // re-projected (deleted) drop out naturally. `collector` rides along to capture
   // localized scalars during the page walk.
-  const ctx = { siteRoot, oldIndex: readPullIndex(siteRoot), newIndex: {}, report, collector, sourceLocale }
+  const ctx = { siteRoot, oldIndex: readPullIndex(siteRoot), newIndex: {}, report, collector, sourceLocale, sectionFiles: new Map() }
+  // Where the site keeps its localized URLs — `site.yml`'s map, when it has one (`pageSlugToYml`).
+  const siteMap = readAuthoredYaml(join(siteRoot, 'site.yml'))?.i18n?.routeTranslations
+  ctx.routes = { siteMap: isPlainRecord(siteMap) && Object.keys(siteMap).length ? siteMap : null, slugs: new Map() }
 
   // Where the tree goes is what `site.yml` says NOW — `siteInfoToConfig` above has
   // written the document's `settings.paths` into it — because that is the file the
   // next push and the build read. See `siteContentDirs`.
   const { pagesDir, layoutDir: layoutBaseDir } = siteContentDirs(siteRoot, readAuthoredYaml(join(siteRoot, 'site.yml')))
+  // The root page the backend marks as the homepage, by the directory it is written to.
+  const home = (document?.pages || []).find((p) => p?.is_index)
+  ctx.homepage = home ? pageDirName(home, sourceLocale) : null
   projectPages(document?.pages, pagesDir, sourceLocale, report, prune, ctx)
+  writeRouteTranslations(siteRoot, ctx.routes)
+  // ⭐ THE HOMEPAGE IS THE ONE THE BACKEND MARKS, named where the site names it. ⛔ Until 2026-09-26 a
+  // clone kept its scaffold's `index: home` whatever the site's homepage was — a page that may not
+  // exist — and the homepage was marked on its own page.yml instead.
+  if (ctx.homepage) {
+    const root = rootOrderList(siteRoot, pagesDir)
+    // A homepage marked `index: true` in its own config — where the push read it (`buildPageData`) —
+    // is left marked there alone: a site.yml that names none is not given an `index:` it never had.
+    const marksItself = readAuthoredYaml(join(pagesDir, ctx.homepage, home.mode === 'folder' ? 'folder.yml' : 'page.yml'))?.index === true
+    if (root.homepage !== ctx.homepage && !(marksItself && root.homepage === undefined)) {
+      const listed = Array.isArray(root.pages) ? parseWildcardArray(root.pages) : null
+      // A list that names the homepage first beats `index:`, so it opens with `...` instead.
+      if (listed && listed.before.length > 0) root.write(['...', ...root.pages.filter((e) => e !== '...')])
+      upsertYamlScalar(join(siteRoot, 'site.yml'), 'index', ctx.homepage)
+    }
+  }
   projectLayout(document?.layout_sections, layoutBaseDir, report, prune, ctx)
 
   report.locales = writeLocaleTranslations(siteRoot, collector.byLocale)
   // Target-locale FREE-FORM bodies → locales/freeform/{locale}/<relpath> + manifest.
   report.freeform = writeFreeformTranslations(siteRoot, collector.freeformPending)
+  // The site's languages, for a site.yml that declares none (`siteInfoToConfig`) — written only where
+  // the translation files, now written, would not make the same list, or where `publishLanguages`
+  // needs a declared list to draw from: the build refuses one without it.
+  if (report.config?.pendingLanguages !== undefined) {
+    const pulled = report.config.pendingLanguages
+    delete report.config.pendingLanguages
+    const site = readAuthoredYaml(join(siteRoot, 'site.yml')) || {}
+    const source = site.defaultLanguage || sourceLocale
+    const made = new Set([source, ...resolveLocaleList(undefined, localesDir(siteRoot))])
+    const same = Array.isArray(pulled) && pulled.length === made.size && pulled.every((l) => made.has(l))
+    if (!same || site.publishLanguages !== undefined) writeSiteConfig(siteRoot, { languages: pulled })
+  }
   writePullIndex(siteRoot, ctx.newIndex)
   return report
 }