@uniweb/build 0.79.0 → 0.80.0

package/package.json

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

package/src/foundation/default-layout.js

@@ -0,0 +1,52 @@
+/**
+ * The layout a page renders with when it names none — decided once, by the build, and written
+ * into both artifacts: the entry's `capabilities.defaultLayout`, which the runtime reads
+ * (`Website.getDefaultLayoutName`), and `_self.defaultLayout` in the schema, which an editor
+ * reads to offer a page the areas it will draw. One rule, run once, so the two cannot disagree.
+ *
+ * ⭐ THE RULE [2026-10-07; Diego: "I think the default layout maybe called `default`"]:
+ *
+ *   1. `main.js`'s `defaultLayout`, written as that layout's own name — `DocsLayout` for
+ *      `docs` — so a reader finds it in `_layouts` by key. ⛔ One that names none of the
+ *      foundation's layouts stops the build: at render it fell to the built-in layout with
+ *      nothing saying why.
+ *   2. Else the layout whose name is `default`, by the one naming rule (`layoutNameKey`):
+ *      `Default`, `DefaultLayout`, `default-layout`.
+ *   3. Else none — the runtime's built-in layout, which draws `header`, the body and `footer`.
+ *
+ * ⛔ NOT "the only layout". Under that rule, adding a second layout would change the layout of
+ * every page that names none — a non-local effect nobody asked for. A foundation that means its
+ * one layout as the default says so, as every template does.
+ *
+ * ⛔ *Until 2026-10-07 the build copied the declared value and derived nothing, so a layout named
+ * `Default` was the default only when `main.js` said so — and a reader of the schema finding none
+ * had to guess what the runtime would draw.*
+ *
+ * @module @uniweb/build/foundation/default-layout
+ */
+
+import { findLayoutEntry } from '@uniweb/core/layout-name'
+
+/**
+ * @param {*} declared - `main.js`'s `defaultLayout`, as `loadFoundationConfig` reads it
+ * @param {string[]} layoutNames - the foundation's layouts (`discoverLayoutsInPath`)
+ * @returns {string|null} the layout's own name, or null for the built-in layout
+ * @throws {Error} when `declared` names none of the layouts
+ */
+export function resolveDefaultLayout(declared, layoutNames = []) {
+  const byName = Object.fromEntries((layoutNames || []).map((name) => [name, name]))
+
+  if (declared !== undefined && declared !== null && declared !== '') {
+    const name = typeof declared === 'string' ? findLayoutEntry(byName, declared) : undefined
+    if (name) return name
+    const known = Object.keys(byName)
+    throw new Error(
+      `main.js: \`defaultLayout\` names ${JSON.stringify(declared)}, which is not one of this foundation's layouts` +
+        (known.length > 0 ? ` (${known.join(', ')})` : ' — it has none in src/layouts/') +
+        '. Name one of them, or remove the key: a page that names no layout then renders the built-in ' +
+        'layout, or one named `Default`.'
+    )
+  }
+
+  return findLayoutEntry(byName, 'default') ?? null
+}

package/src/generate-entry.js

@@ -32,6 +32,7 @@ import {
   LAYOUTS_PATH
 } from './schema.js'
 import { extractAllRuntimeSchemas, extractAllLayoutRuntimeSchemas, extractFoundationRuntime } from './runtime-schema.js'
