@uniweb/build 0.34.0 → 0.36.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.34.0",
+  "version": "0.36.0",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -59,15 +59,15 @@
     "js-yaml": "^4.1.0",
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
-    "@uniweb/schemas": "^0.2.13",
-    "@uniweb/content-reader": "^1.2.4",
-    "@uniweb/theming": "^0.1.15",
     "@uniweb/semantic-parser": "^1.4.0",
-    "@uniweb/projections": "^0.5.5",
-    "@uniweb/content-writer": "^0.3.4"
+    "@uniweb/content-writer": "^0.3.4",
+    "@uniweb/theming": "^0.1.15",
+    "@uniweb/content-reader": "^1.2.4",
+    "@uniweb/schemas": "^0.2.13",
+    "@uniweb/projections": "^0.5.7"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "^0.13.6"
+    "@uniweb/runtime": "^0.14.0"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -76,7 +76,7 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "^0.17.0"
+    "@uniweb/core": "^0.19.0"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/prerender.js

@@ -12,7 +12,7 @@ import { existsSync, readdirSync, statSync } from 'node:fs'
 import { join, dirname, resolve } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { resolveDefaultLocale, isDataUrl } from '@uniweb/core'
-import { executeFetch, mergeDataIntoContent } from './site/data-fetcher.js'
+import { executeFetch, mergeDataIntoContent, toFetchList } from './site/data-fetcher.js'
 import { shouldSplitContent } from './site/split-content.js'
 import { FONT_LINKS_MARKER } from './site/head-markers.js'
 import { getAdapter } from './hosts/index.js'
