@uniweb/build 0.44.5 → 0.45.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.44.5",
+  "version": "0.45.0",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -59,13 +59,13 @@
     "yaml": "^2.5.0",
     "@uniweb/content-reader": "^1.2.4",
     "@uniweb/content-writer": "^0.3.4",
-    "@uniweb/projections": "^0.6.0",
-    "@uniweb/semantic-parser": "^1.4.0",
+    "@uniweb/projections": "^0.6.1",
     "@uniweb/schemas": "^0.2.13",
+    "@uniweb/semantic-parser": "^1.4.0",
     "@uniweb/theming": "^0.1.15"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "^0.19.5"
+    "@uniweb/runtime": "^0.20.0"
   },
   "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/core": "^0.24.4"
+    "@uniweb/core": "^0.25.0"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/prerender.js

@@ -11,7 +11,19 @@ import { readFile, writeFile, mkdir } from 'node:fs/promises'
 import { existsSync, readdirSync, statSync } from 'node:fs'
 import { join, dirname, resolve } from 'node:path'
 import { pathToFileURL } from 'node:url'
-import { resolveDefaultLocale, resolveFetchConfigs, joinPathCapture, splitPathCapture } from '@uniweb/core'
+import {
+  resolveDefaultLocale,
+  resolveFetchConfigs,
+  joinPathCapture,
+  routeQuery,
+  sectionFetches,
+  routeParamValue,
+  routeParamName,
+  routeBinding,
+  parentRouteOf,
+  deriveCacheKey,
+} from '@uniweb/core'
+import { routePatternToRegex } from '@uniweb/core/route-match'
 import { executeFetch, mergeDataIntoContent, toFetchList, stripBuildOnlyFetchKeys } from './site/data-fetcher.js'
 import { shouldSplitContent } from './site/split-content.js'
 import { FONT_LINKS_MARKER } from './site/head-markers.js'
@@ -76,7 +88,9 @@ export function resolveExtensionPath(url, distDir, projectRoot, base) {
  * @param {string} [localeInfo.locale] - Active locale code
  * @param {string} [localeInfo.defaultLocale] - Default locale code
  * @param {string} [localeInfo.distDir] - Path to dist directory (where locale-specific data lives)
- * @returns {Object} { pageFetchedData, fetchedData } - Fetched data for dynamic route expansion and DataStore pre-population
+ * @returns {Object} { fetched, fetchedData, bake } - what each level fetched, by binding key
+ *   (for parametric-page expansion); the entries for DataStore pre-population; and a
+ *   baker for the views a concrete parametric page binds to its route
  */
 export async function executeAllFetches(siteContent, siteDir, onProgress, localeInfo) {
   const fetchOptions = { siteRoot: siteDir, publicDir: 'public' }
@@ -111,6 +125,8 @@ export async function executeAllFetches(siteContent, siteDir, onProgress, locale
     : fetchOptions
   const optionsFor = (cfg, oneFetch) => (cfg.path !== oneFetch.path ? localizedFetchOptions : fetchOptions)
   const entry = (cfg, data, scope) => ({ config: cfg, data, meta: { whole: cfg.whole }, _scope: scope })
+  // What each level fetched, by binding key — what `expandDynamicPages` iterates.
+  const fetched = { site: new Map(), pages: new Map(), sections: new Map() }
 
   // 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
@@ -122,11 +138,22 @@ export async function executeAllFetches(siteContent, siteDir, onProgress, locale
     const result = await executeFetch(cfg, optionsFor(cfg, oneFetch))
     if (result.data && !result.error) {
       fetchedData.push(entry(cfg, result.data, '__site__'))
+      if (!fetched.site.has(oneFetch.as)) fetched.site.set(oneFetch.as, result.data)
     }
   }
 
-  // 2. Process each page and track fetched data by route
-  const pageFetchedData = new Map()
+  // 2. Process each page and track fetched data by route and binding key. ⭐ EVERY
+  // key, at every level — the static build expands a parametric page over the
+  // data of its ROUTE QUERY, which may be the page's own, its parent's, the site's
+  // or its sections' (`routeQuery`). ⛔ Until 2026-09-11 this kept only the FIRST
+  // prerendered fetch per page, while the collector named the first DECLARED one
+  // as `parentSchema`: a page whose first query was `prerender: false` expanded
+  // over its second and baked that key, and the SPA narrowed the first.
+  const keep = (byRoute, route, as, data) => {
+    const m = byRoute.get(route) ?? new Map()
+    if (!m.has(as)) m.set(as, data)
+    byRoute.set(route, m)
+  }
 
   for (const page of siteContent.pages || []) {
     // Page-level fetch — every declaration on the page.
@@ -137,34 +164,44 @@ export async function executeAllFetches(siteContent, siteDir, onProgress, locale
       const result = await executeFetch(cfg, optionsFor(cfg, oneFetch))
       if (result.data && !result.error) {
         fetchedData.push(entry(cfg, result.data, page.route))
-        // ⚖️ 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,
-          })
-        }
+        keep(fetched.pages, page.route, oneFetch.as, result.data)
       }
     }
 
     // Process section-level fetches (own fetch → parsedContent.data, not cascaded)
-    await processSectionFetches(page.sections, fetchOptions, onProgress)
+    await processSectionFetches(page.sections, fetchOptions, onProgress, (as, data) => keep(fetched.sections, page.route, as, data))
   }
 
