@uniweb/build 0.44.5 → 0.46.0

package/src/site/content-collector.js

@@ -24,13 +24,13 @@
 import { readFile, readdir, stat } from 'node:fs/promises'
 import { resolveQueriesConfig, toConfigQueries } from './queries-config.js'
 import { parseNumericPrefix, compareByNumericPrefix } from '../utils/numeric-prefix.js'
-import { join, parse, resolve, sep } from 'node:path'
+import { join, parse, relative, resolve, sep } from 'node:path'
 import { existsSync, statSync, realpathSync, readdirSync } from 'node:fs'
 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, toFetchList } from './data-fetcher.js'
+import { parseFetchConfig } from './data-fetcher.js'
 import { resolveExtensionUrls } from './extension-urls.js'
 import { buildTheme, extractFoundationVars } from '../theme/index.js'
 import { resolveDefaultLocale, resolvePublishableLocales, validateLanguageConfig } from '@uniweb/core'
@@ -122,6 +122,51 @@ function extractRouteParam(folderName) {
   return match ? match[1] : null
 }
 
+/**
+ * Folders the build refuses on a route, ruled 2026-09-11 [Diego]:
+ *
+ *   - `[dir]` and `[path]` — `:dir` and `:path` are route variables every
+ *     parametric page already has, so a folder by either name would make one
+ *     name mean two values (and `[path]` is most often a mistyped `[...path]`);
+ *   - any folder inside a `[...path]` folder — the catch-all takes the rest of
+ *     the URL, so a page below it has a route (`/docs/:path*\/edit`) that can
+ *     never match. A folder that holds something other than a page is named
+ *     with a leading `_`, which the walk skips.
+ *
+ * @param {string} name - the folder's name
+ * @param {string} parentRoute - the route of the folder it sits in
+ */
+function assertRouteFolder(name, parentRoute) {
+  if (name === '[dir]' || name === '[path]') {
+    const hint = name === '[path]' ? ' Did you mean `[...path]`, which captures a path of any depth?' : ''
+    throw new Error(
+      `[uniweb] pages: a folder cannot be named \`${name}\` — \`:${name.slice(1, -1)}\` is a route ` +
+        `variable every parametric page already has.${hint}`
+    )
+  }
+  if (typeof parentRoute === 'string' && /\/:[A-Za-z0-9_-]+\*(\/|$)/.test(parentRoute)) {
+    throw new Error(
+      `[uniweb] pages: \`${name}\` sits inside a \`[...path]\` folder (${parentRoute}). The catch-all ` +
+        `takes the rest of the URL, so a page below it could never be reached. Move it beside the ` +
+        `\`[...path]\` folder, or name it \`_${name}\` if it holds something other than a page.`
+    )
+  }
+}
+
+/**
+ * The route param a page nested inside a parametric page binds — its nearest
+ * parametric ancestor's, the DEEPEST `:param` of the route it sits under. Null
+ * when no ancestor is parametric.
+ *
+ * @param {string} parentRoute
+ * @returns {string|null}
+ */
+function inheritedRouteParam(parentRoute) {
+  if (typeof parentRoute !== 'string') return null
+  const params = [...parentRoute.matchAll(/:([A-Za-z0-9_-]+)(?=\/|$)/g)].map((m) => m[1])
+  return params.length ? params[params.length - 1] : null
+}
+
 // ─────────────────────────────────────────────────────────────────
 // Version Detection
 // ─────────────────────────────────────────────────────────────────
