@uniweb/build 0.80.2 → 0.80.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.80.2",
+  "version": "0.80.3",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -57,10 +57,10 @@
     "js-yaml": "^4.1.0",
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
+    "@uniweb/projections": "^0.7.15",
     "@uniweb/content-reader": "^1.2.8",
     "@uniweb/content-writer": "^0.3.4",
     "@uniweb/schemas": "^0.13.0",
-    "@uniweb/projections": "^0.7.15",
     "@uniweb/semantic-parser": "^1.5.1",
     "@uniweb/theming": "^0.2.0"
   },
@@ -74,8 +74,8 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/runtime": "^0.29.4",
-    "@uniweb/core": "^0.38.0"
+    "@uniweb/core": "^0.38.0",
+    "@uniweb/runtime": "^0.29.4"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/site/layout-folder.js

@@ -30,8 +30,7 @@
  * @module @uniweb/build/site/layout-folder
  */
 
-import { readdir } from 'node:fs/promises'
-import { existsSync } from 'node:fs'
+import { existsSync, readdirSync } from 'node:fs'
 import { dirname, join, parse, relative } from 'node:path'
 import { parseNumericPrefix, compareByNumericPrefix } from '../utils/numeric-prefix.js'
 import { isMarkdownFile, isIgnoredFolder } from '../utils/content-files.js'