-  return { pageFetchedData, fetchedData }
+  /**
+   * Read one config the runtime resolved for an expanded parametric page — a view
+   * its route binds — into a plain entry; `readRouteBoundViews` files it under
+   * each page that asks for it. Local files only: a remote `url:` is the
+   * browser's, as it is by default. Null when there is nothing to embed.
+   */
+  const bake = async (cfg) => {
+    if (cfg.prerender === false || typeof cfg.path !== 'string') return null
+    const options = isNonDefaultLocale && cfg.path.startsWith(`/${localeInfo.locale}/`) ? localizedFetchOptions : fetchOptions
+    const result = await executeFetch(cfg, options)
+    if (!result.data || result.error) return null
+    return { config: cfg, data: result.data, meta: { whole: cfg.whole } }
+  }
+
+  return { fetched, fetchedData, bake }
 }
 
 /**
- * Expand dynamic pages into concrete pages based on fetched data
- * A dynamic page like /blog/:slug with parent data [{ slug: 'post-1' }, { slug: 'post-2' }]
- * becomes /blog/post-1 and /blog/post-2
+ * Expand parametric pages into concrete pages over their route query's records.
+ * A parametric page like /blog/:slug whose route query holds
+ * [{ slug: 'post-1' }, { slug: 'post-2' }] becomes /blog/post-1 and /blog/post-2.
  *
  * @param {Array} pages - Original pages array
- * @param {Map} pageFetchedData - Map of route -> { schema, data }
+ * @param {{ site?: Map, pages?: Map, sections?: Map }} fetched - what each level
+ *   fetched, by binding key (`executeAllFetches`): `site` key → data; `pages` and
+ *   `sections` route → (key → data)
  * @param {function} onProgress - Progress callback
+ * @param {Object} [stats] - receives `unrouted[route]`, the records with no param value
+ * @param {Object} [options]
+ * @param {Object|Array|null} [options.siteFetch] - the site's `fetch`, the last level of a route query
  * @returns {Array} Expanded pages array with dynamic pages replaced by concrete instances
  */
 /**
@@ -202,7 +239,7 @@ export function localizeRedirectTarget(target, { website, locale, isDefault, rou
   return (website.basePath || '') + withSlash
 }
 
-export function expandDynamicPages(pages, pageFetchedData, onProgress = () => {}, stats = { unrouted: {} }) {
+export function expandDynamicPages(pages, fetched, onProgress = () => {}, stats = { unrouted: {} }, { siteFetch = null } = {}) {
   if (!stats.unrouted) stats.unrouted = {}
   const expandedPages = []
 
@@ -216,6 +253,13 @@ export function expandDynamicPages(pages, pageFetchedData, onProgress = () => {}
   const staticRoutes = new Set(
     pages.filter((p) => !p.isDynamic).map((p) => p.route)
   )
+  const byRoute = new Map(pages.filter((p) => p?.route).map((p) => [p.route, p]))
+  const has = (route) => byRoute.has(route)
+  const levels = {
+    site: fetched?.site ?? new Map(),
+    pages: fetched?.pages ?? new Map(),
+    sections: fetched?.sections ?? new Map(),
+  }
 
   for (const page of pages) {
     if (!page.isDynamic) {
@@ -224,33 +268,55 @@ export function expandDynamicPages(pages, pageFetchedData, onProgress = () => {}
       continue
     }
 
-    // Dynamic page - expand based on parent's data
-    const { paramName, parentSchema } = page
+    // ⭐ THE ROUTE QUERY, by the rule every lane reads it with (`routeQuery`,
+    // `@uniweb/core/fetch-config`), off the parent every lane finds
+    // (`parentRouteOf`) — the page's own query, its parent's, the site's, or its
+    // sections' shared key. The records it expands over are that query's, at the
+    // level it came from. ⛔ Until 2026-09-11 this read `parentSchema` and always
+    // expanded over the parent route's first prerendered fetch.
+    const parentRoute = parentRouteOf(page.route, { declared: page.parent ?? null, has })
+    const parent = parentRoute ? byRoute.get(parentRoute) : null
+    const route = routeQuery({
+      page: page.fetch,
+      parent: parent?.fetch,
+      site: siteFetch,
+      sections: sectionFetches(page.sections),
+    })
 
-    if (!parentSchema) {
-      onProgress(`  Warning: Dynamic page ${page.route} has no parentSchema, keeping as template for runtime`)
+    if (!route) {
+      onProgress(`  Keeping ${page.route} for runtime — no query for its URL to narrow`)
       expandedPages.push(page)
       continue
     }
 
-    // Find the parent's data
-    // The parent route is the route without the :param (or :path*) suffix
-    const catchAll = /\/:path\*$/.test(page.route)
-    const parentRoute = page.route.replace(/\/:[\w]+\*?$/, '') || '/'
-    const parentData = pageFetchedData.get(parentRoute)
+    const data = route.level === 'page' ? levels.pages.get(page.route)?.get(route.key)
+      : route.level === 'parent' ? levels.pages.get(parentRoute)?.get(route.key)
+        : route.level === 'site' ? levels.site.get(route.key)
+          : levels.sections.get(page.route)?.get(route.key)
 
-    if (!parentData || !Array.isArray(parentData.data)) {
-      // No build-time data available (e.g., prerender: false on parent fetch).
+    if (!Array.isArray(data)) {
+      // No build-time data available (e.g., prerender: false on the route query).
       // Keep the dynamic template so the runtime can match it client-side.
       onProgress(`  Keeping dynamic template ${page.route} for runtime (no build-time data)`)
       expandedPages.push(page)
       continue
     }
 
-    const items = parentData.data
-    const schema = parentData.schema
+    const paramName = routeParamName(page.route, page.paramName)
+    const { paramNames, catchAll } = routePatternToRegex(page.route)
 
-    onProgress(`  Expanding ${page.route} → ${items.length} pages from ${schema}`)
+    // A route with a parameter the records cannot fill — `/orgs/:org/members/:slug`
+    // expanded over one query knows no `org` — is matched in the browser.
+    if (paramNames.length > 1) {
+      onProgress(`  Keeping ${page.route} for runtime — it has more than one route parameter`)
+      expandedPages.push(page)
+      continue
+    }
+
+    const items = data
+    const key = route.key
+
+    onProgress(`  Expanding ${page.route} → ${items.length} pages from ${key}`)
 
     // ⛔ COUNTED, not only logged per record. A record with no value for the
     // route's param gets no page — correct — but "Skipping item without slug"
@@ -261,12 +327,15 @@ export function expandDynamicPages(pages, pageFetchedData, onProgress = () => {}
 
     // Create a concrete page for each item
     for (const item of items) {
-      // Get the param value from the item (e.g., item.slug for :slug)
-      const paramValue = item[paramName]
-      if (!paramValue) {
+      // The value the record carries for the route's param — read through the one
+      // map (`routeParamValue`): `[slug]` its handle, `[uuid]` its identity, any
+      // other name its field. ⛔ This read `item[paramName]` until 2026-09-11.
+      const raw = routeParamValue(item, paramName)
+      if (raw === undefined || raw === null || raw === '') {
         unrouted += 1
         continue
       }
+      const paramValue = String(raw)
 
       // Create concrete route: /blog/:slug → /blog/my-post. Under `[...path]` the
       // record's URL is its placement (the folder `records.yml` put it in, carried
@@ -274,7 +343,7 @@ export function expandDynamicPages(pages, pageFetchedData, onProgress = () => {}
       // decoded: the server decodes the request before looking the file up.
       const capture = catchAll ? joinPathCapture({ dir: item.path, slug: paramValue }) : null
       const concreteRoute = catchAll
-        ? page.route.replace(/:path\*$/, capture)
+        ? page.route.replace(new RegExp(`:${catchAll}\\*$`), capture)
         : page.route.replace(`:${paramName}`, paramValue)
 
       // Static sibling wins: skip a record whose concrete route collides with
@@ -289,24 +358,21 @@ export function expandDynamicPages(pages, pageFetchedData, onProgress = () => {}
       concretePage.route = concreteRoute
       concretePage.isDynamic = false // No longer dynamic
       concretePage.paramName = undefined
-      concretePage.parentSchema = undefined
-
-      // Store the dynamic route context for runtime data resolution. Only the
-      // keys the runtime actually uses — the entity cascade re-finds the record
-      // from the fetched collection by paramName/paramValue/schema. The record
-      // (`currentItem`) and the full sibling list (`allItems`) are deliberately
-      // NOT baked in: nothing reads them (the documented dynamicContext shape is
-      // { paramName, paramValue, schema }; the record is delivered via
-      // content.data and siblings via `fetch: { refine: true, detail: false }`),
+
+      // The route's binding, as the SPA makes it (`routeBinding`): the three
+      // variables a query binds, the param and its value, and the template's
+      // route. ⛔ No `schema`: the key the URL narrows is worked out where it is
+      // read (deleted 2026-09-11). The record (`currentItem`) and the full sibling
+      // list (`allItems`) are deliberately NOT baked in: the record is delivered
+      // via content.data and siblings via `fetch: { refine: true, detail: false }`,
       // and embedding `allItems` duplicated the whole collection onto every
       // prerendered page in split mode.
+      const binding = routeBinding(page.route, catchAll ? { [catchAll]: capture } : { [paramName]: paramValue }, paramName)
       concretePage.dynamicContext = {
-        paramName,
-        paramValue,
-        schema,           // Plural: 'articles'
-        // A catch-all page carries its three variables, so a query binding
-        // `:dir` or `:path` resolves the same way it does in the browser.
-        ...(catchAll ? { params: splitPathCapture(capture) } : {}),
+        templateRoute: page.route,
+        params: binding.variables,
+        paramName: binding.paramName,
+        paramValue: binding.paramValue,
       }
 
       // Use item data for page metadata if available
@@ -319,7 +385,7 @@ export function expandDynamicPages(pages, pageFetchedData, onProgress = () => {}
     if (unrouted > 0) {
       stats.unrouted[page.route] = unrouted
       onProgress(
-        `  ⚠️ ${unrouted} of ${items.length} ${schema} records have no "${paramName}" — no page was ` +
+        `  ⚠️ ${unrouted} of ${items.length} ${key} records have no "${paramName}" — no page was ` +
           `generated for them under ${page.route}`
       )
     }
@@ -336,7 +402,7 @@ export function expandDynamicPages(pages, pageFetchedData, onProgress = () => {}
  * @param {Object} fetchOptions - Options for executeFetch
  * @param {function} onProgress - Progress callback
  */