@@ -175,27 +220,86 @@ function detectVersions(folderNames) {
 }
 
 /**
- * Desugar a `data:` declaration into a `fetch:` one.
+ * `query:` — the shorthand for `fetch: { query }`, at every level that declares
+ * data: a section's frontmatter, `page.yml`, `folder.yml` and `site.yml`, on the
+ * build and on the sync push alike. It names a query, or a list of them — "fetch
+ * each", one `content.data` key per name (see `parseFetchConfig` for why a
+ * declaration is plural and why that says nothing about request count). Anything
+ * richer — a `limit`, a `where`, a source — is `fetch:`.
  *
- * `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.
+ * ⛔ `data:` WAS THIS KEY until 2026-09-11 [Diego], and it is REFUSED, not
+ * ignored: in frontmatter an unreserved key becomes a section param, so a stale
+ * `data:` would render an empty section and say nothing. The word stays where it
+ * names the data itself — a section type's `meta.js` `data:` (the shape of each
+ * `content.data` key, which fetches nothing) and `content.data`.
  *
- * ⛔ 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.
+ * ⛔ `query:` beside `fetch:` is refused too. It was silent — `fetch:` won, and
+ * the other declaration was dropped with nothing saying so.
+ *
+ * @param {Object|null|undefined} config - the level's authored config
+ * @param {string} where - the file it was authored in, for the message
+ * @returns {Object|Array<Object>|undefined} the level's `fetch:` declaration, as authored
+ */
+export function declaredFetch(config, where) {
+  checkDeclaration(config, where)
+  return config?.fetch ?? fetchFromQueryShorthand(config?.query)
+}
+
+/**
+ * The refusals `declaredFetch` makes, alone — for a reader that must keep the
+ * desugaring inline (the sync push's `settings.fetch`, whose sources
+ * `scripts/gen-emit-surface.mjs` reads off the expression).
  *
- * @param {string|Array<string>|undefined} data
+ * @param {Object|null|undefined} config
+ * @param {string} where
+ */
+export function checkDeclaration(config, where) {
+  if (!config || typeof config !== 'object') return
+  if (config.data !== undefined) {
+    const other = config.query !== undefined ? 'query' : config.fetch !== undefined ? 'fetch' : null
+    throw new Error(
+      other
+        ? `[uniweb] ${where}: \`data:\` is retired, and this file already declares \`${other}:\` — delete the \`data:\` line.`
+        : `[uniweb] ${where}: \`data:\` is retired — the shorthand for \`fetch: { query }\` is now \`query:\`. ` +
+            `Write \`query: ${formatQueryNames(config.data)}\`.`
+    )
+  }
+  if (config.query !== undefined && config.fetch !== undefined) {
+    throw new Error(
+      `[uniweb] ${where}: declare \`query:\` or \`fetch:\`, not both — \`query: x\` is the shorthand for \`fetch: { query: x }\`.`
+    )
+  }
+  if (config.query !== undefined && !isQueryNames(config.query)) {
+    const declaring = config.query && typeof config.query === 'object' && !Array.isArray(config.query)
+    throw new Error(
+      `[uniweb] ${where}: \`query:\` takes a query name or a list of names; anything richer is \`fetch:\` — ` +
+        `e.g. \`fetch: { query: articles, limit: 3 }\`.` +
+        (declaring ? ' Declaring queries? That is `queries:` (in site.yml) or queries.yml.' : '')
+    )
+  }
+}
+
+/**
+ * Desugar a `query:` value: `team` → `{ query: 'team' }`, `[team, articles]` →
+ * one config per name. ⛔ Before 2026-09-02 a list kept `[0]` and dropped the rest
+ * silently — an author writing a list got one dataset and a section rendering
+ * empty.
+ *
+ * @param {string|Array<string>|undefined|null} query - already checked (`checkDeclaration`)
  * @returns {Object|Array<Object>|undefined}
  */