@@ -98,11 +98,13 @@ async function executeAllFetches(siteContent, siteDir, onProgress, localeInfo) {
     ? { siteRoot: localeInfo.distDir, publicDir: '.' }
     : fetchOptions
 
-  // 1. Site-level fetch
-  const siteFetch = siteContent.config?.fetch
-  if (siteFetch && siteFetch.prerender !== false) {
-    const cfg = localizeFetch(siteFetch)
-    const opts = cfg !== siteFetch ? localizedFetchOptions : fetchOptions
+  // 1. Site-level fetch. ⛔ `toFetchList` rather than a property read: a `fetch:`
+  // or `data:` LIST parses to an array, and `siteFetch.prerender` on one is
+  // `undefined` — which passes the `!== false` test and then fetches nothing.
+  for (const oneFetch of toFetchList(siteContent.config?.fetch)) {
+    if (oneFetch.prerender === false) continue
+    const cfg = localizeFetch(oneFetch)
+    const opts = cfg !== oneFetch ? localizedFetchOptions : fetchOptions
     onProgress(`  Fetching site data: ${cfg.path || cfg.url}`)
     const result = await executeFetch(cfg, opts)
     if (result.data && !result.error) {
@@ -114,20 +116,25 @@ async function executeAllFetches(siteContent, siteDir, onProgress, localeInfo) {
   const pageFetchedData = new Map()
 
   for (const page of siteContent.pages || []) {
-    // Page-level fetch
-    const pageFetch = page.fetch
-    if (pageFetch && pageFetch.prerender !== false) {
-      const cfg = localizeFetch(pageFetch)
-      const opts = cfg !== pageFetch ? localizedFetchOptions : fetchOptions
+    // Page-level fetch — every declaration on the page.
+    for (const oneFetch of toFetchList(page.fetch)) {
+      if (oneFetch.prerender === false) continue
+      const cfg = localizeFetch(oneFetch)
+      const opts = cfg !== oneFetch ? localizedFetchOptions : fetchOptions
       onProgress(`  Fetching page data for ${page.route}: ${cfg.path || cfg.url}`)
       const result = await executeFetch(cfg, opts)
       if (result.data && !result.error) {
         fetchedData.push({ config: cfg, data: result.data, _scope: page.route })
-        // Store for dynamic route expansion
-        pageFetchedData.set(page.route, {
-          schema: pageFetch.schema,
-          data: result.data,
-        })
+        // ⚖️ Dynamic-route expansion consumes ONE query — a `[slug]` template
+        // expands over a single record set. With several declared, the first
+        // that prerenders is the route query, matching `parentSchema` in the
+        // collector; `expandDynamicPages` is what reads this back.
+        if (!pageFetchedData.has(page.route)) {
+          pageFetchedData.set(page.route, {
+            schema: oneFetch.as,
+            data: result.data,
+          })
+        }
       }
     }
 
@@ -295,17 +302,18 @@ async function processSectionFetches(sections, fetchOptions, onProgress) {
   if (!sections || !Array.isArray(sections)) return
 
   for (const section of sections) {
-    // Execute section-level fetch
-    const sectionFetch = section.fetch
-    if (sectionFetch && sectionFetch.prerender !== false) {
+    // Execute every section-level fetch. Each merges under its own key, so
+    // several accumulate into one `parsedContent.data` — the same keyed map the
+    // runtime's EntityStore builds.
+    for (const sectionFetch of toFetchList(section.fetch)) {
+      if (sectionFetch.prerender === false) continue
       onProgress(`  Fetching section data: ${sectionFetch.path || sectionFetch.url}`)
       const result = await executeFetch(sectionFetch, fetchOptions)
       if (result.data && !result.error) {
-        // Merge fetched data into section's parsedContent
         section.parsedContent = mergeDataIntoContent(
           section.parsedContent || {},
           result.data,
-          sectionFetch.schema,
+          sectionFetch.as,
           sectionFetch.merge
         )
       }

package/src/site/content-collector.js

@@ -32,7 +32,7 @@ import yaml from 'js-yaml'
 import { collectSectionAssets, mergeAssetCollections, collectConfigAssets } from './assets.js'
 import { collectSectionIcons, mergeIconCollections, buildIconManifest } from './icons.js'
 import { normalizeHideIn, dropUnpublishedPages } from './nav-visibility.js'
-import { parseFetchConfig } from './data-fetcher.js'
+import { parseFetchConfig, toFetchList } from './data-fetcher.js'
 import { resolveExtensionUrls } from './extension-urls.js'
 import { buildTheme, extractFoundationVars } from '../theme/index.js'
 import { resolveDefaultLocale, resolvePublishableLocales, validateLanguageConfig } from '@uniweb/core'
@@ -127,6 +127,28 @@ function detectVersions(folderNames) {
   return versions
 }
 
+/**
+ * Desugar a `data:` declaration into a `fetch:` one.
+ *
+ * `data: team` → `{ query: 'team' }`; `data: [team, articles]` → one config per
+ * entry. ⭐ **A list means "fetch each"** — see `parseFetchConfig` for why the
+ * declaration is plural by necessity and why that is not a statement about
+ * request count.
+ *
+ * ⛔ Before 2026-09-02 a list kept `[0]` and dropped the rest **silently**: no
+ * warning, no error, and the array was not carried forward on the section, so
+ * nothing downstream could recover it. An author writing a list got one dataset
+ * and a section rendering empty.
+ *
+ * @param {string|Array<string>|undefined} data
+ * @returns {Object|Array<Object>|undefined}
+ */
+function fetchFromDataShorthand(data) {
+  if (!data) return undefined
+  if (Array.isArray(data)) return data.map((query) => ({ query }))
+  return { query: data }
+}
+
 /**
  * Build version metadata from detected versions and page.yml config
  * @param {Array<Object>} detectedVersions - Detected version infos
@@ -860,14 +882,28 @@ async function processMarkdownFile(filePath, id, siteRoot, defaultStableId = nul
   // Extract @ component references → insets (mutates doc)
   const insets = extractInsets(proseMirrorContent)
 
-  // Support 'data:' shorthand for collection fetch
-  // data: team → fetch: { query: team }
-  // data: [team, articles] → fetch: { query: team } (first item, others via inheritData)
-  let resolvedFetch = fetch
-  if (!fetch && data) {
-    const queryName = Array.isArray(data) ? data[0] : data
-    resolvedFetch = { query: queryName }
-  }
+  // `data:` shorthand — `data: team` → `fetch: { query: team }`.
+  //
+  // ⛔ **A LIST KEEPS ONLY `[0]`. THE REST ARE INERT.** This comment used to say
+  // *"others via inheritData"*, and that is wrong in a way worth spelling out,
+  // because it read as a mechanism and was copied into a second doc as one.
+  //
+  // `inheritData` is a BOOLEAN OPT-OUT on a section's `meta.js`
+  // (`meta.inheritData === false` → deliver nothing). It never consumed list
+  // elements. What actually happens is that delivery is default-on and
+  // collect-all: `EntityStore._getRequestedSchemas` returns `[]`, so a section
+  // receives EVERY fetch config in the section → page → site cascade whether or
+  // not it named any of them.
+  //
+  // ⇒ So `articles` arrives only if something ELSE already declared a fetch for
+  // it — in which case this section would have received it anyway. **Naming it
+  // here contributes nothing.** Measured 2026-09-02: `data: [team, articles]`
+  // with no other declaration yields exactly one config, `team`, and the array
+  // is not carried forward on the section, so nothing downstream can recover it.
+  //
+  // ⚠️ The list form appears in no `docs/` page, so nothing promises it works.
+  // Whether it should mean "fetch each" or be refused outright is undecided.
+  const resolvedFetch = fetch || fetchFromDataShorthand(data)
 
   // Stable ID for scroll targeting: frontmatter id > filename-derived > null
   // This ID is stable across reordering (unlike the positional id)
@@ -1378,11 +1414,22 @@ async function processPage(pagePath, pageName, siteRoot, { isIndex = false, pare
   // Layout panel visibility (from object form of layout config)
   const layoutObj = typeof layoutConfig === 'object' && layoutConfig !== null ? layoutConfig : {}
 
-  // For dynamic routes, determine the parent's data schema
-  // This tells prerender which data array to iterate over
+  // For dynamic routes, determine the parent's data schema — this tells
+  // prerender which data array to iterate over.
+  //
+  // ⚖️ **A `[slug]` template expands over exactly ONE record set**, so a plural
+  // parent declaration has to resolve to one query here. The first is taken,
+  // matching what prerender records in `pageFetchedData`; the two must agree or
+  // expansion iterates a set the route was not built from.
+  //
+  // ⛔ This is a genuine cardinality constraint, not a limit worth lifting: a
+  // route pattern names one variable, and "which collection does `:slug` index"
+  // has no second answer. A page that needs another dataset alongside its
+  // dynamic one still declares it — plurality is what makes that sayable.
   let parentSchema = null
   if (isDynamic && parentFetch) {
-    parentSchema = parentFetch.schema
+    const [first] = toFetchList(parentFetch)
+    parentSchema = first ? first.as : null
   }
 
   return {
@@ -1450,9 +1497,7 @@ async function processPage(pagePath, pageName, siteRoot, { isIndex = false, pare
       // Support 'data:' shorthand at page level
       // data: team → fetch: { query: team }
       fetch: parseFetchConfig(
-        pageConfig.fetch || (pageConfig.data
-          ? { query: Array.isArray(pageConfig.data) ? pageConfig.data[0] : pageConfig.data }
-          : undefined)
+        pageConfig.fetch || fetchFromDataShorthand(pageConfig.data)
       ),
 
       hasContent: hierarchicalSections.length > 0,

package/src/site/data-fetcher.js

@@ -251,13 +251,13 @@ export function applyPostProcessing(data, config) {
 // not understand, but we can refuse to pretend it was never there. Reported
 // once per key name per process so a 200-record build does not print 200 lines.
 const RECOGNIZED_FETCH_KEYS = {
-  refine: new Set(['refine', 'inherit', 'detail', 'limit', 'sort', 'where', 'filter']),
+  refine: new Set(['refine', 'detail', 'limit', 'sort', 'where', 'filter']),
   query: new Set([
-    'query', 'schema', 'prerender', 'merge', 'transform',
+    'query', 'as', 'schema', 'prerender', 'merge', 'transform',
     'where', 'limit', 'sort', 'detailPage', 'filter',
   ]),
   source: new Set([
-    'path', 'url', 'schema', 'prerender', 'merge', 'transform', 'detail',
+    'path', 'url', 'as', 'schema', 'prerender', 'merge', 'transform', 'detail',
     'detailPage', 'where', 'limit', 'sort', 'filter',
   ]),
 }
@@ -283,16 +283,68 @@ export function _resetUnknownFetchKeyWarnings() {
   warnedUnknownFetchKeys.clear()
 }
 
+/**
+ * Normalize a parsed `fetch` to a list. **Use this at every consumption point.**
+ *
+ * `parseFetchConfig` returns an object for one declaration and an array for
+ * several, so `cfg.path` on a multi-fetch page reads `undefined` rather than
+ * throwing — the silent-empty class. Reaching for this instead of a property is
+ * what keeps that from happening.
+ *
+ * @param {Object|Array|null} fetch - a PARSED fetch (post-`parseFetchConfig`).
+ * @returns {Array<Object>} zero, one, or many configs.
+ */
+export function toFetchList(fetch) {
+  if (!fetch) return []
+  return Array.isArray(fetch) ? fetch : [fetch]
+}
+
+/**
+ * Parse a `fetch:` (or desugared `data:`) declaration.
+ *
+ * ⭐ **A LIST MEANS "FETCH EACH".** `data: [team, articles]` declares two needs
+ * and they land under two keys in `content.data` — a component reads
+ * `content.data.team` and `content.data.articles` independently, so the
+ * declaration is plural by necessity.
+ *
+ * ⚖️ **Plural DECLARATIONS are not plural REQUESTS.** How many round trips this
+ * becomes belongs to the fetcher: `EntityStore` already assembles every config
+ * before dispatching any of them and awaits them together, which is exactly
+ * where a batching source would coalesce. Nothing here should encode a
+ * transport assumption — the file lane genuinely has two artifacts, and most
+ * sources cannot batch at all.
+ *
+ * ⛔ **A one-entry list collapses to an object, deliberately.** The returned
+ * shape reflects the cardinality of the RESULT, not of the input syntax, so
+ * every declaration that resolves to a single fetch is byte-identical to what
+ * this emitted before — the array shape appears only where content could not
+ * previously have worked. (Before 2026-09-02 a list kept `[0]` and discarded the
+ * rest silently, so the only content whose shape changes is content that was
+ * already broken.)
+ *
+ * @param {string|Object|Array|null} fetch
+ * @returns {Object|Array<Object>|null}
+ */
 export function parseFetchConfig(fetch) {
   if (!fetch) return null
 
+  if (Array.isArray(fetch)) {
+    const parsed = fetch.map((f) => parseFetchConfig(f)).filter(Boolean)
+    // Flatten: a nested array is not a meaningful authoring shape, and letting
+    // one through would put an array inside an array where every consumer
+    // expects configs.
+    const flat = parsed.flat()
+    if (flat.length === 0) return null
+    return flat.length === 1 ? flat[0] : flat
+  }
+
   // Simple string: "/data/team.json"
   if (typeof fetch === 'string') {
-    const schema = inferSchemaFromPath(fetch)
+    const inferred = inferSchemaFromPath(fetch)
     return {
       path: fetch,
       url: undefined,
-      schema,
+      as: inferred,
       prerender: true,
       merge: false,
       transform: undefined,
@@ -302,24 +354,30 @@ export function parseFetchConfig(fetch) {
   // Full config object
   if (typeof fetch !== 'object') return null
 
+  // ⛔ THE RETIRED ALIAS IS AN ERROR, NOT A WARNING — same reasoning as
+  // `collection:` below. `inherit: true` was the earlier spelling of
+  // `refine: true`, accepted with a warning from April 2026 and removed on
+  // 2026-09-02. Ignored, `{ inherit: true, limit: 3 }` would fall through to
+  // the source shape, find neither `path` nor `url`, and resolve to null — a
+  // silently empty block.
+  if (fetch.inherit !== undefined) {
+    throw new Error(
+      '[uniweb] fetch: `inherit: true` is retired. Write `refine: true` — the same ' +
+        'per-instance refinement of the ancestor fetch, under its current name.'
+    )
+  }
+
   // Refine config: { refine: true, detail: false, limit: 3 }
   // No URL — merges with the parent fetch config at runtime; only carries
-  // override props. The legacy spelling `inherit: true` is accepted for one
-  // release with a warning, then removed.
+  // override props.
   //
   // Note on build-vs-runtime scope: this parser passes `sort` and `filter`
   // through on refine configs, but the runtime EntityStore only applies
   // `detail`, `limit`, and `order` overrides. `sort` / `filter` on a refine
   // block are currently accepted by the parser but not honored at runtime.
   // Preserved as-is in this rename commit; revisit separately if needed.
-  if (fetch.refine === true || fetch.inherit === true) {
+  if (fetch.refine === true) {
     warnUnknownFetchKeys(fetch, 'refine')
-    if (fetch.inherit === true && fetch.refine !== true) {
-      console.warn(
-        "[uniweb] 'fetch: { inherit: true }' is deprecated; rename to 'fetch: { refine: true }'. " +
-        'Accepted for one release; will be removed in the next minor.'
-      )
-    }
     if (fetch.filter !== undefined) warnFilterDeprecated()
     return {
       refine: true,
@@ -368,10 +426,15 @@ export function parseFetchConfig(fetch) {
       query: fetch.query,
       path: queryDataUrl(fetch.query),
       url: undefined,
-      // The BINDING KEY — the `content.data.<key>` a component reads. Defaults to
-      // the query name, which is why the two were confusable; `query` above now
-      // carries the identity so this one only has to carry the key.
-      schema: fetch.schema || fetch.query,
+      // ⭐ **`as` is the BINDING KEY** — the `content.data.<key>` a component
+      // reads — defaulting to the query name. It was called `schema` until
+      // 2026-09-02, which collided with the MODEL REF of the same name on a
+      // `queries` declaration. `fetch.schema` is still accepted as INPUT, so
+      // content authored before the rename keeps working; it is never emitted.
+      // ⭐ `fetch.schema` here is an AUTHOR's older spelling in a content file —
+      // the same boundary normalization as the source-shape branch below, not
+      // the internal alias (removed 2026-09-02). One name travels inside.
+      as: fetch.as || fetch.schema || fetch.query,
       prerender: fetch.prerender ?? true,
       merge: fetch.merge ?? false,
       transform: fetch.transform,
@@ -391,6 +454,7 @@ export function parseFetchConfig(fetch) {
   const {
     path,
     url,
+    as,
     schema,
     prerender = url ? false : true,
     merge = false,
@@ -413,7 +477,12 @@ export function parseFetchConfig(fetch) {
   return {
     path,
     url,
-    schema: schema || inferSchemaFromPath(path || url),
+    // ⭐ **The one place `schema` is still read, and it is a BOUNDARY
+    // normalization — not the internal alias.** An author may have written
+    // `fetch: { schema: person }` before the 2026-09-02 rename; that is content
+    // on someone's disk, not a field our own packages pass to each other.
+    // Translating it here means one name — `as` — everywhere inside.
+    as: as ?? schema ?? inferSchemaFromPath(path || url),
     prerender,
     merge,
     transform,
@@ -589,7 +658,7 @@ export function mergeDataIntoContent(content, fetchedData, schema, merge = false
  *
  * @param {object[]} configs - Array of normalized fetch configs
  * @param {object} options - Execution options (same as executeFetch)
- * @returns {Promise<Map<string, any>>} Map of schema -> data
+ * @returns {Promise<Map<string, any>>} Map of binding key (`as`) -> data
  */
 export async function executeMultipleFetches(configs, options = {}) {
   if (!configs || configs.length === 0) {
@@ -599,7 +668,7 @@ export async function executeMultipleFetches(configs, options = {}) {
   const results = await Promise.all(
     configs.map(async (config) => {
       const result = await executeFetch(config, options)
-      return { schema: config.schema, data: result.data }
+      return { schema: config.as, data: result.data }
     })
   )
 

package/src/site/fetch-shapes.js

@@ -3,7 +3,7 @@
 // ⛔ WHY THIS EXISTS. A `fetch:` declaration has three shapes, and the keys each one
 // accepts differ (`data-fetcher.js` RECOGNIZED_FETCH_KEYS):
 //
-//   refine      refine · inherit · detail · limit · sort · where · filter
+//   refine      refine · detail · limit · sort · where · filter
 //   query       query · schema · … — and NOT `path`/`url`
 //   source      path · url · schema · …
 
@@ -39,7 +39,7 @@
 /** Which of the three shapes a declaration is — the same order `data-fetcher` uses. */
 export function fetchShapeOf(fetch) {
   if (!fetch || typeof fetch !== 'object') return null
-  if (fetch.refine === true || fetch.inherit === true) return 'refine'
+  if (fetch.refine === true) return 'refine'
   if (fetch.query) return 'query'
   return 'source'
 }

package/src/site/plugin.js

@@ -51,7 +51,7 @@ import { processAssets, rewriteSiteContentPaths } from './asset-processor.js'
 import { processAdvancedAssets } from './advanced-processors.js'
 import { processQueries, writeQueryFiles } from './query-processor.js'
 import { ENTITIES_DIR } from './entity-pool.js'
-import { executeFetch, mergeDataIntoContent } from './data-fetcher.js'
+import { executeFetch, mergeDataIntoContent, toFetchList } from './data-fetcher.js'
 import { shouldSplitContent } from './split-content.js'
 import { FONT_LINKS_MARKER } from './head-markers.js'
 import { collectExtensionAssets } from './emit-extensions.js'
@@ -137,9 +137,9 @@ async function executeDevFetches(siteContent, siteDir) {
   const fetchOptions = { siteRoot: siteDir, publicDir: 'public' }
   const fetchedData = []
 
-  // Site-level fetch
-  const siteFetch = siteContent.config?.fetch
-  if (shouldPrefetchInDev(siteFetch)) {
+  // Site-level fetch — every declaration.
+  for (const siteFetch of toFetchList(siteContent.config?.fetch)) {
+    if (!shouldPrefetchInDev(siteFetch)) continue
     const result = await executeFetch(siteFetch, fetchOptions)
     if (result.data && !result.error) {
       fetchedData.push({ config: siteFetch, data: result.data })
@@ -148,9 +148,9 @@ async function executeDevFetches(siteContent, siteDir) {
 
   // Process each page
   for (const page of siteContent.pages || []) {
-    // Page-level fetch
-    const pageFetch = page.fetch
-    if (shouldPrefetchInDev(pageFetch)) {
+    // Page-level fetch — every declaration.
+    for (const pageFetch of toFetchList(page.fetch)) {
+      if (!shouldPrefetchInDev(pageFetch)) continue
       const result = await executeFetch(pageFetch, fetchOptions)
       if (result.data && !result.error) {
         fetchedData.push({ config: pageFetch, data: result.data })
@@ -176,17 +176,16 @@ async function processDevSectionFetches(sections, fetchOptions) {
   if (!sections || !Array.isArray(sections)) return
 
   for (const section of sections) {
-    // Execute section-level fetch
-    const sectionFetch = section.fetch
-    if (shouldPrefetchInDev(sectionFetch)) {
+    // Execute every section-level fetch, so dev shows what prerender will.
+    for (const sectionFetch of toFetchList(section.fetch)) {
+      if (!shouldPrefetchInDev(sectionFetch)) continue
       const result = await executeFetch(sectionFetch, fetchOptions)
       if (result.data && !result.error) {
-        // Merge fetched data into section's parsedContent (not cascadedData)
-        // This matches prerender behavior - section's own fetch goes to content.data
+        // A section's own fetch goes to content.data, matching prerender.
         section.parsedContent = mergeDataIntoContent(
           section.parsedContent || {},
           result.data,
-          sectionFetch.schema,
+          sectionFetch.as,
           sectionFetch.merge
         )
       }

package/src/uwx/site.js

@@ -220,10 +220,13 @@ function buildPageData(config, ctx) {
   setIf(data, 'rewrite', config.rewrite)
   setIf(data, 'layout', config.layout)
   setIf(data, 'seo', config.seo)
+  // ⭐ A `data:` LIST means "fetch each" — one declaration per entry. Before
+  // 2026-09-02 this kept `[0]` and dropped the rest silently, so the wire
+  // carried one dataset for a page that asked for several.
   let fetch =
     config.fetch ??
     (config.data
-      ? { query: Array.isArray(config.data) ? config.data[0] : config.data }
+      ? (Array.isArray(config.data) ? config.data.map((query) => ({ query })) : { query: config.data })
       : undefined)
   // Resolve the authored `query:` shorthand to the runtime-fetchable
   // `path: /data/<name>.json` (the static convention the default-fetcher uses).
@@ -232,8 +235,14 @@ function buildPageData(config, ctx) {
   // it would never resolve at render (the static build resolves it the same way
   // in site/data-fetcher.js parseFetchConfig). The gateway serves the collection
   // at `<base>/data/<name>.json`.
-  if (fetch && typeof fetch.query === 'string') {
-    const { query, ...rest } = fetch
+  // ⛔ **Mapped, not read.** A `data:`/`fetch:` LIST reaches here as an array, and
+  // `fetch.query` on one is `undefined` — so a property test would skip the
+  // resolution below and put bare `{ query }` entries on the wire with no
+  // `path`, no `as` and no `schema`. That is the silent-empty class: a payload
+  // that arrives, parses, and resolves to nothing.
+  const resolveWireFetch = (one) => {
+    if (!one || typeof one.query !== 'string') return one
+    const { query, ...rest } = one
     // ⭐ BOTH, deliberately, and they are not redundant.
     //
     //   `query` — the author's named query, unresolved. A consumer that can ask
@@ -249,9 +258,9 @@ function buildPageData(config, ctx) {
     // `path` once it has resolved an address — matching parseFetchConfig, which
     // has always returned early on the shorthand.
     //
-    // `schema` (the query name) is BOTH the content.data key and part of the
-    // dataStore cache key (deriveCacheKey hashes {path,url,endpoint,schema,…};
-    // the shorthand is ignored). Mirrors the static build's parseFetchConfig —
+    // `as` (the query name) is BOTH the content.data key and part of the
+    // dataStore cache key (deriveCacheKey hashes {path,url,endpoint,as,…}; the
+    // shorthand is ignored). Mirrors the static build's parseFetchConfig —
     // ⚠️ which it did NOT until 2026-09-02. This line emitted `query` and that
     // one did not, for the same declaration, so `resolveQuerySource` fired on a
     // published site and never on a `--link`-deployed one: same site, two verbs,
@@ -263,8 +272,22 @@ function buildPageData(config, ctx) {
     // validating — so `fetch` is a blob they carry and framework owns its
     // vocabulary. ⇒ There was nothing to coordinate, and inventing a coordination
     // is how a name stays wrong.
-    fetch = { query, path: queryDataUrl(query), schema: query, ...rest }
+    // ⚠️ Owning the vocabulary is not the same as nobody reading it. A backend
+    // that re-implements the render payload for a lane with no build step reads
+    // ONE key out of this blob — `as`, to derive which record set a dynamic route
+    // iterates — and that read went silently empty when the key moved on
+    // 2026-09-02. So `fetch.as` is on the coupled surface even though `fetch`
+    // is carried: a consumer that interprets a name is a reader of it, however
+    // little of the object it looks at.
+    // ⛔ `as`, the BINDING KEY — not to be confused with `schema` at
+    // DECL_EMITTED_ABOVE / `setIf(data,'schema',d.schema)` below, which is a
+    // queries decl's MODEL REF and keeps its name. One word meant both until
+    // 2026-09-02; this is the half that moved, and the compatibility duplicate
+    // that briefly rode alongside it was dropped 2026-09-02 once frontend and
+    // hosting had dropped theirs. ⇒ A site synced before that must be re-pushed.
+    return { query, path: queryDataUrl(query), as: query, ...rest }
   }
+  fetch = Array.isArray(fetch) ? fetch.map(resolveWireFetch) : resolveWireFetch(fetch)
   setIf(data, 'fetch', fetch)
   if (isDynamic) {
     data.is_dynamic = true

package/src/validate-data.js

@@ -37,6 +37,7 @@ import { validateAndNormalizeSchema } from './resolve-data-schema.js'
 // reach it here) even though the implementation moved next to the vocabulary.
 export { validateItem, isStaticallyCheckable } from '@uniweb/schemas/conform'
 import { buildSchema } from './schema.js'
+import { toFetchList } from './site/data-fetcher.js'
 import { resolveFoundationSrcPath } from './utils/foundation-source-root.js'
 import { collectSiteContent } from './site/content-collector.js'
 import { processQueries } from './site/query-processor.js'
@@ -94,6 +95,10 @@ export async function validateDataInputs({ siteRoot, foundationPath }) {
     byQuery = await processQueries(siteRoot, config.queries, config.paths?.entities, basePath)
   }
 
+  // Declared here rather than beside pass 2's other accumulators because pass 1
+  // now writes to it as well — see THE JOIN, RUN THE OTHER WAY below.
+  const setupErrors = []
+
   // Pass 1 — discover unique (file, schema-ref) pairs and who uses each.
   const work = new Map() // pairKey -> { path, ref, schema, users: [{ route, section, key }] }
   const deferred = []
@@ -103,8 +108,47 @@ export async function validateDataInputs({ siteRoot, foundationPath }) {
       const type = section.type
       if (!type) return
       const bindings = foundation[type]?.data
-      for (const input of collectInputs(section, page.fetch, config.fetch)) {
-        const key = input.schema // the content.data KEY (the `fetch.schema` field is mis-named)
+      const inputs = collectInputs(section, page.fetch, config.fetch)
+
+      // ⭐ **THE JOIN, RUN THE OTHER WAY: data arrived, but under no name this
+      // section reads.** Everything below asks "for each input, is there a
+      // binding?". This asks "for each binding, was anything delivered?" — and
+      // the answer was silence until 2026-09-02.
+      //
+      // A section reads `content.data.<key>` for the keys its `meta.js` `data:`
+      // declares. When the page delivers a query under a DIFFERENT name, the
+      // section renders its heading and nothing else: no error, no warning, HTTP
+      // 200, a clean console. Reported by `flows`, measured in a real browser —
+      // two records-backed sections carrying 8 and 6 characters of text beside
+      // static ones carrying 182/572/289/529/99.
+      //
+      // ⚖️ **Narrow on purpose: only when SOMETHING was delivered.** `data:` in
+      // `meta.js` is a hint rather than a delivery gate (`docs/reference/
+      // data-fetching.md`), so a section declaring keys on a page with no data at
+      // all is ordinary and silent. What is not ordinary is a page that fetched
+      // something and a section on it that reads none of it — there the author
+      // demonstrably intended data to arrive and the names did not meet.
+      const declaredKeys = bindings ? Object.keys(bindings) : []
+      if (declaredKeys.length > 0 && inputs.length > 0) {
+        const delivered = inputs.map((i) => i.as).filter(Boolean)
+        if (delivered.length > 0 && !declaredKeys.some((k) => delivered.includes(k))) {
+          setupErrors.push({
+            file: `${page.route || '/'} · ${type}`,
+            message:
+              `section reads ${declaredKeys.map((k) => `content.data.${k}`).join(' or ')}, ` +
+              `but this page delivers ${delivered.map((k) => `\`${k}\``).join(', ')}. ` +
+              `The section will render with no data and nothing else will say so. ` +
+              `Name the query for the key the section reads, or give the section its own ` +
+              `\`fetch: { query: <name> }\`.`,
+            // One user per declared key, so `uniweb validate` can print
+            // `used by /team › Team › data.team` — the key is the thing to rename.
+            users: declaredKeys.map((k) => ({ route: page.route, section: type, key: k })),
+          })
+        }
+      }
+
+      for (const input of inputs) {
+        const key = input.as // the content.data KEY
 
         if (input.url) {
           deferred.push({ route: page.route, section: type, key, reason: 'remote url: source', url: input.url })
@@ -137,7 +181,6 @@ export async function validateDataInputs({ siteRoot, foundationPath }) {
 
   // Pass 2 — validate each unique pair ONCE, attribute findings to its users.
   const violations = []
-  const setupErrors = []
   const schemasSeen = new Set()
   let recordCount = 0
 
@@ -436,9 +479,19 @@ async function loadStandardSchemas() {
  */
 function collectInputs(section, pageFetch, siteFetch) {
   const byKey = new Map()
-  for (const f of [siteFetch, pageFetch, section.fetch]) {
-    if (f && (f.path || f.url) && typeof f.schema === 'string') {
-      byKey.set(f.schema, f)
+  // ⭐ Each level may declare SEVERAL — `data: [team, articles]` — so each is
+  // flattened rather than read. Order is least- to most-specific and `set`
+  // overwrites, which is what makes a section's declaration win the key.
+  for (const source of [siteFetch, pageFetch, section.fetch]) {
+    for (const f of toFetchList(source)) {
+      // ⛔ Gate on the BINDING KEY. A gate on the wrong name silently yields
+      // NOTHING here — no inputs collected, no violations found, a green run —
+      // which is exactly how the rename was caught: the integration test went
+      // from flagging the seeded violations to flagging none.
+      const key = f?.as
+      if (f && (f.path || f.url) && typeof key === 'string') {
+        byKey.set(key, f)
+      }
     }
   }
   return [...byKey.values()]