+import { resolveDefaultLayout } from './foundation/default-layout.js'
 import { SCHEMA_EXTENSIONS } from './resolve-data-schema.js'
 
 /**
@@ -124,6 +125,7 @@ function generateEntrySource(components, options = {}) {
     cssPath = null,
     foundationExports = null,
     foundationRuntime = { code: [], data: {} },
+    defaultLayout = null,
     meta = {},
     layouts = {},
     layoutMeta = {},
@@ -188,6 +190,9 @@ function generateEntrySource(components, options = {}) {
       for (const key of foundationRuntime.code) capParts.push(`${key}: _foundationModule.default?.${key}`)
       for (const [key, value] of Object.entries(foundationRuntime.data)) capParts.push(`${key}: ${JSON.stringify(value)}`)
     }
+    // The resolved default, with or without a main.js — a layout named `Default` is one
+    // (`resolveDefaultLayout`), and `_self.defaultLayout` in the schema carries the same name.
+    if (defaultLayout) capParts.push(`defaultLayout: ${JSON.stringify(defaultLayout)}`)
     if (layoutNames.length > 0) {
       capParts.push(`layouts: { ${layoutNames.join(', ')} }`)
     }
@@ -310,6 +315,11 @@ export async function generateEntryPoint(srcDir, outputPath = null, options = {}
   const foundationExports = detectFoundationExports(srcDir)
   const foundationConfig = await loadFoundationConfig(srcDir)
   const foundationRuntime = foundationExports ? extractFoundationRuntime(foundationConfig) : { code: [], data: {} }
+  // Which layout a page that names none renders with — the build's answer, written here and in
+  // the schema's `_self.defaultLayout` (`buildSchema`) from one rule, so the runtime and an editor
+  // agree. It replaces the declared value `extractFoundationRuntime` copied.
+  const defaultLayout = resolveDefaultLayout(foundationConfig.defaultLayout, layoutNames)
+  delete foundationRuntime.data.defaultLayout
 
   // Per-component runtime metadata. ⭐ No data schema is resolved for it: the runtime reads a
   // declared key's ref and nothing of its shape (2026-10-05), so the entry no longer depends on
@@ -329,6 +339,7 @@ export async function generateEntryPoint(srcDir, outputPath = null, options = {}
     cssPath,
     foundationExports,
     foundationRuntime,
+    defaultLayout,
     meta,
     layouts,
     layoutMeta,

package/src/schema.js

@@ -28,6 +28,7 @@ import {
   unnameableIn,
 } from './foundation/derive-supports.js'
 import { RENAMED_SERVICES } from './uwx/services-request.js'
+import { resolveDefaultLayout } from './foundation/default-layout.js'
 import { foundationNameOf, splitFoundationName } from './foundation-name.js'
 import { resolveFoundationSrcDir } from './utils/foundation-source-root.js'
 
@@ -1236,6 +1237,9 @@ export async function buildSchema(srcDir, sectionPaths, derivedSupports = null)
 
   // Discover layouts from src/layouts/
   const layouts = await discoverLayoutsInPath(srcDir)
+  // The layout a page that names none renders with — the entry gets the same answer
+  // (`generate-entry.js`), so an editor reading `_self.defaultLayout` offers what the runtime draws.
+  const defaultLayout = resolveDefaultLayout(foundationConfig.defaultLayout, Object.keys(layouts))
   await refuseFlagsOnListSchemas(
     [
       ...Object.entries(components).map(([name, entry]) => [`${name} (meta.js)`, entry?.data]),
@@ -1260,8 +1264,9 @@ export async function buildSchema(srcDir, sectionPaths, derivedSupports = null)
     }
   }
 
-  // Build _self, stripping the raw extension boolean in favor of normalized role
-  const { extension: _ext, ...configWithoutExtension } = foundationConfig
+  // Build _self, stripping the raw extension boolean in favor of normalized role, and the
+  // declared `defaultLayout` in favor of the resolved one (`resolveDefaultLayout`)
+  const { extension: _ext, defaultLayout: _declaredLayout, ...configWithoutExtension } = foundationConfig
 
   // `supports` is the one identity field the build knows better than the file.
   // `identity.supports` is already normalized (absent stays absent, `[]` stays
@@ -1303,7 +1308,7 @@ export async function buildSchema(srcDir, sectionPaths, derivedSupports = null)
       ...supports,
       ...(name && { name }),
       ...(foundationConfig.description && { description: foundationConfig.description }),
-      ...(foundationConfig.defaultLayout && { defaultLayout: foundationConfig.defaultLayout }),
+      ...(defaultLayout && { defaultLayout }),
       ...(isExtension && { role: 'extension' }),
       // The build's fact, last: which form the entries below hold.
       schemaFormat: SCHEMA_FORMAT,

package/src/site/content-collector.js

@@ -22,7 +22,7 @@
  */
 
 import { readFile, readdir, stat } from 'node:fs/promises'
-import { resolveQueriesConfig, toConfigQueries } from './queries-config.js'
+import { resolveQueriesConfig, toConfigQueries, dataKeyTyping } from './queries-config.js'
 import { isSectionKey } from '@uniweb/schemas/section'
 import { parseNumericPrefix, compareByNumericPrefix } from '../utils/numeric-prefix.js'
 import { isMarkdownFile, isIgnoredFolder } from '../utils/content-files.js'