-export function fetchFromDataShorthand(data) {
-  if (!data) return undefined
-  if (Array.isArray(data)) return data.map((query) => ({ query }))
-  return { query: data }
+export function fetchFromQueryShorthand(query) {
+  if (query === undefined || query === null) return undefined
+  if (Array.isArray(query)) return query.map((name) => ({ query: name }))
+  return { query }
 }
 
+const isQueryName = (name) => typeof name === 'string' && name.trim() !== ''
+const isQueryNames = (value) =>
+  isQueryName(value) || (Array.isArray(value) && value.length > 0 && value.every(isQueryName))
+const formatQueryNames = (value) =>
+  isQueryNames(value) ? (Array.isArray(value) ? `[${value.join(', ')}]` : value) : '<name>'
+
 /**
  * Build version metadata from detected versions and page.yml config
  * @param {Array<Object>} detectedVersions - Detected version infos
@@ -235,7 +339,7 @@ function buildVersionMetadata(detectedVersions, pageConfig = {}) {
  * this function reads `site.yml`, `page.yml`, `folder.yml`, `theme.yml` and
  * every section's frontmatter — i.e. every configuration surface an author
  * writes. So a single typo silently discarded that file's entire contribution:
- * page order, nesting, `sections:`, `data:` declarations, theme. **The build
+ * page order, nesting, `sections:`, `query:` declarations, theme. **The build
  * succeeded and shipped a site missing what the author asked for**, with one
  * line on stderr that named no file.
  *
@@ -866,7 +970,6 @@ async function processFileAsPage(filePath, fileName, siteRoot, parentRoute) {
       lastModified: fileStat.mtime?.toISOString() || null,
       isDynamic: false,
       paramName: null,
-      parentSchema: null,
       version: null,
       versionMeta: null,
       versionScope: null,
@@ -921,7 +1024,9 @@ async function processMarkdownFile(filePath, id, siteRoot, defaultStableId = nul
     console.warn(`[content-collector] ${err.message}`)
   }
 
-  const { type, preset, input, props, fetch, data, id: frontmatterId, ...params } = frontMatter
+  // `query`, `fetch` and `data` are never params: `query:` / `fetch:` declare the
+  // section's own data, and a leftover `data:` is refused (`declaredFetch`).
+  const { type, preset, input, props, fetch, query, data, id: frontmatterId, ...params } = frontMatter
 
   // Convert markdown to ProseMirror
   const proseMirrorContent = markdownToProseMirror(markdown)
@@ -929,28 +1034,13 @@ async function processMarkdownFile(filePath, id, siteRoot, defaultStableId = nul
   // Extract @ component references → insets (mutates doc)
   const insets = extractInsets(proseMirrorContent)
 
-  // `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)
+  // `query: team` → `fetch: { query: team }`; a list, one config per name, each
+  // delivered under its own `content.data` key — the one helper every level uses.
+  // Unrelated to a section type's `meta.js` `data:`, which declares the SHAPE of
+  // each `content.data` key and fetches nothing: delivery is default-on, so a
+  // section receives every fetch in the section → page → site cascade whether or
+  // not it names one here.
+  const resolvedFetch = declaredFetch({ fetch, query, data }, relative(siteRoot, filePath))
 
   // Stable ID for scroll targeting: frontmatter id > filename-derived > null
   // This ID is stable across reordering (unlike the positional id)
@@ -1467,12 +1557,19 @@ async function processPage(pagePath, pageName, siteRoot, { isIndex = false, pare
   // Determine route
   // Index pages get the parent route as their canonical route (no dual routes)
   // sourcePath stores the original folder-based path for ancestor checking
-  const isDynamic = isDynamicRoute(pageName)
-  const paramName = isDynamic ? extractRouteParam(pageName) : null
+  // ⭐ A page is PARAMETRIC when its folder is a bracket name or it sits inside
+  // one (ruled 2026-09-11 [Diego]): `pages/members/[slug]/cv/` is `/members/:slug/cv`
+  // and binds its ancestor's `slug`. Every lane — the SPA, the prefetch, the static
+  // build — tells a parametric page by the parameter in its route; this flag says
+  // the same thing to a consumer that reads the flag.
+  const isBracket = isDynamicRoute(pageName)
+  const inheritedParam = isBracket ? null : inheritedRouteParam(parentRoute)
+  const isDynamic = isBracket || inheritedParam !== null
+  const paramName = isBracket ? extractRouteParam(pageName) : inheritedParam
 
   // First, calculate the folder-based route (what the route would be without index handling)
   let folderRoute
-  if (isDynamic) {
+  if (isBracket) {
     // Dynamic routes: /blog/[slug] → /blog/:slug (for route matching);
     // /blog/[...path] → /blog/:path* — the one multi-segment token the matcher knows.
     const token = isCatchAllRoute(pageName) ? ':path*' : `:${paramName}`
@@ -1500,23 +1597,13 @@ async function processPage(pagePath, pageName, siteRoot, { isIndex = false, pare
   const layoutObj = mergeLayoutConfig(inheritedLayout, normalizeLayoutConfig(layoutConfig))
   const resolvedLayoutName = layoutObj.name || null
 
-  // 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) {
-    const [first] = toFetchList(parentFetch)
-    parentSchema = first ? first.as : null
-  }
+  // ⛔ NO `parentSchema`. Which query a parametric page's URL names one record of
+  // — its ROUTE QUERY — is worked out where it is read, by one function every lane
+  // calls (`routeQuery`, `@uniweb/core/fetch-config`): the page's own query, its
+  // parent's, the site's, or its sections' shared key. This emitted a copy chosen
+  // by another rule (the closest ancestor with a query at ANY depth, never the
+  // page's own or the site's), so the URL narrowed nothing, or a key no section
+  // received — measured 2026-09-10. Removed 2026-09-11 [Diego].
 
   return {
     page: {
@@ -1535,10 +1622,9 @@ async function processPage(pagePath, pageName, siteRoot, { isIndex = false, pare
         : {}),
       lastModified: lastModified?.toISOString(),
 
-      // Dynamic route metadata
+      // Parametric route metadata
       isDynamic,
-      paramName, // e.g., "slug" from [slug]
-      parentSchema, // e.g., "articles" - the data array to iterate over
+      paramName, // e.g., "slug" from [slug]; a nested page's ancestor's
 
       // Version metadata (if within a versioned section)
       version: versionContext?.version || null,
@@ -1579,12 +1665,8 @@ async function processPage(pagePath, pageName, siteRoot, { isIndex = false, pare
         priority: seo.priority || null
       },
 
-      // Data fetching
-      // Support 'data:' shorthand at page level
-      // data: team → fetch: { query: team }
-      fetch: parseFetchConfig(
-        pageConfig.fetch || fetchFromDataShorthand(pageConfig.data)
-      ),
+      // Data fetching — `fetch:`, or the `query:` shorthand (`declaredFetch`)
+      fetch: parseFetchConfig(declaredFetch(pageConfig, relative(siteRoot, join(pagePath, 'page.yml')))),
 
       hasContent: hierarchicalSections.length > 0,
       sections: hierarchicalSections
@@ -1872,6 +1954,7 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
     // Process subdirectories
     for (const folder of orderedFolders) {
       const { name: entry, path: entryPath, dirConfig, dirMode, mountedContentMode, childOrderConfig, childLayout } = folder
+      assertRouteFolder(entry, parentRoute)
       const isIndex = entry === indexName
       const effectiveLayout = mergeLayoutConfig(parentLayout, childLayout)
 
@@ -1930,7 +2013,6 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
           lastModified: null,
           isDynamic: false,
           paramName: null,
-          parentSchema: null,
           version: versionContext?.version || null,
           versionMeta: versionContext?.versionMeta || null,
           versionScope: versionContext?.scope || null,
@@ -1947,7 +2029,10 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
             changefreq: dirConfig.seo?.changefreq || null,
             priority: dirConfig.seo?.priority || null
           },
-          fetch: parseFetchConfig(dirConfig.fetch) || null,
+          // ⭐ `declaredFetch`, as every other level: this read `dirConfig.fetch`
+          // alone until 2026-09-11, so a container's `folder.yml` shorthand reached
+          // a backend on `push` and was dropped from a static build.
+          fetch: parseFetchConfig(declaredFetch(dirConfig, relative(siteRoot, join(entryPath, 'folder.yml')))) || null,
           hasContent: false,
           sections: [],
           order: typeof dirConfig.order === 'number' ? dirConfig.order : undefined
@@ -2001,6 +2086,7 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
   // Second pass: process each page folder
   for (const folder of orderedFolders) {
     const { name: entry, path: entryPath, dirConfig, dirMode, mountedContentMode, childOrderConfig, childLayout } = folder
+    assertRouteFolder(entry, parentRoute)
     const isIndex = entry === indexPageName
     const effectiveLayout = mergeLayoutConfig(parentLayout, childLayout)
 
@@ -2024,7 +2110,6 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
         lastModified: null,
         isDynamic: false,
         paramName: null,
-        parentSchema: null,
         version: versionContext?.version || null,
         versionMeta: versionContext?.versionMeta || null,
         versionScope: versionContext?.scope || null,
@@ -2039,7 +2124,12 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
           changefreq: dirConfig.seo?.changefreq || null,
           priority: dirConfig.seo?.priority || null
         },
-        fetch: null,
+        // ⭐ The folder's own declaration, as the folder-mode container above and
+        // every other level read it. ⛔ This was `fetch: null` until 2026-09-11:
+        // a `folder.yml` here lost its `fetch:` (and its shorthand) on a static
+        // build while `push` carried it, so its pages had the folder's data on a
+        // hosted site and none on an exported one.
+        fetch: parseFetchConfig(declaredFetch(dirConfig, relative(siteRoot, join(entryPath, 'folder.yml')))) || null,
         hasContent: false,
         sections: [],
         order: typeof dirConfig.order === 'number' ? dirConfig.order : undefined
@@ -2051,8 +2141,11 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
         pages.push(containerPage)
       }
 
+      // The container's own fetch config, or the parent's — as the folder-mode
+      // container above passes it.
       const childDirPath = mounts?.get(entry) || entryPath
-      const subResult = await collectPagesRecursive(childDirPath, containerRoute, siteRoot, childOrderConfig, parentFetch, versionContext, 'pages', null, effectiveLayout)
+      const containerFetch = containerPage.fetch || parentFetch
+      const subResult = await collectPagesRecursive(childDirPath, containerRoute, siteRoot, childOrderConfig, containerFetch, versionContext, 'pages', null, effectiveLayout)
       pages.push(...subResult.pages)
       assetCollection = mergeAssetCollections(assetCollection, subResult.assetCollection)
       iconCollection = mergeIconCollections(iconCollection, subResult.iconCollection)
@@ -2616,7 +2709,9 @@ export async function collectSiteContent(sitePath, options = {}) {
   // `publishLanguages` is authoring/publish intent — it has no runtime
   // consumer and never ships in a payload (the visitor runtime is
   // list-unaware; the sync lane reads site.yml directly, not this output).
-  const { publishLanguages: _publishLanguages, ...runtimeSiteConfig } = siteConfig
+  // The `query:` shorthand ships as `config.fetch`, desugared below; carried raw
+  // it would sit beside `config.queries`, the declarations, and read as one.
+  const { publishLanguages: _publishLanguages, query: _query, ...runtimeSiteConfig } = siteConfig
   // ⛔ `$`-prefixed keys are the project's BACKEND-SCOPED state — `$uuid`, `$org`,
   // `$backend`, `$services`, `$secrets` — and this payload is a PUBLISHED artifact
   // that a visitor can fetch. They have no runtime reader (nothing in core, runtime
@@ -2660,7 +2755,7 @@ export async function collectSiteContent(sitePath, options = {}) {
       `${distinctFailures.length} file${distinctFailures.length === 1 ? '' : 's'} could not be parsed as YAML:\n` +
         `${lines.join('\n')}\n\n` +
         `  Each one contributed NOTHING to this build — page order, nesting,\n` +
-        `  sections:, data: and theme settings in these files were dropped.\n` +
+        `  sections:, query: and theme settings in these files were dropped.\n` +
         `  Fix them and rebuild; the dev server reports the same files without failing.`
     )
   }
@@ -2680,13 +2775,12 @@ export async function collectSiteContent(sitePath, options = {}) {
       ...(publishFilterActive && Array.isArray(siteConfig.languages)
         ? { languages: publishable }
         : {}),
-      // ⛔ `data:` IS THE SHORTHAND FOR `fetch:` AND BOTH LANES MUST READ IT.
+      // ⛔ `query:` IS THE SHORTHAND FOR `fetch:` AND BOTH LANES MUST READ IT.
       // This read `siteConfig.fetch` alone until 2026-09-09, so a site-level
-      // `data: articles` reached a backend on the sync lane and was silently
-      // ignored on a static build — the works-on-one-lane shape. The page level
-      // has always used this helper (`pageConfig.fetch || fetchFromDataShorthand(…)`);
-      // the site level simply never did.
-      fetch: parseFetchConfig(siteConfig.fetch || fetchFromDataShorthand(siteConfig.data)),
+      // shorthand reached a backend on the sync lane and was silently ignored on
+      // a static build — the works-on-one-lane shape. Every level reads it
+      // through `declaredFetch` now.
+      fetch: parseFetchConfig(declaredFetch(siteConfig, 'site.yml')),
       fetcher: warnRetiredFetcherKeys(siteConfig.fetcher),
       // NOTE: `intelligence.yml` was read here and emitted as `config.intelligence`.
       // Removed 2026-08-12 — the assistant surface is `site.yml::assistant`, which
@@ -2835,6 +2929,7 @@ function buildRouteTranslations(pages, { defaultLocale = 'en', languages = null
 }
 
 export {
+  assertRouteFolder,
   buildRouteTranslations,
   extractItemName,
   parseWildcardArray,

package/src/site/data-fetcher.js

@@ -20,7 +20,7 @@ import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { existsSync } from 'node:fs'
 import yaml from 'js-yaml'
-import { matchWhere, sortRecords, queryDataUrl } from '@uniweb/core'
+import { matchWhere, sortRecords, queryDataUrl, applyScope } from '@uniweb/core'
 
 /**
  * Infer schema name from path or URL
@@ -115,10 +115,16 @@ export function applyWhere(items, where) {
  */
 export function applyPostProcessing(data, config) {
   if (!data || !Array.isArray(data)) return data
-  if (!config.where && !config.sort && !config.limit) return data
+  if (!config.scope && !config.where && !config.sort && !config.limit) return data
 
   let result = data
 
+  // `scope` first — the folder branch the rest of the query reads, over each
+  // record's placement (`path`), as the runtime's default fetcher applies it.
+  if (typeof config.scope === 'string' && config.scope) {
+    result = applyScope(result, config.scope)
+  }
+
   // Apply where-object predicate first (new path)
   if (config.where) {
     result = applyWhere(result, config.where)
@@ -176,16 +182,50 @@ const RECOGNIZED_FETCH_KEYS = {
   // dropped in the one way the author could not see: no warning, and a plausible
   // key inferred from the path in its place. It has its own message below, since
   // "unrecognized" understates a key that used to work.
+  // ⭐ `scope` is recognized since 2026-09-11, when a folder branch became `scope:`
+  // on both lanes and `where: { path: { under } }` was retired in its favour. It
+  // was dropped here as "unrecognized" until then, so a page could not narrow a
+  // query to a branch at all.
   query: new Set([
     'query', 'as', 'prerender', 'merge', 'transform',
-    'where', 'limit', 'sort', 'detailPage',
+    'scope', 'where', 'limit', 'sort', 'detailPage',
   ]),
   source: new Set([
     'path', 'url', 'as', 'prerender', 'merge', 'transform', 'detail',
-    'detailPage', 'where', 'limit', 'sort',
+    'detailPage', 'scope', 'where', 'limit', 'sort',
   ]),
 }
 
+/**
+ * ⛔ `under` IS RETIRED (2026-09-11 [Diego]) — refused, like every retired spelling
+ * here, because an ignored predicate is a silently wrong answer. It existed for
+ * `where: { path: { under: X } }`, a folder branch written before a query had
+ * `scope:`; a branch is `scope: X` now, on both lanes, and the evaluator no longer
+ * knows the operator, so a `where` still carrying it would match nothing.
+ *
+ * @param {Object|undefined} where
+ * @param {string} context - where the declaration sits, for the message
+ */
+export function refuseUnder(where, context) {
+  const walk = (node) => {
+    if (Array.isArray(node)) {
+      node.forEach(walk)
+      return
+    }
+    if (!node || typeof node !== 'object') return
+    for (const [key, value] of Object.entries(node)) {
+      if (value && typeof value === 'object' && !Array.isArray(value) && Object.prototype.hasOwnProperty.call(value, 'under')) {
+        const instead = key === 'path' && typeof value.under === 'string'
+          ? `Write \`scope: ${JSON.stringify(value.under)}\` — the same folder branch, on every lane.`
+          : 'A folder branch is `scope:`; `under` is no longer an operator.'
+        throw new Error(`[uniweb] ${context}: \`where: { ${key}: { under: … } }\` is retired. ${instead}`)
+      }
+      walk(value)
+    }
+  }
+  walk(where)
+}
+
 // Keys that are neither recognized nor merely unknown: they USED to work, and a
 // generic "unrecognized key" line understates that. Each has a dedicated message
 // naming its replacement, so this table only has to keep the generic report from
@@ -234,9 +274,9 @@ export function toFetchList(fetch) {
 }
 
 /**
- * Parse a `fetch:` (or desugared `data:`) declaration.
+ * Parse a `fetch:` (or desugared `query:`) declaration.
  *
- * ⭐ **A LIST MEANS "FETCH EACH".** `data: [team, articles]` declares two needs
+ * ⭐ **A LIST MEANS "FETCH EACH".** `query: [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.
@@ -300,6 +340,7 @@ export function parseFetchConfig(fetch) {
         'per-instance refinement of the ancestor fetch, under its current name.'
     )
   }
+  refuseUnder(fetch.where, 'fetch')
 
   // Refine config: { refine: true, detail: false, limit: 3 }
   // No URL — merges with the parent fetch config at runtime; only carries
@@ -368,7 +409,8 @@ export function parseFetchConfig(fetch) {
       prerender: fetch.prerender ?? true,
       merge: fetch.merge ?? false,
       transform: fetch.transform,
-      // Query operators
+      // Query operators — a fetch's own override the named query's, per field
+      scope: fetch.scope,
       where: fetch.where,
       limit: fetch.limit,
       sort: fetch.sort,
@@ -389,6 +431,7 @@ export function parseFetchConfig(fetch) {
     detail,
     detailPage,
     // Query operators
+    scope,
     where,
     limit,
     sort,
@@ -413,6 +456,7 @@ export function parseFetchConfig(fetch) {
     // Canonical detail page for a list card's href (page:<stable_id>).
     detailPage,
     // Query operators
+    scope,
     where,
     limit,
     sort,

package/src/site/fetch-shapes.js

@@ -69,3 +69,57 @@ export function authorableFetch(fetch) {
   }
   return out
 }
+
+// ── `query:` or `fetch:` — the key a projection writes back ─────────────────────
+//
+// An author declares a level's data with `fetch:` or with its shorthand, `query:`
+// (`query: team` ≡ `fetch: { query: team }`). The wire carries only the desugared
+// form, so it cannot say which key was typed — and a pull must give back the
+// authored KEY as well as the value (the round-trip law of the sync format). So a
+// projection writes back the key the file already uses, and a file it creates gets
+// `query:` whenever the declaration is nothing but query names — the form the
+// docs teach. The declaration keys are one group: exactly one is written, and a
+// file holding both is refused by the build.
+
+/** The keys that declare a level's data: the long form, its shorthand, and the retired shorthand. */
+export const DECLARATION_KEYS = Object.freeze(['query', 'fetch', 'data'])
+
+/**
+ * The query names a declaration consists of, when that is ALL it says — what
+ * `query:` can express. Keys the build derives or defaults beside a query (`path`,
+ * `url`, `as` equal to the name, `prerender: true`, `merge: false`) say nothing an
+ * author wrote; any other key makes it a `fetch:`.
+ *
+ * @param {object|object[]} fetch - a declaration (or a list) off the wire
+ * @returns {string|string[]|null} the name(s), or null when `query:` cannot say it
+ */
+export function queryNamesOf(fetch) {
+  const nameOf = (one) => {
+    if (!one || typeof one !== 'object' || typeof one.query !== 'string' || one.query === '') return null
+    for (const [key, value] of Object.entries(one)) {
+      if (key === 'query' || key === 'path' || key === 'url') continue
+      if (key === 'as' && value === one.query) continue
+      if (key === 'prerender' && value === true) continue
+      if (key === 'merge' && value === false) continue
+      return null
+    }
+    return one.query
+  }
+  if (!Array.isArray(fetch)) return nameOf(fetch)
+  const names = fetch.map(nameOf)
+  return names.length > 0 && names.every((n) => n !== null) ? names : null
+}
+
+/**
+ * The declaration to write back, and under which key.
+ *
+ * @param {object|object[]} wireFetch - the level's `fetch` off the wire
+ * @param {object|null} [existing] - the authored file's current keys; null for a new file
+ * @returns {{ key: 'query'|'fetch', value: string|string[]|object|object[] }}
+ */
+export function authorableDeclaration(wireFetch, existing = null) {
+  const fetch = Array.isArray(wireFetch) ? wireFetch.map((one) => authorableFetch(one)) : authorableFetch(wireFetch)
+  const names = queryNamesOf(fetch)
+  const typedFetch = !!existing && typeof existing === 'object' && existing.fetch !== undefined
+  return names !== null && !typedFetch ? { key: 'query', value: names } : { key: 'fetch', value: fetch }
+}