@uniweb/build 0.53.0 → 0.54.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.53.0",
+  "version": "0.54.1",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -58,14 +58,14 @@
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
     "@uniweb/content-reader": "^1.2.5",
-    "@uniweb/schemas": "^0.3.3",
-    "@uniweb/theming": "^0.1.15",
     "@uniweb/content-writer": "^0.3.4",
     "@uniweb/projections": "^0.7.3",
-    "@uniweb/semantic-parser": "^1.4.1"
+    "@uniweb/semantic-parser": "^1.4.1",
+    "@uniweb/schemas": "^0.3.3",
+    "@uniweb/theming": "^0.1.15"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "^0.26.5"
+    "@uniweb/runtime": "^0.26.6"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.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.26.5",
-    "@uniweb/core": "^0.29.4"
+    "@uniweb/core": "^0.29.5",
+    "@uniweb/runtime": "^0.26.6"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/prerender.js

@@ -1095,9 +1095,10 @@ export async function prerenderSite(siteDir, options = {}) {
       // ⭐ `renderer.render` IS the sequence this loop used to spell out —
       // renderPage → classify → injectPageContent. It was moved into
       // `@uniweb/runtime/ssr` because an SSR isolate assembles the same three steps
-      // per request, and two hand-written copies of one sequence 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.
+      // for the page a visit starts on, and two hand-written copies of one sequence
+      // 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)
 
       if (result.outcome === 'failed') {

package/src/site/content-collector.js

@@ -1714,14 +1714,18 @@ async function processPage(pagePath, pageName, siteRoot, { isIndex = false, pare
 }
 
 /**
- * Determine the index page name from ordering config
+ * The homepage ONE config declares: the first named `pages:` entry, else `index:`.
+ * `undefined` when it declares none; `null` when its first `pages:` entry names
+ * nothing usable, which has always meant "no homepage" rather than "fall through".
  *
- * @param {Object} orderConfig - { pages: [...], index: 'name' } from parent
- * @param {Array} availableFolders - Array of { name, order } for folders at this level
- * @returns {string|null} The folder name that should be the index, or null
+ * The within-file rule, in one place — a level's config and each of the root's two
+ * configs (`rootOrderConfig`) are read by it alike.
+ *
+ * @param {Object} [config] - `{ pages, index }` as authored
+ * @returns {string|null|undefined}
  */
-function determineIndexPage(orderConfig, availableFolders) {
-  const { pages: pagesArray, index: indexName } = orderConfig || {}
+function declaredHomepage(config) {
+  const { pages: pagesArray, index: indexName } = config || {}
 
   // 1. Explicit pages array - first non-'...' item is index
   if (Array.isArray(pagesArray) && pagesArray.length > 0) {
@@ -1733,9 +1737,69 @@ function determineIndexPage(orderConfig, availableFolders) {
   }
 
   // 2. Explicit index property
-  if (indexName) {
-    return indexName
+  return indexName || undefined
+}
+
+/**
+ * The homepage a level's order config names. The root's was already decided across
+ * its two configs, and arrives as `homepage` (`rootOrderConfig`); any other level
+ * that promotes one — a folder promoted to `/`, the latest version of a scope at the
+ * root — names it in its own config.
+ */
+function homepageOf(orderConfig) {
+  return orderConfig && 'homepage' in orderConfig ? orderConfig.homepage : declaredHomepage(orderConfig)
+}
+
+/**
+ * The site's TOP LEVEL — its order and its homepage — from the two configs that can
+ * declare it: the site config (`site.yml`, or a document profile's own file) and the
+ * pages directory's own config (`pages/folder.yml`, or `pages/page.yml`).
+ *
+ * ⭐ The pages directory's config is read as a MOUNTED directory's is: the content's
+ * own declaration, under the site's. Every other directory's config orders its
+ * children, and a mounted one's does too — but the root's was read for its mode
+ * alone until 2026-09-19, so a content repository that orders itself kept its order
+ * mounted below the root and lost it as the whole pages directory: alphabetical,
+ * and in folder mode with no homepage at all.
+ *
+ * ⛔ THE HOMEPAGE IS DECIDED PER CONFIG, NOT PER KEY. Within one file the first
+ * `pages:` entry beats `index:`, as it always has; across the two, whichever form the
+ * site config uses beats the pages directory's. Merged key by key, a `pages:` list
+ * from the pages directory would override a `site.yml` `index:`. The order is the
+ * site config's `pages:`, else the pages directory's.
+ *
+ * ⚖️ `pages:` and `index:` ONLY. The root has no container page, so the keys that
+ * describe one (`title`, `seo`, …) mean nothing here — a repository carries them for
+ * when it is mounted below the root. And `layout:` stays the site config's alone: a
+ * site's layout travels on the sync lane as that file's own value, verbatim, so a
+ * second source would render on a static build and nowhere else.
+ *
+ * @param {{ pages?: Array, index?: string }} [site] - the site config's own order keys
+ * @param {Object} [root] - the pages directory's config, as `readFolderConfig` read it
+ * @returns {{ pages: Array|undefined, index: string|undefined, homepage: string|null|undefined }}
+ */
+export function rootOrderConfig(site = {}, root = {}) {
+  const listed = (value) => Array.isArray(value) && value.length > 0
+  const fromSite = declaredHomepage(site)
+  const homepage = fromSite !== undefined ? fromSite : declaredHomepage(root)
+  return {
+    pages: listed(site?.pages) ? site.pages : listed(root?.pages) ? root.pages : undefined,
+    index: homepage || undefined,
+    homepage,
   }
+}
+
+/**
+ * Determine the index page name from ordering config
+ *
+ * @param {Object} orderConfig - { pages: [...], index: 'name' } from parent
+ * @param {Array} availableFolders - Array of { name, order } for folders at this level
+ * @returns {string|null} The folder name that should be the index, or null
+ */
+function determineIndexPage(orderConfig, availableFolders) {
+  // 1–2. The first named `pages:` entry, else `index:` (`declaredHomepage`).
+  const declared = homepageOf(orderConfig)
+  if (declared !== undefined) return declared
 
   // 3. Fallback: lowest order value, or first alphabetically
   // IMPORTANT: Dynamic route folders (e.g., [slug]) can never be index pages
@@ -1953,11 +2017,7 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
     // pages: controls order only and every folder keeps its natural route.
     let indexName = null
     if (parentRoute === '/') {
-      if (pagesParsedFM && pagesParsedFM.before.length > 0) {
-        indexName = extractItemName(pagesParsedFM.before[0])
-      } else {
-        indexName = orderConfig?.index || null
-      }
+      indexName = homepageOf(orderConfig) ?? null
     }
 
     // Add md-file-pages
@@ -2505,21 +2565,22 @@ export async function collectSiteContent(sitePath, options = {}) {
     }
   }
 
+  // Root content mode default comes from the profile (folder mode for
+  // documents, page mode for sites). A folder.yml/page.yml in the pages root
+  // overrides the profile default per readFolderConfig.
+  const { mode: rootContentMode, config: rootFolderConfig } = await readFolderConfig(pagesPath, profile.defaultMode)
+
   // Extract page ordering config from the top-level config.
   // Document profile reads the `content:` field (with `pages:` as a back-compat
   // alias); site profile reads `pages:`. Either way the internal field name is
   // `pages` so collectPagesRecursive doesn't need to care about profile.
-  const siteOrderConfig = {
+  // ⭐ Layered over the pages directory's own `pages:` / `index:` — see `rootOrderConfig`.
+  const siteOrderConfig = rootOrderConfig({
     pages: profile.orderField === 'pages'
       ? siteConfig.pages
       : (siteConfig[profile.orderField] ?? siteConfig.pages),
     index: siteConfig.index
-  }
-
-  // Root content mode default comes from the profile (folder mode for
-  // documents, page mode for sites). A folder.yml/page.yml in the pages root
-  // overrides the profile default per readFolderConfig.
-  const { mode: rootContentMode } = await readFolderConfig(pagesPath, profile.defaultMode)
+  }, rootFolderConfig)
 
   // Collect layout areas from the layout/ directory, read from the site alone
   const { layouts, assetCollection: layoutAssets, iconCollection: layoutIcons } =

package/src/uwx/site-diff.js

@@ -64,8 +64,9 @@ const ownContent = (record, ...childKeys) => {
  * the projector would write it to.
  *
  * Paths use the conventional `pages/` and `layout/` roots. A site that relocates
- * them via `info.paths` still gets stable, unique keys — only the displayed prefix
- * would differ from disk, which is a labelling nicety, not a correctness issue.
+ * them via `site.yml::paths` (`settings.paths` on the wire) still gets stable, unique
+ * keys — only the displayed prefix would differ from disk, which is a labelling
+ * nicety, not a correctness issue.
  *
  * @returns {Map<string, object>} path → the unit's own record
  */

package/src/uwx/site-dirs.js

@@ -0,0 +1,32 @@
+// Where a site's pages and layout live — ONE definition for the push, which reads
+// the tree from here (`site.js`), and the pull, which writes it back here
+// (`site-project.js`). A leaf module so the pull does not import the push.
+
+import { join, resolve } from 'node:path'
+
+/**
+ * `site.yml::paths.pages` / `paths.layout`, else `pages/` and `layout/` — resolved
+ * as the build resolves them (`site/content-collector.js`).
+ *
+ * ⛔ The pull read this from the pulled document's `info.paths` until 2026-09-19.
+ * `paths` moved to the `settings` Section on 2026-09-09 and that reader did not
+ * move with it, so it read as absent: every pull wrote pages to `pages/` and layout
+ * to `layout/` whatever the site declared, while the build and the next push kept
+ * reading the declared directory — untouched by the pull, and recorded by it as
+ * current.
+ *
+ * ⭐ Reading `site.yml` rather than the document is the fix, not a detour: it is the
+ * file both readers use, and the pull writes the document's `settings.paths` into it
+ * before it places a single page.
+ *
+ * @param {string} siteRoot
+ * @param {object|null} siteYml - the parsed `site.yml`
+ * @returns {{ pagesDir: string, layoutDir: string }}
+ */
+export function siteContentDirs(siteRoot, siteYml) {
+  const paths = siteYml?.paths
+  return {
+    pagesDir: paths?.pages ? resolve(siteRoot, paths.pages) : join(siteRoot, 'pages'),
+    layoutDir: paths?.layout ? resolve(siteRoot, paths.layout) : join(siteRoot, 'layout'),
+  }
+}

package/src/uwx/site-project.js

@@ -46,6 +46,7 @@ import { createTranslationCollector, writeLocaleTranslations, writeFreeformTrans
 import { buildFreeformPath } from '../i18n/freeform.js'
 import { unwrapLocalized, unwrapLocalizedList } from './backfill.js'
 import { LOCALIZED_FIELD_ASSUMPTION } from './localize.js'
+import { siteContentDirs } from './site-dirs.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
@@ -607,24 +608,35 @@ function pageRecordToYml(record, sectionsArray, sourceLocale, existing = null) {
   return y
 }
 
-// Delete `<name>.md` files in `pageDir` whose stableId isn't in `keep`.
+// ⛔ 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
+// `_partials/` folder or a `.git/` directory never reaches the backend and can never
+// come back in a pulled document. Judged by "not in the incoming set" alone, every
+// one of them was an orphan and a default pull DELETED it — the `.git/` of a pages
+// directory that is its own clone included. The same two rules decide both sides
+// now, which is also what the layout prune below already did.
+
+// Delete the section files in `pageDir` whose stableId isn't in `keep`.
 function pruneOrphanSectionFiles(pageDir, keep, report) {
   if (!existsSync(pageDir)) return
   for (const entry of readdirSync(pageDir)) {
-    if (extname(entry).toLowerCase() !== '.md') continue
+    if (!isMarkdownFile(entry)) continue
     if (keep.has(basename(entry, extname(entry)))) continue
     const p = join(pageDir, entry)
+    if (!statSync(p).isFile()) continue
     unlinkSync(p)
     report.deleted.push(p)
   }
 }
 
-// Delete subdirectories of `pagesDir` whose name isn't an incoming page dir.
+// Delete the page directories in `pagesDir` whose name isn't an incoming page dir.
 function pruneOrphanPageDirs(pagesDir, keepDirs, report) {
   if (!existsSync(pagesDir)) return
   for (const entry of readdirSync(pagesDir)) {
+    if (isIgnoredFolder(entry) || keepDirs.has(entry)) continue
     const p = join(pagesDir, entry)
-    if (!statSync(p).isDirectory() || keepDirs.has(entry)) continue
+    if (!statSync(p).isDirectory()) continue
     rmSync(p, { recursive: true, force: true })
     report.deleted.push(p)
   }
@@ -870,11 +882,11 @@ export function siteContentDocumentToProject({ document, siteRoot, sourceLocale
   // localized scalars during the page walk.
   const ctx = { siteRoot, oldIndex: readPullIndex(siteRoot), newIndex: {}, report, collector, sourceLocale }
 
-  const paths = document?.info?.paths || {}
-  const pagesDir = paths.pages ? join(siteRoot, paths.pages) : join(siteRoot, 'pages')
+  // 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')))
   projectPages(document?.pages, pagesDir, sourceLocale, report, prune, ctx)
-
-  const layoutBaseDir = paths.layout ? join(siteRoot, paths.layout) : join(siteRoot, 'layout')
   projectLayout(document?.layout_sections, layoutBaseDir, report, prune, ctx)
 
   report.locales = writeLocaleTranslations(siteRoot, collector.byLocale)

package/src/uwx/site.js

@@ -57,6 +57,7 @@ import {
   fetchFromQueryShorthand,
   assertRouteFolder,
   mountEntriesOf,
+  rootOrderConfig,
 } from '../site/content-collector.js'
 import { refuseBinding, refuseUnder, refuseOutsideLanguage, warnDuplicateBindings } from '../site/data-fetcher.js'
 import { readLayoutFolder } from '../site/layout-folder.js'
@@ -69,6 +70,7 @@ import { loadFreeformTranslation } from '../i18n/freeform.js'
 import { upsertYamlScalar } from './yaml-upsert.js'
 import { resolveQueriesConfig } from './queries-config.js'
 import { resolveSelfScope } from './self-scope.js'
+import { siteContentDirs } from './site-dirs.js'
 
 const SITE_ENTITY_KEY = 'site-content' // one content entity per site project
 
@@ -545,8 +547,7 @@ async function collectPageSectionsNested(pageDir, siteRoot, pageConfig) {
   }
 
   // Top-level sections: every NON-`@` markdown file, in order. `@`-prefixed files
-  // are children, pulled in via their parent's `nest:` above (an orphaned `@`
-  // file with no parent is simply omitted — it stays out of the document).
+  // are children, pulled in via their parent's `nest:` above.
   const seen = new Set()
   const sections = []
   for (const file of mdFiles) {
@@ -555,13 +556,33 @@ async function collectPageSectionsNested(pageDir, siteRoot, pageConfig) {
     sections.push(await buildSection(file, seen))
   }
 
+  // An `@` file no `nest:` claimed is an ORPHAN, and the build keeps it — appended
+  // as a top-level section, with a warning, "to avoid silent data loss" (`processPage`,
+  // `site/content-collector.js`). Mirrored exactly: at the end, in file order, with no
+  // children of its own. ⛔ This lane omitted it until 2026-09-19, and a pull of the
+  // result then DELETED the file — on disk and absent from the document, it read as
+  // something removed upstream.
+  for (const file of mdFiles) {
+    if (!isChildSection(file) || seen.has(file)) continue
+    seen.add(file)
+    const stableDefault = parseNumericPrefix(stripAtPrefix(parse(file).name)).name
+    const { section } = await processMarkdownFile(join(pageDir, file), String(seen.size), siteRoot, stableDefault)
+    section.subsections = []
+    sections.push(section)
+  }
+
   return sections.map((s, i) => sectionToRecord(s, i))
 }
 
 // A folder-mode folder's `.md` files are pages to the build and nothing to this
 // lane. Name every one of them, so the shortfall is visible at push time rather
 // than by reading the backend's store or opening the published site.
-async function warnFolderModePagesSkipped(dirPath, siteRoot) {
+//
+// `source` is `readFolderConfig`'s: a folder with no config of its own is in folder
+// mode because a `folder.yml` above it put it there, and the message says so —
+// "it is a folder-mode folder (`folder.yml`)" over a folder that has none would send
+// the author looking for a file that does not exist.
+async function warnFolderModePagesSkipped(dirPath, siteRoot, source = 'folder.yml') {
   let files
   try {
     files = (await readdir(dirPath)).filter(isMarkdownFile)
@@ -570,18 +591,33 @@ async function warnFolderModePagesSkipped(dirPath, siteRoot) {
   }
   if (files.length === 0) return
   const where = relative(siteRoot, dirPath)
+  const why = source === 'inherited'
+    ? 'it is a folder-mode folder (it has no `folder.yml` or `page.yml` of its own, so it inherits folder mode from the `folder.yml` above it)'
+    : 'it is a folder-mode folder (`folder.yml`)'
   console.warn(
     `uwx/site: ${files.length} page(s) in \`${where}\` will NOT be pushed — ` +
-      `it is a folder-mode folder (\`folder.yml\`), and pushing \`.md\`-as-pages ` +
+      `${why}, and pushing \`.md\`-as-pages ` +
       `is not implemented on the sync lane. A build renders them; the backend ` +
       `will not have them.\n` +
       files.map((f) => `  - ${where}/${f}`).join('\n') +
       `\n  To publish them, make each one a page-mode directory ` +
       `(\`<name>/page.yml\` + its section files). To ship them as they are, ` +
-      `use \`uniweb export\` or \`uniweb deploy --host <adapter>\`.`
+      `use \`uniweb export\` or \`uniweb deploy --host <adapter>\`.` +
+      REPUBLISH_CLAUSE
   )
 }
 
+// A push sends the page tree as ONE entity (see site-diff.js), so a republish does
+// not merge: the shorter document becomes the whole tree. Measured by the backend
+// lane 2026-09-18 against a current `uniwebd` — 49 stored pages replaced by 2, the
+// publish reporting success. Both skip warnings carry this, because "will not be
+// pushed" reads as "you publish short" when the real cost on an already-published
+// site is that live pages are REMOVED.
+const REPUBLISH_CLAUSE =
+  `\n  ⚠ If this site has been published before, a push REPLACES its whole page ` +
+  `tree — pages already live that are missing here are REMOVED, and the publish ` +
+  `still reports success.`
+
 // Recursively build the `pages` tree: each record carries its fields, its inline
 // `page_sections` (page mode only), and its child pages under `$children`.
 async function walkPagesNested(ctx, dirPath, parentSlugPath, inheritedMode, parentConfig, isRoot) {
@@ -597,7 +633,16 @@ async function walkPagesNested(ctx, dirPath, parentSlugPath, inheritedMode, pare
     assertRouteFolder(f.dirName, insideCatchAll ? '/:path*' : '/')
     const dyn = f.dirName.match(DYNAMIC_RE)
     const slug = dyn ? dyn[1] : f.name
-    const mode = f.source === 'folder.yml' ? 'folder' : 'page'
+    // ⭐ THE BUILD'S ANSWER, NOT A SECOND ONE. `readFolderConfig` has already resolved
+    // this folder's mode — a `folder.yml` here, a `page.yml` here, or neither and
+    // INHERITED from its parent — and that resolved mode is exactly what the build
+    // reads (`site/content-collector.js`). ⛔ This line tested the config file's NAME
+    // until 2026-09-19, so a folder with no config under a folder-mode parent — the
+    // documented cascade, one `folder.yml` at the top of a docs tree — was pushed as
+    // ONE page whose sections were its `.md` files while the build rendered each as a
+    // page of its own. Nothing warned, and a pull then wrote a `page.yml` into the
+    // folder, converting the author's own site to the wrong shape.
+    const mode = f.internalMode === 'pages' ? 'folder' : 'page'
     const slugPath = parentSlugPath ? `${parentSlugPath}/${slug}` : slug
 
     const data = buildPageData(f.config, {
@@ -632,7 +677,7 @@ async function walkPagesNested(ctx, dirPath, parentSlugPath, inheritedMode, pare
       // measured 2026-09-18, a 49-page documentation site published 2 pages with
       // every CLI instrument reporting success [measured:backend, channel with
       // backend, and reproduced here against the same site].
-      await warnFolderModePagesSkipped(f.path, siteRoot)
+      await warnFolderModePagesSkipped(f.path, siteRoot, f.source)
     }
 
     const children = await walkPagesNested(ctx, f.path, slugPath, f.internalMode, f.config, false)
@@ -1384,7 +1429,8 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   // left in an old site.yml is inert — nothing reads it, so nothing sends it.
   // (uwx-format.md → info.url.)
 
-  const ctx = { siteRoot, siteIndex: siteYml.index, sourceLocale, translations }
+  // `siteIndex` — the homepage — joins below, once the pages directory's own config is read.
+  const ctx = { siteRoot, sourceLocale, translations }
   // ⛔ ONE `paths:` CONVENTION, TWO READERS, AND THIS ONE IS A STRICT SUBSET.
   // The build honours sub-mounts — `paths: { pages/<segment>: <dir> }`, through
   // `resolveMounts`/`mountEntriesOf` in `site/content-collector.js` — and this
@@ -1394,25 +1440,43 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   // a site whose entire corpus was one sub-mount: 49 pages built, 2 pushed.
   // Deferred by design for now (bidirectional-sync.md); warned about here so it
   // is not also silent.
+  //
+  // The same two directories the pull writes back to — see `siteContentDirs`.
+  const { pagesDir: pagesPath, layoutDir } = siteContentDirs(siteRoot, siteYml)
   for (const [segment] of mountEntriesOf(siteYml.paths)) {
+    // Only a LOCAL stub (`pages/<segment>/`, the folder that gives a mounted route its
+    // layout) is walked, so the route arrives as an empty container; with no stub,
+    // nothing here stands for the route and it is not sent at all. ⚠️ The message
+    // said "empty container" in both cases until 2026-09-19.
+    const fate = existsSync(join(pagesPath, segment))
+      ? 'will be pushed as an empty container'
+      : 'will not be pushed at all'
     console.warn(
       `uwx/site: \`paths: { pages/${segment}: … }\` is NOT read on the sync lane — ` +
-        `\`${segment}\` will be pushed as an empty container and none of the mounted ` +
+        `\`${segment}\` ${fate} and none of the mounted ` +
         `pages will reach the backend. A build mounts it normally. Inline the ` +
         `directory under \`pages/${segment}/\` to push it, or ship the site with ` +
-        `\`uniweb export\` / \`uniweb deploy --host <adapter>\`.`
+        `\`uniweb export\` / \`uniweb deploy --host <adapter>\`.` +
+        REPUBLISH_CLAUSE
     )
   }
-  const pagesPath = siteYml.paths?.pages
-    ? join(siteRoot, siteYml.paths.pages)
-    : join(siteRoot, 'pages')
-  const pages = existsSync(pagesPath)
-    ? await walkPagesNested(ctx, pagesPath, '', 'sections', siteYml, true)
-    : []
-
-  const layoutDir = siteYml.paths?.layout
-    ? join(siteRoot, siteYml.paths.layout)
-    : join(siteRoot, 'layout')
+  let pages = []
+  if (existsSync(pagesPath)) {
+    // The root has a mode too, read as the build reads it (`rootContentMode`):
+    // `pages/folder.yml` puts the whole site in folder mode, and every folder with no
+    // config of its own inherits it. ⛔ This walk started in page mode unconditionally
+    // until 2026-09-19, so such a site's top-level `.md` pages were dropped without a
+    // word and its top-level folders were pushed as pages of sections.
+    const { mode: rootMode, source: rootSource, config: rootConfig } = await readFolderConfig(pagesPath, 'sections')
+    if (rootMode === 'pages') await warnFolderModePagesSkipped(pagesPath, siteRoot, rootSource)
+    // The top level's order and homepage, decided by the build's own function: the
+    // site's `pages:` / `index:` over the pages directory's own. ⛔ The homepage read
+    // `index:` alone until 2026-09-19, so a site naming it by its first `pages:` entry
+    // — as the build does — pushed no homepage at all.
+    const top = rootOrderConfig({ pages: siteYml.pages, index: siteYml.index }, rootConfig)
+    pages = await walkPagesNested({ ...ctx, siteIndex: top.homepage }, pagesPath, '', rootMode, { pages: top.pages }, true)
+  }
+
   const layoutSections = await collectLayoutNested(layoutDir, siteRoot)
 
   // Wrap each section's content into its per-locale form (source doc + target

package/src/validate-data.js

@@ -28,7 +28,8 @@ import { existsSync } from 'node:fs'
 import { join, resolve, basename } from 'node:path'
 import yaml from 'js-yaml'
 import { YAML_OPTIONS } from './utils/yaml-schema.js'
-import { queryNameFromUrl, siteReaches, declaredKeys, fillDeclaredKeys } from '@uniweb/core'
+import { queryNameFromUrl, declaredKeys, fillDeclaredKeys, fetchLevels, pageRouteQuery } from '@uniweb/core'
+import { parentRouteOf } from '@uniweb/core/route-match'
 
 import { validateItem, isStaticallyCheckable, validateBound } from '@uniweb/schemas/conform'
 import { validateAndNormalizeSchema } from './resolve-data-schema.js'
@@ -105,7 +106,26 @@ export async function validateDataInputs({ siteRoot, foundationPath }) {
   const deferred = []
 
   const byRoute = new Map((site.pages || []).map((p) => [p.route, p]))
+  // ⭐ The parent by the ONE parent rule, not the declared field alone: a payload may omit
+  // `parent`, and reading it raw gives a page no parent here while every other lane infers one —
+  // so the site's fetch reached pages it does not reach, and a parent's reached none.
+  const parentOf = (page) => {
+    if (!page?.route) return null
+    const route = parentRouteOf(page.route, { declared: page.parent ?? null, has: (r) => byRoute.has(r) })
+    return route ? byRoute.get(route) ?? null : null
+  }
+  const access = {
+    routeOf: (p) => p?.route,
+    parentOf,
+    fetchOf: (p) => p?.fetch ?? null,
+    sectionsOf: (p) => p?.sections,
+    site: config.fetch,
+  }
   for (const page of site.pages || []) {
+    const parent = parentOf(page)
+    // Its route query, when it is on a parametric route — a page nested inside one included,
+    // which is a level this check did not have.
+    const route = pageRouteQuery(page, access)
     walkSections(page.sections || [], (section) => {
       const type = section.type
       if (!type) return
@@ -115,10 +135,11 @@ export async function validateDataInputs({ siteRoot, foundationPath }) {
       // same function the entity store delivers by — so a `post: '@std/article'` key
       // filled by an `articles` fetch is checked against `@std/article`, and a fetch that
       // fills no declared key is not checked at all, since no component receives it. The
-      // levels are the section's own fetch, its page's, its parent page's and — for a
-      // top-level page — the site's (`siteReaches`).
+      // levels are the rule's, so this check sees what the render sees (`fetchLevels`,
+      // `@uniweb/core/page-data`) — ⛔ it wrote its own list until 2026-09-19, which read only
+      // the declared parent and had no route binding for a nested page.
       const declared = declaredKeys(bindings)
-      const levels = [section.fetch, page.fetch, byRoute.get(page.parent)?.fetch, siteReaches(page.parent) ? config.fetch : null]
+      const levels = fetchLevels({ own: section.fetch, page: page.fetch, parent, route, site: config.fetch })
       const inputs = collectInputs(levels)
       const held = nodesOfType(section.content, 'dataBlock').map((node) => node.attrs?.tag).filter(Boolean)
       const fills = fillDeclaredKeys(declared, levels, { queries: config.queries, held })