-async function processSectionFetches(sections, fetchOptions, onProgress) {
+async function processSectionFetches(sections, fetchOptions, onProgress, record = null) {
   if (!sections || !Array.isArray(sections)) return
 
   for (const section of sections) {
@@ -348,6 +414,9 @@ async function processSectionFetches(sections, fetchOptions, onProgress) {
       onProgress(`  Fetching section data: ${sectionFetch.path || sectionFetch.url}`)
       const result = await executeFetch(sectionFetch, fetchOptions)
       if (result.data && !result.error) {
+        // What a section fetched, by key — the route query of a parametric page
+        // whose sections alone declare it (`routeQuery`).
+        if (record) record(sectionFetch.as, result.data)
         section.parsedContent = mergeDataIntoContent(
           section.parsedContent || {},
           result.data,
@@ -359,7 +428,7 @@ async function processSectionFetches(sections, fetchOptions, onProgress) {
 
     // Process subsections recursively
     if (section.subsections && section.subsections.length > 0) {
-      await processSectionFetches(section.subsections, fetchOptions, onProgress)
+      await processSectionFetches(section.subsections, fetchOptions, onProgress, record)
     }
   }
 }
@@ -425,7 +494,7 @@ async function discoverLocaleContents(distDir, defaultContent) {
  * `{ config, data }` shape the runtime's hydrateDataStore expects.
  */
 function stripFetchScope(entry) {
-  const { _scope, ...clean } = entry
+  const { _scope, _routeBound, ...clean } = entry
   return clean
 }
 
@@ -448,14 +517,66 @@ function stripFetchScope(entry) {
  * @param {Set<string>|null} scopeRoutes - Routes whose entries to keep, or null.
  * @returns {Array<{config: Object, data: any}>}
  */
-export function scopeFetchedData(fetchedData, scopeRoutes) {
+export function scopeFetchedData(fetchedData, scopeRoutes, currentRoute = null) {
   if (!Array.isArray(fetchedData)) return fetchedData
-  if (!scopeRoutes) return fetchedData.map(stripFetchScope)
+  // A route-bound entry (`readRouteBoundViews`) belongs to one expanded page, in
+  // either mode: carried everywhere, a site of N such pages would embed N views —
+  // or N whole records — in every page.
+  const own = (e) => !e._routeBound || e._scope === currentRoute
+  if (!scopeRoutes) return fetchedData.filter(own).map(stripFetchScope)
   return fetchedData
-    .filter((e) => e._scope === '__site__' || scopeRoutes.has(e._scope))
+    .filter((e) => own(e) && (e._scope === '__site__' || scopeRoutes.has(e._scope)))
     .map(stripFetchScope)
 }
 
+/**
+ * The views an expanded parametric page binds to its route — `scope: :dir` bound to
+ * its branch, a `deferred:` query's per-record file — that no list page asked for.
+ * Each is resolved by the RUNTIME's own rule for the page (`resolvePageFetchConfigs`,
+ * the one a host's prefetch calls, matched against the parametric page it came
+ * from) and read by `read`, so the page renders complete and the SPA hydrates the
+ * very keys it asks for.
+ *
+ * ⭐ ONE ENTRY PER PAGE, ONE READ PER VIEW. Each entry is tagged `_routeBound` with
+ * its page's route: `scopeFetchedData` embeds it in that page's HTML and nowhere
+ * else, and the split-mode manifest leaves it out — so N expanded pages do not
+ * carry N views (or N whole records) each. Pages that bind the same view (two
+ * entries in one branch) each get an entry, over a single read. ⛔ Filed under
+ * the first page that asked for it, a shared view reached no other page's HTML
+ * (measured: the second entry in a branch shipped without its branch's view).
+ *
+ * A key already `present` is not read: every page carries those already — the
+ * site's, and, in split mode, its parent's and its template's (the render loop's
+ * `scopeRoutes`).
+ *
+ * @param {Object} options
+ * @param {Object} options.templates - the content as it was before expansion (the parametric pages)
+ * @param {Array<Object>} options.pages - the pages after expansion
+ * @param {Array<Object>} options.present - the entries already baked
+ * @param {Function} options.resolvePageFetchConfigs - `@uniweb/runtime/ssr`'s
+ * @param {(cfg: Object) => Promise<{config: Object, data: any, meta?: Object}|null>} options.read - reads one config
+ * @param {string|null} [options.locale]
+ * @returns {Promise<Array<Object>>} the new entries, each for its own page
+ */
+export async function readRouteBoundViews({ templates, pages, present, resolvePageFetchConfigs, read, locale = null }) {
+  const carried = new Set((present || []).map((e) => deriveCacheKey(e.config)))
+  const reads = new Map()
+  const out = []
+  for (const page of pages || []) {
+    if (!page?.dynamicContext) continue
+    const filed = new Set()
+    for (const cfg of resolvePageFetchConfigs(templates, page.route, { locale })) {
+      const key = deriveCacheKey(cfg)
+      if (carried.has(key) || filed.has(key)) continue
+      filed.add(key)
+      if (!reads.has(key)) reads.set(key, read(cfg))
+      const view = await reads.get(key)
+      if (view) out.push({ ...view, _scope: page.route, _routeBound: true })
+    }
+  }
+  return out
+}
+
 /**
  * Inject build-specific data into HTML (theme CSS, __SITE_CONTENT__, icon cache).
  * Called after the shared injectPageContent for build-specific additions.
@@ -518,7 +639,7 @@ export function injectBuildData(html, siteContent, { splitContent = false, curre
   if (Array.isArray(contentForJson.fetchedData)) {
     contentForJson = {
       ...contentForJson,
-      fetchedData: scopeFetchedData(contentForJson.fetchedData, splitContent ? scopeRoutes : null),
+      fetchedData: scopeFetchedData(contentForJson.fetchedData, splitContent ? scopeRoutes : null, currentRoute),
     }
   }
 
@@ -607,6 +728,7 @@ export async function prerenderSite(siteDir, options = {}) {
     prefetchIcons,
     createPageRenderer,
     generate404Html,
+    resolvePageFetchConfigs,
   } = await import('@uniweb/runtime/ssr')
 
   // Load default site content
@@ -674,7 +796,7 @@ export async function prerenderSite(siteDir, options = {}) {
     // For non-default locales, collection data is read from dist/{locale}/data/
     onProgress('Executing data fetches...')
     const defaultLocale = resolveDefaultLocale(defaultSiteContent.config)
-    const { pageFetchedData, fetchedData } = await executeAllFetches(
+    const { fetched, fetchedData, bake } = await executeAllFetches(
       siteContent, siteDir, onProgress,
       { locale, defaultLocale, distDir }
     )
@@ -690,7 +812,33 @@ export async function prerenderSite(siteDir, options = {}) {
     // Expand dynamic pages (e.g., /blog/:slug → /blog/post-1, /blog/post-2)
     if (siteContent.pages?.some(p => p.isDynamic)) {
       onProgress('Expanding dynamic routes...')
-      siteContent.pages = expandDynamicPages(siteContent.pages, pageFetchedData, onProgress)
+      const templates = { ...siteContent, pages: siteContent.pages }
+      siteContent.pages = expandDynamicPages(siteContent.pages, fetched, onProgress, undefined, {
+        siteFetch: siteContent.config?.fetch ?? null,
+      })
+
+      // ⭐ AN EXPANDED PAGE ASKS FOR WHAT ITS ROUTE BINDS. Its sections read views
+      // no list page asked for — `scope: :dir` bound to its branch, a `deferred:`
+      // query's per-record file — and those are resolved here by the RUNTIME's own
+      // rule for a page (`resolvePageFetchConfigs`, the one a host's prefetch
+      // calls, matched against the parametric page it came from), then read by
+      // this build's executor. So the page renders complete, and the SPA hydrates
+      // the very keys it asks for.
+      // ⛔ Appended to `siteContent.fetchedData` — the copy `stripBuildOnlyFetchKeys`
+      // made above — never to the raw `fetchedData`, whose configs still carry the
+      // build-only `merge` (it leaked into shipped pages that way, measured).
+      const baked = await readRouteBoundViews({
+        templates,
+        pages: siteContent.pages,
+        present: siteContent.fetchedData,
+        resolvePageFetchConfigs,
+        read: bake,
+        locale,
+      })
+      if (baked.length > 0) {
+        siteContent.fetchedData = [...siteContent.fetchedData, ...baked]
+        onProgress(`  Read ${baked.length} route-bound view(s) for expanded pages`)
+      }
     }
 
     // Determine whether to split content (after dynamic expansion, after data fetches)
@@ -752,7 +900,9 @@ export async function prerenderSite(siteDir, options = {}) {
     // hydrateDataStore handles cache-key derivation + value-shape wrapping
     // — same helper used by the browser SPA boot and by the Cloudflare
     // Worker SSR isolate, so all three render paths agree on shape.
-    hydrateDataStore(uniweb.activeWebsite, fetchedData)
+    // ⛔ `siteContent.fetchedData`, not the raw list: only it holds the route-bound
+    // views, and an expanded page rendered without them paints "not found" (measured).
+    hydrateDataStore(uniweb.activeWebsite, siteContent.fetchedData)
 
     // Pre-fetch icons for SSR embedding
     await prefetchIcons(siteContent, uniweb, onProgress)
@@ -846,7 +996,9 @@ export async function prerenderSite(siteDir, options = {}) {
       // Build-specific: theme CSS, __SITE_CONTENT__, icon cache.
       // scopeRoutes mirrors the runtime data cascade (page → page.parent → site)
       // so split-mode pages embed only the collection data their first render reads.
-      const scopeRoutes = new Set([page.route, page.parent?.route].filter(Boolean))
+      // An expanded page's own fetch was read under its TEMPLATE's route — the
+      // route it had when the fetches ran — so that route is in its cascade too.
+      const scopeRoutes = new Set([page.route, page.parent?.route, page.dynamicContext?.templateRoute].filter(Boolean))
       html = injectBuildData(html, siteContent, {
         splitContent,
         currentRoute: page.route,
@@ -892,9 +1044,10 @@ export async function prerenderSite(siteDir, options = {}) {
         })
       }
       // The manifest is a single (non-per-page) file, so it keeps all fetched
-      // data — but the internal `_scope` tag must never leak into it.
+      // data — but the internal `_scope` tag must never leak into it, and a
+      // route-bound entry belongs to its own page's HTML, not to every page.
       if (Array.isArray(manifest.fetchedData)) {
-        manifest.fetchedData = manifest.fetchedData.map(stripFetchScope)
+        manifest.fetchedData = manifest.fetchedData.filter((e) => !e?._routeBound).map(stripFetchScope)
       }
       await writeFile(localeContentPath, JSON.stringify(manifest))
       onProgress('Rewrote site-content.json as lightweight manifest')

package/src/site/content-collector.js

@@ -30,7 +30,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, 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
 // ─────────────────────────────────────────────────────────────────
@@ -866,7 +911,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,
@@ -1467,12 +1511,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 +1551,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 +1576,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,
@@ -1872,6 +1912,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 +1971,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,
@@ -2001,6 +2041,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 +2065,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,
@@ -2835,6 +2875,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
@@ -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/query-processor.js

@@ -54,8 +54,8 @@ import { join, basename, extname, dirname, relative, resolve, sep } from 'node:p
 import { existsSync } from 'node:fs'
 import yaml from 'js-yaml'
 import { parseBibtex } from '@citestyle/bibtex'
-import { DATA_DIR, fillRoutePattern } from '@uniweb/core'
-import { applyWhere, applySort } from './data-fetcher.js'
+import { DATA_DIR, fillRoutePattern, withoutRouteVariables } from '@uniweb/core'
+import { applyWhere, applySort, refuseUnder } from './data-fetcher.js'
 import { resolveAssetPath, walkContentAssets, isLocalAssetPath } from './assets.js'
 import { readEntityPool, groupPoolBySchema, ENTITIES_DIR } from './entity-pool.js'
 import { readRecordsConfig, resolveFolder, FOLDER_MISSING } from './records-config.js'
@@ -113,6 +113,7 @@ function parseQueryConfig(name, config) {
       schema: config,
       url: null,
       route: null,
+      scope: null,
       sort: null,
       where: null,
       filter: null,
@@ -122,6 +123,7 @@ function parseQueryConfig(name, config) {
     }
   }
 
+  refuseUnder(config.where, `queries.${name}`)
   return {
     name,
     // The query's schema selects its records from the pool — `entities/{schema}/`
@@ -129,6 +131,9 @@ function parseQueryConfig(name, config) {
     schema: config.schema || null,
     url: config.url || null,
     route: config.route || null,
+    // The folder branch the query reads (`records.yml` placement). ⛔ Not read
+    // here until 2026-09-11: a named query's `scope` was ignored on this lane.
+    scope: typeof config.scope === 'string' ? config.scope : null,
     sort: config.sort || null,
     // `where:` is the CANONICAL predicate; `filter:` is the deprecated string DSL
     // it replaced. Both are carried and both are applied below, in the same order
@@ -673,6 +678,19 @@ async function collectItems(siteDir, config, entitiesDir, basePath) {
   // Filter out nulls (unpublished items)
   items = items.filter(Boolean)
 
+  // ⭐ `$name` IS THE RECORD HANDLE ON EVERY SITE (ruled 2026-09-11 [Diego]) — the
+  // field a `[slug]` or `[...path]` page matches, and the one the records service
+  // serves. It is the record's FINAL slug: set here, after every format has been
+  // read and flattened, so a frontmatter `slug:` (which wins over the filename),
+  // a BibTeX cite key and an array-form file's own `slug` all count — exactly what
+  // our sync sends as the entry's name (`uwx/entity-source.js`). `slug` stays:
+  // foundations and templates read it.
+  items = items.map((item) => (
+    item && typeof item === 'object' && item.slug !== undefined && item.slug !== null && item.slug !== ''
+      ? { ...item, $name: String(item.slug) }
+      : item
+  ))
+
   warnDuplicateSlugs(items, config.name)
 
   // `route:` on the query — bake each record's canonical href.
@@ -711,8 +729,19 @@ async function collectItems(siteDir, config, entitiesDir, basePath) {
   // the sync wire, stored — and never applied, while the DEPRECATED one it replaced
   // worked. An author following current guidance got silence and shipped unfiltered
   // data. Pinned by `tests/collection-query-terms.test.js`.
-  if (config.where) {
-    items = applyWhere(items, config.where)
+  // ⭐ ONLY THE `where` FIXED FOR EVERY PAGE. A clause bound to the route —
+  // `where: { tag: :dir }` — cannot be applied to a file written once for every
+  // page; the runtime binds it per page (`@uniweb/core/fetch-config`,
+  // `resolveQuerySource`). ⛔ Until 2026-09-11 it was applied here to the literal
+  // `':dir'`, and the query compiled to no records (measured).
+  //
+  // ⛔ `scope` is NEVER baked, fixed or routed. The runtime applies the one that
+  // wins — a page fetch's own, else this query's — which is what the records
+  // service does. Baked here, a page's `scope:` could only narrow inside the
+  // query's branch on a static site and would replace it on a hosted one.
+  const fixed = withoutRouteVariables({ where: config.where })
+  if (fixed.where) {
+    items = applyWhere(items, fixed.where)
   }
 
   // Apply sort

package/src/uwx/site.js

@@ -53,7 +53,9 @@ import {
   applyWildcardOrder,
   processMarkdownFile,
   fetchFromDataShorthand,
+  assertRouteFolder,
 } from '../site/content-collector.js'
+import { refuseUnder } from '../site/data-fetcher.js'
 import { normalizeHideIn } from '../site/nav-visibility.js'
 import { resolveDefaultLocale, validateLanguageConfig, queryDataUrl } from '@uniweb/core'
 import { emitEntitySyncPackage } from './entity-document.js'
@@ -236,6 +238,10 @@ function buildPageData(config, ctx) {
   // 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 ?? fetchFromDataShorthand(config.data)
+  // `where: { path: { under } }` is refused here as the build refuses it
+  // (`parseFetchConfig`): a site that cannot build must not sync either. A
+  // section's fetch is refused where the collector parses it.
+  for (const one of [fetch].flat()) refuseUnder(one?.where, 'fetch')
   // Resolve the authored `query:` shorthand to the runtime-fetchable
   // `path: /data/<name>.json` (the static convention the default-fetcher uses).
   // A shell/backend-hosted site renders client-side with NO prerender, so the
@@ -548,8 +554,13 @@ async function walkPagesNested(ctx, dirPath, parentSlugPath, inheritedMode, pare
   const { siteRoot, siteIndex, sourceLocale, translations } = ctx
   const folders = await orderedSubfolders(dirPath, inheritedMode, parentConfig)
   const out = []
+  // A folder inside a `[...path]` folder can never be reached, and `[dir]` /
+  // `[path]` would name a route variable — refused here as the collector refuses
+  // them, so a site that cannot build cannot sync either (ruled 2026-09-11).
+  const insideCatchAll = (parentSlugPath || '').split('/').includes(CATCH_ALL_MARKER)
   for (let i = 0; i < folders.length; i++) {
     const f = folders[i]
+    assertRouteFolder(f.dirName, insideCatchAll ? '/:path*' : '/')
     const dyn = f.dirName.match(DYNAMIC_RE)
     const slug = dyn ? dyn[1] : f.name
     const mode = f.source === 'folder.yml' ? 'folder' : 'page'
@@ -803,6 +814,7 @@ const DECL_NOT_ON_WIRE = new Set([
 function queriesNested(declarations, uuids = null, org = null) {
   const out = []
   for (const [name, d] of Object.entries(declarations)) {
+    refuseUnder(d.where, `queries.${name}`)
     const data = {}
     const source = d.path ? { path: d.path } : d.url ? { url: d.url } : d.source
     setIf(data, 'source', source)
@@ -1071,6 +1083,10 @@ function settingsNested(siteYml, { headHtml, themeYml, sourceLocale, translation
   // ⭐ The site-level fetch, DESUGARED and under its real name. `data:` is the
   // authoring shorthand for `fetch:` and every other tier already calls the wire
   // field `fetch`; the site tier called it `data` until 2026-09-09.
+  // `under` is refused as the build refuses it; the `data:` shorthand carries no
+  // `where`. ⚠️ The source expression stays inside `setIf`: `gen-emit-surface.mjs`
+  // reads the published key's sources off it.
+  for (const one of [siteYml.fetch].flat()) refuseUnder(one?.where, 'site.yml fetch')
   setIf(settings, 'fetch', siteYml.fetch ?? fetchFromDataShorthand(siteYml.data))
 
   // ⭐ The SITE TIER of framework's own `{name, hide, params}` layout object, which