@@ -93,7 +92,19 @@ export function _resetLayoutFolderWarnings() {
  *   section order; `source` is the area's path, relative, for messages.
  * @throws when the folder declares something no lane can read the same way
  */
-export async function readLayoutFolder(layoutDir, { siteRoot = null, onWarning = (m) => console.warn(m) } = {}) {
+export async function readLayoutFolder(layoutDir, options = {}) {
+  return readLayoutFolderSync(layoutDir, options)
+}
+
+/**
+ * `readLayoutFolder`, synchronously — the same reader, for a caller that cannot await: the pull,
+ * which writes each area's sections back where this finds them (`uwx/site-project.js`).
+ *
+ * @param {string} layoutDir
+ * @param {Object} [options] - as `readLayoutFolder`'s
+ * @returns {Array<{ layout: string, area: string, form: 'file'|'folder', dir: string, files: string[], source: string }>}
+ */
+export function readLayoutFolderSync(layoutDir, { siteRoot = null, onWarning = (m) => console.warn(m) } = {}) {
   if (!layoutDir || !existsSync(layoutDir)) return []
 
   const base = siteRoot || dirname(layoutDir)
@@ -140,8 +151,8 @@ export async function readLayoutFolder(layoutDir, { siteRoot = null, onWarning =
   }
 
   /** The areas inside one layout's folder (the root folder is the default layout's). */
-  const readAreas = async (layoutName, dir, { isRoot }) => {
-    const entries = (await readdir(dir, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))
+  const readAreas = (layoutName, dir, { isRoot }) => {
+    const entries = readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))
 
     const files = []
     const folders = []
@@ -168,14 +179,14 @@ export async function readLayoutFolder(layoutDir, { siteRoot = null, onWarning =
       const areaDir = join(dir, folder)
       const area = parseNumericPrefix(folder).name
       const sectionFiles = []
-      for (const entry of await readdir(areaDir, { withFileTypes: true })) {
+      for (const entry of readdirSync(areaDir, { withFileTypes: true })) {
         if (entry.isFile()) {
           refusePageConfig(areaDir, entry.name)
           if (!isMarkdownFile(entry.name)) continue
           refuseChild(areaDir, entry.name)
           sectionFiles.push(entry.name)
         } else if (entry.isDirectory() && !isIgnoredFolder(entry.name)) {
-          const nested = (await readdir(join(areaDir, entry.name))).filter(isMarkdownFile)
+          const nested = readdirSync(join(areaDir, entry.name)).filter(isMarkdownFile)
           if (nested.length > 0) {
             fail(
               join(areaDir, entry.name),
@@ -197,7 +208,7 @@ export async function readLayoutFolder(layoutDir, { siteRoot = null, onWarning =
     return []
   }
 
-  const layoutFolders = await readAreas(DEFAULT_LAYOUT, layoutDir, { isRoot: true })
+  const layoutFolders = readAreas(DEFAULT_LAYOUT, layoutDir, { isRoot: true })
 
   // Each folder directly under layout/ is a named layout; `default` (in any case, with
   // or without a trailing `Layout`) is the default layout written as a folder.
@@ -229,7 +240,7 @@ export async function readLayoutFolder(layoutDir, { siteRoot = null, onWarning =
         )
       }
     }
-    await readAreas(layoutName, join(layoutDir, folder), { isRoot: false })
+    readAreas(layoutName, join(layoutDir, folder), { isRoot: false })
   }
 
   return areas

package/src/uwx/index.js

@@ -91,6 +91,8 @@ export {
   // The file the author keeps a section in (`1-hero.md` holds `hero`) — what a section
   // unit's path names on disk, for a push recording what it delivered.
   existingSectionFile,
+  // …and the file a layout unit names on disk (`default/footer.md` holds the `footer.md` place).
+  layoutUnitFile,
 } from './site-project.js'
 export {
   createTranslationCollector,

package/src/uwx/locale-sync.js

@@ -27,6 +27,7 @@ import { visitDataBlockStrings } from '../i18n/data-strings.js'
 import { resolveDocForLocale, translatedInline, linkLabels } from '../i18n/merge.js'
 import { computeSourceHash } from '../i18n/freeform-manifest.js'
 import { sameMarkdownDocument, canonicalJson } from './same-content.js'
+import { parseFrontmatter } from '../utils/frontmatter.js'
 
 const FREEFORM_MANIFEST = '.manifest.json'
 
@@ -389,6 +390,15 @@ function deriveStructuralMap(sourceDoc, targetDoc, modelFor = () => null) {
   return addDataBlockStrings(map, sourceDoc, targetDoc, modelFor)
 }
 
+// Whether a free-form file says `target`, read as a push reads it — its body, as stored.
+function sameStoredFreeform(text, filePath, target) {
+  try {
+    return sameMarkdownDocument(parseFrontmatter(text, filePath).body, target)
+  } catch {
+    return false
+  }
+}
+
 // ⭐ A LINK'S LABEL, NOT THE LINK, when only its words were translated. The merge reads a label onto
 // the source's own link (`merge.js::translatedInline`), so it keeps following that link wherever the
 // source moves it, where `[Donar Ahora](/contact)` would keep `/contact`. Several links are a label a
@@ -564,7 +574,9 @@ export function writeFreeformTranslations(siteRoot, freeformPending) {
       }
       // ⭐ A file whose markdown already says this is left as the author wrote it — the writer's
       // markdown is not theirs (blank lines, line breaks), as for a section body (`writeSectionFile`).
-      if (current !== text && !(current !== null && sameMarkdownDocument(current.trim(), target))) {
+      // Compared as a push reads it (`i18n/freeform.js::loadFreeformTranslation`). ⛔ Until 2026-10-08 the
+      // file was trimmed first, so one whose last line ended in a space was rewritten by every pull.
+      if (current !== text && !(current !== null && sameStoredFreeform(current, filePath, target))) {
         mkdirSync(dirname(filePath), { recursive: true })
         writeFileSync(filePath, text)
         report.written.push(filePath)

package/src/uwx/project-writer.js

@@ -204,7 +204,10 @@ export function writeSectionFile({ filePath, content, params, reserved = DEFAULT
   // only frontmatter — a parametric page's `type:` and `fetch:` — was re-serialized, and lost its
   // comments, on a pull that changed nothing. So is no document at all (a params-only update).
   const authoredBody = (existingBody || '').replace(/^\n+/, '').replace(/\s+$/, '')
-  const keepsBody = !content || sameMarkdownDocument(authoredBody, content)
+  // Compared as a push reads it: the body as stored (`content-collector.js::processMarkdownFile`).
+  // ⛔ Until 2026-10-08 the trimmed copy was compared, so a body whose last line ended in a space never
+  // matched what a push had sent from it, and every pull rewrote it — trailing blank lines and all.
+  const keepsBody = !content || sameMarkdownDocument(existingBody || '', content)
   if (existing && keepsBody && canonicalJson(nextFrontmatter) === canonicalJson(frontmatter)) return 'unchanged'
   const body = keepsBody ? authoredBody : proseMirrorToMarkdown(content)
   return writeIfChanged(filePath, assembleSection(nextFrontmatter, body))

package/src/uwx/site-project.js

@@ -52,7 +52,8 @@ 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 { layoutAreaRoute, readLayoutFolderSync, DEFAULT_LAYOUT } from '../site/layout-folder.js'
+import { layoutNameKey } from '@uniweb/core/layout-name'
 import { orderFolders, rootOrderConfig, parseNumericPrefix, parseWildcardArray, composeLocalizedRoute, stripAtPrefix, compareFilenames } from '../site/content-collector.js'
 import { parseFrontmatter } from '../utils/frontmatter.js'
 
@@ -503,6 +504,7 @@ export function sectionFileBase(record) {
 export function pageSectionsToFiles({ pageDir, pageSections, ctx, pageContext }) {
   const written = []
   const files = [] // the top level's file names, in the document's order
+  const childFiles = [] // every nested section's file name
   let nested = false
   const buildEntries = (records, top) => {
     const entries = []
@@ -539,6 +541,7 @@ export function pageSectionsToFiles({ pageDir, pageSections, ctx, pageContext })
         context: pageContext ? translationContext({ stableId }, pageContext.route) : null,
       })
       written.push(filePath)
+      if (!top) childFiles.push(basename(filePath))
       const children = Array.isArray(record.$children) ? record.$children : []
       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:`.
@@ -552,8 +555,12 @@ export function pageSectionsToFiles({ pageDir, pageSections, ctx, pageContext })
   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 }
+  const topInOrder = files.every((f) => !f.startsWith('@')) && [...files].sort(compareFilenames).join('\n') === files.join('\n')
+  const filesGiveOrder = !nested && topInOrder
+  // …and, for a nested page, whether they give its top level, every child being an `@` file — which
+  // is all a `nest:` needs beside them (`pageRecordToYml`).
+  const filesGiveTopOrder = nested && topInOrder && childFiles.every((f) => f.startsWith('@'))
+  return { sections, written, filesGiveOrder, filesGiveTopOrder }
 }
 
 // The name the build reads a section file's section by: its file name without the `@` child mark and
@@ -585,8 +592,12 @@ function listedNames(list) {
 export function existingSectionFile(pageDir, fileBase, stableId, { child = false } = {}) {
   if (!existsSync(pageDir)) return null
   const entries = readdirSync(pageDir).filter((e) => isMarkdownFile(e) && (child || !e.startsWith('@')))
+  // A child is looked for as the build looks for a `nest:` child (`findSectionFile`): `name.md`, then
+  // `@name.md`, then a numbered one. ⛔ Until 2026-10-08 a child went to the first file of its name in
+  // directory order, so `@booking-form.md` came back into a top-level `1-booking-form.md` beside it.
   const found =
     entries.find((e) => basename(e, '.md') === fileBase) ||
+    (child && entries.find((e) => e === `@${fileBase}.md`)) ||
     entries.find((e) => fileSectionName(e) === fileBase) ||
     entries.find((e) => {
       try {
@@ -608,7 +619,7 @@ export function existingSectionFile(pageDir, fileBase, stableId, { child = false
 const PAGE_YML_MANAGED_KEYS = new Set([
   'id', 'title', 'description', 'label', 'keywords', 'index', 'hidden',
   'hideIn', 'knowledge', 'trackSections', 'redirect', 'rewrite', 'layout', 'seo',
-  'query', 'fetch', 'data', 'sections',
+  'query', 'fetch', 'data', 'sections', 'nest',
 ])
 
 // Keys a pull WRITES and never removes — kept out of the managed set on purpose. ⭐ `slug`, a page's
@@ -623,7 +634,7 @@ const PAGE_YML_KEPT_KEYS = new Set(['slug'])
 // 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, { isRoot = false, slug = null, filesGiveOrder = false } = {}) {
+function pageRecordToYml(record, sectionsArray, sourceLocale, existing = null, { isRoot = false, slug = null, filesGiveOrder = false, filesGiveTopOrder = 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`).
@@ -671,22 +682,53 @@ function pageRecordToYml(record, sectionsArray, sourceLocale, existing = null, {
   // their nesting, and anything new is discovered and appended as it would be in a
   // page that was never pulled.
   // ⭐ 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`).
+  // A page with no list gets none where its files' names give the order (`filesGiveOrder`) — nor where
+  // they give the top level and the author's `nest:` the nesting, the form the docs lead with.
   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 (filesGiveTopOrder && nestSays(existing?.nest, sectionsArray)) {
+      // Nothing to list: the files and `nest:` say it, kept below.
     } else if (!filesGiveOrder) {
       y.sections = [...sectionsArray, '...']
     } else if (authored !== undefined) {
       y.sections = authored // `'*'`, which says what no list says
     }
   }
+  // ⭐ `nest:` stays as the author wrote it — unless this pull writes a list that nests: `nest:` wins
+  // over a list's nesting (`content-collector.js::processNesting`), so beside a new one it would put
+  // back the nesting the list carries. ⛔ Until 2026-10-08 a pull added a list to every page that
+  // nested with `nest:`, beside it, saying the same nesting twice — and a nesting changed in the app
+  // came back in the list, where the stale `nest:` overrode it.
+  const listed = y.sections !== undefined && y.sections !== existing?.sections && nestsIn(y.sections)
+  if (existing?.nest !== undefined && !listed) y.nest = existing.nest
   return y
 }
 
+// Whether a `sections:` list nests: an entry that is a parent with its children.
+function nestsIn(list) {
+  return Array.isArray(list) && list.some((entry) => isPlainRecord(entry))
+}
+
+// Whether a page's `nest:` gives exactly the nesting of the sections the pull wrote — each parent the
+// list nests, its children in order, one level down, as the build attaches them to top-level sections.
+function nestSays(nest, list) {
+  if (!isPlainRecord(nest)) return false
+  const parents = list.filter((entry) => isPlainRecord(entry))
+  if (parents.length !== Object.keys(nest).length) return false
+  return parents.every((entry) => {
+    const [parent, children] = Object.entries(entry)[0]
+    return (
+      Array.isArray(nest[parent]) &&
+      children.every((child) => typeof child === 'string') &&
+      JSON.stringify(nest[parent].map(String)) === JSON.stringify(children)
+    )
+  })
+}
+
 // ⛔ A PRUNE MAY ONLY DELETE WHAT A PUSH COULD HAVE SENT. An orphan is a file the
 // incoming document no longer has — but a push reads the tree with the build's own
 // rules (`isMarkdownFile`, `isIgnoredFolder`), so a `_draft.md`, a `README.md`, a
@@ -787,10 +829,12 @@ function writePagesTree(pages, pagesDir, sourceLocale, report, ctx, routePrefix
 
     let sectionsArray = []
     let filesGiveOrder = false
+    let filesGiveTopOrder = 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
+      filesGiveTopOrder = r.filesGiveTopOrder
       report.sections.push(...r.written)
     }
 
@@ -800,7 +844,15 @@ function writePagesTree(pages, pagesDir, sourceLocale, report, ctx, routePrefix
     // owns only 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)
+    const yml = pageRecordToYml(record, sectionsArray, sourceLocale, existing, { isRoot: !routePrefix, slug: pageSlug, filesGiveOrder, filesGiveTopOrder })
+    // ⭐ A `page.yml` with nothing to say is not created: the build reads an empty one as none
+    // (`content-collector.js::readFolderConfig`). ⛔ Until 2026-10-08 a pull wrote `{}` into every page
+    // whose folder had none. An empty `folder.yml` is written still — its presence is folder mode.
+    if (ymlName === 'page.yml' && Object.keys(yml).length === 0 && !existsSync(ymlPath)) {
+      writePagesTree(record.$children || [], pageDir, sourceLocale, report, ctx, route, parentOrderList(ymlPath), canon)
+      continue
+    }
+    writeMergedYaml(ymlPath, yml, PAGE_YML_MANAGED_KEYS)
     report.pages.push(ymlPath)
 
     writePagesTree(record.$children || [], pageDir, sourceLocale, report, ctx, route, parentOrderList(ymlPath), canon)
@@ -1003,6 +1055,82 @@ export function layoutSectionPaths(layoutSections) {
   return out
 }
 
+// The key an area is held under on both sides: its layout's name as the runtime compares it.
+const layoutAreaKey = (layout, area) => `${layoutNameKey(layout || DEFAULT_LAYOUT)}/${area}`
+
+// The areas the author's layout folder holds, by key — read by the build's own reader, so found
+// wherever the build finds them. None for a folder the build refuses.
+function authoredLayoutAreas(layoutBaseDir) {
+  let areas = []
+  try {
+    areas = readLayoutFolderSync(layoutBaseDir, { onWarning: () => {} })
+  } catch {
+    areas = []
+  }
+  return new Map(areas.map((area) => [layoutAreaKey(area.layout, area.area), area]))
+}
+
+// The layout and area a placement names, and the section's id where it names one.
+function placementOf(relPath) {
+  const parts = relPath.split('/')
+  const name = (file) => basename(file, extname(file))
+  if (parts.length === 1) return { layout: DEFAULT_LAYOUT, area: name(parts[0]), id: null }
+  if (parts.length === 2) return { layout: parts[0], area: name(parts[1]), id: null }
+  return { layout: parts[0], area: parts[1], id: fileSectionName(parts[2]) }
+}
+
+/**
+ * ⭐ THE FILES THE AUTHOR KEEPS A LAYOUT'S SECTIONS IN — the area found by the build's own reader
+ * (`readLayoutFolderSync`): one file, at the root or in its layout's folder (`default/footer.md`), or a
+ * folder of section files numbered as the author numbers them. Each placed section → its file: the
+ * author's where the area holds exactly the incoming sections, by name and in order; else the place
+ * `layoutSectionPaths` gives it, as for a clone.
+ * ⛔ Until 2026-10-08 every section went to that place, so a pull into the copy that pushed moved
+ * `layout/default/footer.md` to `layout/footer.md` and renumbered `0-alert.md` and `1-header.md` as
+ * `1-alert.md` and `2-header.md` — beside the old files, or, pruning, in place of them.
+ */
+function authoredLayoutFiles(layoutBaseDir, placed) {
+  const areas = authoredLayoutAreas(layoutBaseDir)
+  const byArea = new Map()
+  for (const entry of placed) {
+    const { layout, area } = placementOf(entry.relPath)
+    const key = layoutAreaKey(layout, area)
+    if (!byArea.has(key)) byArea.set(key, [])
+    byArea.get(key).push(entry)
+  }
+  const fileOf = new Map()
+  for (const [key, entries] of byArea) {
+    const area = areas.get(key)
+    let files = null
+    if (area?.form === 'file' && entries.length === 1) files = [area.files[0]]
+    else if (area?.form === 'folder' && area.files.length === entries.length) {
+      const named = area.files.every((file, i) => fileSectionName(file) === recordStableId(entries[i].record))
+      if (named) files = area.files
+    }
+    entries.forEach((entry, i) => fileOf.set(entry, files ? join(area.dir, files[i]) : join(layoutBaseDir, entry.relPath)))
+  }
+  return fileOf
+}
+
+/**
+ * The file a layout unit — a `layoutSectionPaths` place, relative to the layout folder — is on disk:
+ * that place, else the author's file for the same section (`authoredLayoutFiles`). For a reader that
+ * maps a unit to the file a pull wrote it to (`uniweb`'s `unitFilesOf`).
+ *
+ * @param {string} layoutBaseDir - the site's layout folder
+ * @param {string} relPath - the unit's place, as `layoutSectionPaths` gives it
+ * @returns {string} an absolute path
+ */
+export function layoutUnitFile(layoutBaseDir, relPath) {
+  const placed = join(layoutBaseDir, relPath)
+  if (existsSync(placed)) return placed
+  const { layout, area, id } = placementOf(relPath)
+  const found = authoredLayoutAreas(layoutBaseDir).get(layoutAreaKey(layout, area))
+  if (!found) return placed
+  const file = found.form === 'file' || found.files.length === 1 ? found.files[0] : found.files.find((f) => fileSectionName(f) === id)
+  return file ? join(found.dir, file) : placed
+}
+
 // Delete orphan layout section files not in `keep` — at every depth the layout
 // folder reader reads (`<area>.md`, `<layout>/<area>.md`, `<layout>/<area>/*.md`) —
 // and remove an area or layout folder left empty. Only files the reader treats as
@@ -1045,8 +1173,11 @@ function pruneOrphanLayout(layoutBaseDir, keep, report) {
 // layout and area folders. Pruning is guarded against an empty incoming set.
 function projectLayout(layoutSections, layoutBaseDir, report, prune, ctx) {
   const written = []
-  for (const { record, relPath } of layoutSectionPaths(layoutSections)) {
-    const filePath = join(layoutBaseDir, relPath)
+  const placed = layoutSectionPaths(layoutSections)
+  const fileOf = authoredLayoutFiles(layoutBaseDir, placed)
+  for (const entry of placed) {
+    const { record } = entry
+    const filePath = fileOf.get(entry)
     // A relocation into a new area folder needs the folder first.
     mkdirSync(dirname(filePath), { recursive: true })
     placeByUuid(ctx, record.$uuid, filePath)

package/src/uwx/site.js

@@ -513,10 +513,16 @@ function sectionToRecord(section, index) {
   return rec
 }
 
-// Resolve a section's logical name (`hero`, `card-a`) to its file in `mdFiles`,
-// matching the normal build's conventions: bare or `@`-prefixed, with or without
-// a numeric `N-` prefix. The stable name is the filename minus `@` and `N-`.
+// Resolve a section's logical name (`hero`, `card-a`) to its file in `mdFiles`, in the
+// normal build's order (`content-collector.js::findSectionFile`): `name.md`, then
+// `@name.md`, then the first file whose name is `name` once its `@` and `N-` prefixes
+// are off. ⛔ Until 2026-10-08 this took the first match in file order, so a child
+// `@booking-form.md` that `nest:` names beside a top-level `1-booking-form.md` resolved to
+// the top-level file — already placed, so skipped — and the child was pushed as an
+// orphan at the end of the page, where the build nests it.
 function findSectionFileName(mdFiles, sectionName) {
+  if (mdFiles.includes(`${sectionName}.md`)) return `${sectionName}.md`
+  if (mdFiles.includes(`@${sectionName}.md`)) return `@${sectionName}.md`
   for (const file of mdFiles) {
     const bare = stripAtPrefix(parse(file).name)
     if (parseNumericPrefix(bare).name === sectionName) return file