@@ -2511,13 +2511,17 @@ export async function collectSiteContent(sitePath, options = {}) {
   // merged both, so a declaration in the second file was invisible here: never
   // compiled, `data: <name>` delivering nothing, while sync pushed it fine.
   //
-  // ⭐ `config.queries` — framework's own payload key, framework's own readers.
-  // The backend's projector never emits it (their measurement: 17 `config` keys,
-  // not this one), and hosting renders with framework's code. There was nobody to
-  // coordinate with, which is exactly why it had no excuse to stay wrong.
-  const byQuery = toConfigQueries(
-    (await resolveQueriesConfig(sitePath, { siteYml: siteConfig })).declarations
-  )
+  // ⭐ `config.queries` — what a page's queries are, which a section's keys are filled by. A
+  // backend-served payload carries its own projection of each (`schema`, `where`, `sort`,
+  // `limit`, `scope`) since 2026-09-05. ⛔ This said the backend's projector never emitted it,
+  // which was true only before then.
+  //
+  // ⭐ A query a data key types carries the type, as a push names it (`dataKeyTyping`), so a key
+  // typed `@/post` fills from `articles:` on a static site as it does on a hosted one.
+  const { declarations } = await resolveQueriesConfig(sitePath, { siteYml: siteConfig })
+  const nameDefaulted = Object.values(declarations).some((d) => d?.schemaExplicit === false)
+  const typing = nameDefaulted ? await dataKeyTyping(sitePath, declarations, { siteYml: siteConfig }) : null
+  const byQuery = toConfigQueries(declarations, typing)
   if (byQuery) siteConfig.queries = byQuery
 
   // Record the RESOLVED base (--base > UNIWEB_BASE > site.yml::base) on the

package/src/site/queries-config.js

@@ -41,6 +41,7 @@ import { refuseQueryRoute, refuseLimit, refuseFilter } from './data-fetcher.js'
 import { readFile } from 'node:fs/promises'
 import yaml from 'js-yaml'
 import { YAML_OPTIONS } from '../utils/yaml-schema.js'
+import { dataKeyTypes } from '../uwx/data-key-types.js'
 
 // Read its own YAML rather than importing the site build's helper. That import
 // pointed the wrong way — a config resolver reaching into the collector that
@@ -320,21 +321,73 @@ function refuseMethod(method, where) {
  * held a key a declaration may want for something else [Diego, 2026-09-27]. Until then every
  * query on the payload read `{ name: 'articles', … }` under `articles`.
  *
+ * ⭐ A query that declares no `schema:` and whose records a data key types carries the TYPE —
+ * `articles` → `@/post` (`dataKeyTyping`) — which is what a push names it on the wire
+ * (`uwx/site.js::queriesNested`). The schema a page's query carries is what a section's key is
+ * filled by at render (automatic `as`), so the two lanes fill the same keys. ⛔ Until 2026-10-08 the
+ * static payload carried the name (`@/articles`), and a key typed `@/post` filled on a hosted site
+ * and stayed empty on a static one.
+ *
  * Returns undefined for a site with no queries, so `config.queries`
  * stays absent rather than becoming an empty object — an empty object reads as
  * "declared, and empty" to anything checking for presence.
+ *
+ * @param {object} declarations - `resolveQueriesConfig(…).declarations`
+ * @param {Map<string, string>|null} [typing] - `dataKeyTyping`: name-defaulted ref → its type
  */
-export function toConfigQueries(declarations) {
+export function toConfigQueries(declarations, typing = null) {
   const names = Object.keys(declarations || {})
   if (names.length === 0) return undefined
   const out = {}
   for (const key of names) {
     const { schemaExplicit, name, ...rest } = declarations[key]
-    out[key] = rest
+    const typed = schemaExplicit === false ? typing?.get(rest.schema) : null
+    out[key] = typed ? { ...rest, schema: typed } : rest
   }
   return out
 }
 
+/**
+ * ⭐ THE TYPE A DATA KEY GIVES A NAME — `@/articles` → `@/post` (ruled 2026-09-25 [Diego];
+ * `uwx/data-key-types.js`), decided for the static build as a push decides it
+ * (`uwx/records.js::typedFor`), so both lanes give a query one schema.
+ *
+ * A name-defaulted ref, `@/<name>`, stands for the type of the data key of that name when:
+ *
+ *   - no data schema has the name — `@/<name>` resolves to nothing;
+ *   - the foundation's section types declare the key `<name>` with one type, and it resolves;
+ *   - no query asks for `@/<name>` explicitly — that one is the author's, and fails loudly.
+ *
+ * Then `records/<name>/` holds records of the type, and a query named `<name>` that declares no
+ * schema is a query of it. ⚠️ Where the records live on disk and how their translations are keyed
+ * stay keyed by the name.
+ *
+ * @param {string} siteRoot
+ * @param {object} declarations - `resolveQueriesConfig(…).declarations`, for which refs are explicit
+ * @param {object} [opts]
+ * @param {object} [opts.siteYml] - an already-read site.yml
+ * @returns {Promise<Map<string, string>>} name-defaulted ref → the type; empty when none
+ */
+export async function dataKeyTyping(siteRoot, declarations, opts = {}) {
+  const typing = new Map()
+  const siteYml = opts.siteYml || (await readYamlFile(join(siteRoot, 'site.yml')))
+  const keyTypes = dataKeyTypes(await foundationSections(siteRoot, siteYml))
+  if (keyTypes.size === 0) return typing
+  const explicit = new Set(
+    Object.values(declarations || {})
+      .filter((d) => d && d.schemaExplicit === true)
+      .map((d) => d.schema)
+  )
+  const named = [...keyTypes.keys()].map(defaultSchema)
+  const { schemas } = await resolveRecordSchemas(siteRoot, [...named, ...keyTypes.values()], { siteYml })
+  for (const [key, type] of keyTypes) {
+    const ref = defaultSchema(key)
+    if (schemas[ref] || explicit.has(ref) || !schemas[type]) continue
+    typing.set(ref, type)
+  }
+  return typing
+}
+
 
 /**
  * The data schemas a site's records are shaped by, keyed by ref — each resolved from

package/src/site/query-processor.js

@@ -65,8 +65,8 @@ import { readEntityPool, groupPoolBySchema, poolDirsForSchema } from './entity-p
 import { readRecordsConfig, resolveFolder, folderTreeOrder } from './records-config.js'
 import { isDraftRecord } from './record-draft.js'
 import { refuseNotOneRecord } from './record-file.js'
-import { resolveRecordSchemas, resolveQueriesConfig, foundationSections } from './queries-config.js'
-import { dataKeyTypes } from '../uwx/data-key-types.js'
+import { resolveRecordSchemas, resolveQueriesConfig, dataKeyTyping } from './queries-config.js'
+import { keyOfDefaultRef } from '../uwx/data-key-types.js'
 import { parseFrontmatter } from '../utils/frontmatter.js'
 import { toDeliveredRecord, toStoredRecord, storedPath, briefFieldMap, contentBodyField, misplacedFields, mapReferences, recordLayout } from '@uniweb/schemas/conform'
 import { collectNestedRefs } from '@uniweb/schemas/format'
@@ -1197,10 +1197,24 @@ export async function processQueries(siteDir, queriesConfig, recordsDir, basePat
   const poolBySchema = groupPoolBySchema(pool.entities)
   const recordsRoot = resolve(siteDir, pool.dir)
 
+  // ⭐ A FOLDER NAMED FOR A DATA KEY HOLDS RECORDS OF THE KEY'S TYPE (ruled 2026-09-25 [Diego];
+  // `dataKeyTyping`): `records/articles/`, when no data schema has the name and the foundation types
+  // `articles` as `@/post`, holds `@/post` records — so they join that type's records, as a push
+  // sends them, and any query of `@/post` reads them, as a host answers one. ⛔ Until 2026-10-08 they
+  // stayed under `@/articles`: only a query named `articles` read them, and it carried `@/articles`
+  // on the payload where a push named `@/post`.
+  const typing = await recordTyping(siteDir, queriesConfig, poolBySchema)
+  for (const [ref, type] of typing) {
+    const held = poolBySchema.get(ref)
+    if (!held) continue
+    poolBySchema.delete(ref)
+    poolBySchema.set(type, [...(poolBySchema.get(type) || []), ...held])
+  }
+
   // ⭐ THE DATA SCHEMA EACH QUERY'S RECORDS ARE DELIVERED IN (`deliverRecord`) — resolved
   // from the foundation's source once for every query. A query with none compiles its
   // records as their files hold them.
-  const dataSchemas = options.dataSchemas ?? (await querySchemas(siteDir, queriesConfig))
+  const dataSchemas = options.dataSchemas ?? (await querySchemas(siteDir, queriesConfig, typing))
   const references = referenceHydrator({ poolBySchema, dataSchemas, siteDir, recordsRoot, basePath, includeDrafts })
 
   const results = {}
@@ -1211,6 +1225,9 @@ export async function processQueries(siteDir, queriesConfig, recordsDir, basePat
     // be an empty `/data/<name>.json` standing in for a live source.
     if (config && typeof config === 'object' && config.url !== undefined) continue
     const parsed = parseQueryConfig(name, config)
+    // A query that still names its folder (`@/articles`) is a query of the folder's type.
+    const folderRef = parsed.schema
+    if (parsed.schema && typing.has(parsed.schema)) parsed.schema = typing.get(parsed.schema)
     parsed.poolEntities = parsed.schema ? poolBySchema.get(parsed.schema) || [] : []
     parsed.placements = folder.placements
     parsed.folderRank = folderRank
@@ -1218,7 +1235,7 @@ export async function processQueries(siteDir, queriesConfig, recordsDir, basePat
     parsed.dataSchema = (parsed.schema && dataSchemas[parsed.schema]) || null
     parsed.references = references
     if (parsed.poolEntities.length === 0) {
-      const dirs = parsed.schema ? poolDirsForSchema(parsed.schema) : null
+      const dirs = folderRef ? poolDirsForSchema(folderRef) : null
       console.warn(
         `[query-processor] Query "${name}" matches no records — ` +
           (dirs
@@ -1240,12 +1257,12 @@ export async function processQueries(siteDir, queriesConfig, recordsDir, basePat
  * its records are compiled as their files hold them, which is not the shape a
  * component receives from a host.
  */
-async function querySchemas(siteDir, queriesConfig) {
-  const refs = []
+async function querySchemas(siteDir, queriesConfig, typing = new Map()) {
+  const refs = [...typing.values()]
   for (const config of Object.values(queriesConfig)) {
     if (config && typeof config === 'object' && config.url !== undefined) continue
     const ref = typeof config === 'string' ? config : config?.schema
-    if (typeof ref === 'string') refs.push(ref)
+    if (typeof ref === 'string' && !typing.has(ref)) refs.push(ref)
   }
   const { schemas, failures } = await resolveRecordSchemas(siteDir, refs)
   for (const { ref, message } of failures) {
@@ -1254,28 +1271,25 @@ async function querySchemas(siteDir, queriesConfig) {
         `their files hold them rather than as a component receives them: ${message}`
     )
   }
-  await typeByDataKey(siteDir, queriesConfig, schemas)
   return schemas
 }
 
 /**
- * ⭐ A QUERY NAMED FOR A DATA KEY HOLDS RECORDS OF THE KEY'S TYPE (ruled 2026-09-25 [Diego],
- * `uwx/data-key-types.js`). `articles:` with no `schema:` names `@/articles`; when no data schema
- * has that name while the foundation's section types declare `data: { articles: '@/post' }`, its
- * records are `@/post` records — a push sends them as such, and they are delivered as such here,
- * where they still live and are keyed by the name (`records/articles/`). Never for a schema the
- * query asked for explicitly: that one is the author's, and does not resolve. ⛔ Until 2026-09-27
- * this lane compiled them as if they had no data schema, while a push typed them.
+ * ⭐ WHICH FOLDERS HOLD RECORDS OF A DATA KEY'S TYPE (ruled 2026-09-25 [Diego]): `@/articles` →
+ * `@/post` — `dataKeyTyping`, the rule a push applies, asked only when the site has a folder or a
+ * query it could apply to: a name-defaulted ref, `@/<name>`. ⛔ Until 2026-10-08 this lane typed a
+ * query's RECORDS by aliasing its `@/<name>` to the type's schema, while its query and its folder
+ * kept the name.
  *
  * @param {string} siteDir
- * @param {Object} queriesConfig
- * @param {Object} schemas - resolved data schemas by ref; a typed query's ref is added to it
+ * @param {Object} queriesConfig - what the build compiles (`config.queries`)
+ * @param {Map<string, Array>} poolBySchema - the records, by the ref their folder names
+ * @returns {Promise<Map<string, string>>} name-defaulted ref → the type
  */
-async function typeByDataKey(siteDir, queriesConfig, schemas) {
-  const untyped = Object.entries(queriesConfig).filter(
-    ([name, c]) => c && typeof c === 'object' && c.url === undefined && c.schema === `@/${name}` && !schemas[c.schema]
-  )
-  if (untyped.length === 0) return
+async function recordTyping(siteDir, queriesConfig, poolBySchema) {
+  const candidate = (ref) => typeof ref === 'string' && keyOfDefaultRef(ref) !== null
+  const queried = Object.values(queriesConfig).map((c) => (typeof c === 'string' ? c : c?.schema))
+  if (![...poolBySchema.keys(), ...queried].some(candidate)) return new Map()
   // `config.queries` carries no trace of whether its author wrote the schema; the declarations do.
   let declarations = {}
   try {
@@ -1283,17 +1297,11 @@ async function typeByDataKey(siteDir, queriesConfig, schemas) {
   } catch {
     // a declaration the build refuses is reported where the build reads it
   }
-  const pending = untyped.filter(([name]) => declarations[name]?.schemaExplicit !== true)
-  if (pending.length === 0) return
-  const keyTypes = dataKeyTypes(await foundationSections(siteDir))
-  const wanted = new Map()
-  for (const [name, c] of pending) {
-    const type = keyTypes.get(name)
-    if (type) wanted.set(c.schema, type)
+  try {
+    return await dataKeyTyping(siteDir, declarations)
+  } catch {
+    return new Map() // a foundation that does not read is reported by the build that reads it
   }
-  if (wanted.size === 0) return
-  const { schemas: types } = await resolveRecordSchemas(siteDir, wanted.values())
-  for (const [ref, type] of wanted) if (types[type]) schemas[ref] = types[type]
 }
 
 /**

package/src/uwx/data-key-types.js

@@ -7,8 +7,10 @@
 // records folder (`records/team/`). When no data schema has that name, but the foundation's
 // section types declare the data key of that name with a type — `data: { team: '@/member' }` in a
 // `meta.js` — the records ARE of that type: a push sends them as its entities, and the query names
-// it on the wire. ⛔ Until 2026-09-25 they were read as having no data schema at all and went out
-// as static files, although the one section that reads them declared what they are.
+// it on the wire; the static build names it on the payload and reads them as the type's records
+// (`site/queries-config.js::dataKeyTyping`, since 2026-10-08 — until then the payload named the query
+// `@/team`). ⛔ Until 2026-09-25 they were read as having no data schema at all and went out as
+// static files, although the one section that reads them declared what they are.
 //
 // ⚠️ THIS DECIDES ONLY WHICH DATA SCHEMA THE RECORDS BELONG TO. Where they live on disk, how the
 // site builds them and how their translations are keyed stay keyed by the name (`team`), as the

package/src/uwx/index.js

@@ -88,6 +88,9 @@ export {
   sectionRecordToFile,
   pageSectionsToFiles,
   siteContentDocumentToProject,
+  // 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,
 } from './site-project.js'
 export {
   createTranslationCollector,

package/src/uwx/site-diff.js

@@ -96,8 +96,12 @@ export function collectSiteUnits(doc, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.
 export function walkSiteUnits(doc, cb, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale) {
   const walkSections = (sections, dir) => {
     for (const record of sections || []) {
-      // The projector's own file rule, so a unit's path here is the file it is
-      // written to — including an app-created section named from its `$uuid`.
+      // The projector's own file rule — including an app-created section named from its
+      // `$uuid`. ⚠️ The path NAMES the unit by its id; it is not always the author's file:
+      // a pull writes into an existing `1-about.md` or `@about.md` in place
+      // (`existingSectionFile`), so a reader mapping a unit to disk looks it up there.
+      // (This said "a unit's path here is the file it is written to" until 2026-10-07,
+      // and a push recorded no file for a numbered section.)
       const base = sectionFileBase(record)
       if (base) cb(`${dir}/${base}.md`, record, 'section')
       walkSections(record.$children, dir)

package/src/uwx/site-project.js

@@ -587,7 +587,7 @@ function listedNames(list) {
 //
 // ⛔ 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 } = {}) {
+export 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 =