@uniweb/build 0.54.0 → 0.55.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.54.0",
+  "version": "0.55.0",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -58,14 +58,14 @@
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
     "@uniweb/content-reader": "^1.2.5",
-    "@uniweb/semantic-parser": "^1.4.1",
-    "@uniweb/schemas": "^0.3.3",
     "@uniweb/content-writer": "^0.3.4",
+    "@uniweb/projections": "^0.7.3",
     "@uniweb/theming": "^0.1.15",
-    "@uniweb/projections": "^0.7.3"
+    "@uniweb/semantic-parser": "^1.4.1",
+    "@uniweb/schemas": "^0.3.3"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "^0.26.5"
+    "@uniweb/runtime": "^0.27.0"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -74,8 +74,8 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/runtime": "^0.26.5",
-    "@uniweb/core": "^0.29.4"
+    "@uniweb/core": "^0.29.6",
+    "@uniweb/runtime": "^0.27.0"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/prerender.js

@@ -25,7 +25,9 @@ import {
   evaluateQuery,
 } from '@uniweb/core'
 import { recordTitle, routePatternToRegex } from '@uniweb/core/route-match'
+import DataStore from '@uniweb/core/datastore'
 import { executeFetch, mergeDataIntoContent, toFetchList } from './site/data-fetcher.js'
+import { createFileTransport } from './site/file-transport.js'
 import { shouldSplitContent } from './site/split-content.js'
 import { FONT_LINKS_MARKER } from './site/head-markers.js'
 import { getAdapter } from './hosts/index.js'
@@ -89,9 +91,10 @@ 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} { 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
+ * @returns {Object} { fetched, fetchedData } - what each level fetched, by binding key (for
+ *   parametric-page expansion), and the entries for DataStore pre-population. ⛔ It no longer
+ *   bakes the views an expanded page binds to its route: the render loop asks for those by the
+ *   rule the render uses, per page (`loadPageData`, 2026-09-20).
  */
 export async function executeAllFetches(siteContent, siteDir, onProgress, localeInfo) {
   // The locale this pass renders, which a `sort` collates texts in.
@@ -171,7 +174,15 @@ export async function executeAllFetches(siteContent, siteDir, onProgress, locale
   // `undefined` — which passes the `!== false` test and then fetches nothing.
   const firstSite = firstOfKey()
   for (const oneFetch of toFetchList(siteContent.config?.fetch)) {
-    if (!firstSite(oneFetch.as)) continue
+    // ⭐ EVERY binding is FETCHED; only the first per key is KEPT as the key's set.
+    // Ruled 2026-09-20 [Diego]: where several fetches of one schema meet several declared
+    // keys of it and no `as` pairs them, they pair POSITIONALLY — so a second binding under
+    // one key fills another key and its data is needed. ⛔ Skipping it baked nothing for that
+    // key and the section rendered empty. What stays first-per-key is the SET a parametric
+    // page expands over, which is the route query's — and it is counted before
+    // `prerender: false` is honoured, so a deferred first binding is not replaced by a baked
+    // second.
+    const isFirst = firstSite(oneFetch.as)
     // ⭐ `prerender` is read off the RESOLVED config: an external query's binding is the
     // browser's unless it says otherwise, which only the resolver knows.
     const cfg = resolveForBuild(oneFetch)
@@ -180,7 +191,7 @@ export async function executeAllFetches(siteContent, siteDir, onProgress, locale
     const got = await read(cfg, oneFetch)
     if (got) {
       fetchedData.push(entry(cfg, got.view, '__site__'))
-      fetched.site.set(oneFetch.as, got.selection)
+      if (isFirst) fetched.site.set(oneFetch.as, got.selection)
     }
   }
 
@@ -201,14 +212,15 @@ export async function executeAllFetches(siteContent, siteDir, onProgress, locale
     // Page-level fetch — every declaration on the page.
     const firstPage = firstOfKey()
     for (const oneFetch of toFetchList(page.fetch)) {
-      if (!firstPage(oneFetch.as)) continue
+      // Every binding fetched, the first per key kept as the key's set — see the site level.
+      const isFirst = firstPage(oneFetch.as)
       const cfg = resolveForBuild(oneFetch)
       if (cfg.prerender === false) continue
       onProgress(`  Fetching page data for ${page.route}: ${cfg.path || cfg.url}`)
       const got = await read(cfg, oneFetch)
       if (got) {
         fetchedData.push(entry(cfg, got.view, page.route))
-        keep(fetched.pages, page.route, oneFetch.as, got.selection)
+        if (isFirst) keep(fetched.pages, page.route, oneFetch.as, got.selection)
       }
     }
 
@@ -218,7 +230,7 @@ export async function executeAllFetches(siteContent, siteDir, onProgress, locale
     // key, a view its route binds under any other. A list baked into the template
     // was cloned into every expanded page and outranked both (measured 2026-09-13:
     // `/blog/b` rendered all three records). Its views are read per expanded page
-    // instead (`readRouteBoundViews`).
+    // instead — by the render loop's data step, per page (`loadPageData`).
     await processSectionFetches(page.sections, {
       resolve: resolveForBuild,
       read,
@@ -228,21 +240,7 @@ export async function executeAllFetches(siteContent, siteDir, onProgress, locale
     })
   }
 
-  /**
-   * 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' && typeof cfg.url !== 'string')) return null
-    const options = isNonDefaultLocale && typeof cfg.path === 'string' && 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 }
+  return { fetched, fetchedData }
 }
 
 /**
@@ -622,7 +620,7 @@ function stripFetchScope(entry) {
  */
 export function scopeFetchedData(fetchedData, scopeRoutes, currentRoute = null) {
   if (!Array.isArray(fetchedData)) return fetchedData
-  // A route-bound entry (`readRouteBoundViews`) belongs to one expanded page, in
+  // A route-bound entry — what a page's own data step asked for — belongs to that 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
@@ -663,54 +661,6 @@ function dedupeByAddress(entries) {
   return out
 }
 
-/**
- * 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.
@@ -862,7 +812,7 @@ export async function prerenderSite(siteDir, options = {}) {
     prefetchIcons,
     createPageRenderer,
     generate404Html,
-    resolvePageFetchConfigs,
+    loadPageData,
   } = await import('@uniweb/runtime/ssr')
 
   // Load default site content
@@ -941,30 +891,15 @@ 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...')
-      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.
-      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`)
-      }
+      // ⭐ AN EXPANDED PAGE ASKS FOR WHAT ITS ROUTE BINDS — its branch's view, a `deferred:`
+      // query's per-record file — and that is now asked for in the render loop below, by the
+      // rule the render uses, per page (`loadPageData`). ⛔ It was worked out here from the
+      // payload alone until 2026-09-20, which cannot build a record's own address from the
+      // record: an `[id]` route over a `deferred:` query asked for `{slug}` unfilled.
     }
 
     // Determine whether to split content (after dynamic expansion, after data fetches)
@@ -1022,6 +957,16 @@ export async function prerenderSite(siteDir, options = {}) {
     // fixed, so it is created once and asked per page.
     const renderer = createPageRenderer({ website: uniweb.activeWebsite, shell: htmlShell })
 
+    // ⭐ The data step's two halves for this lane: a transport over the files this build has
+    // already produced, and one cache for the whole run so an address every page asks for is read
+    // once rather than once per page.
+    const fileTransport = createFileTransport({
+      siteRoot: siteDir,
+      distDir,
+      base: siteContent.config?.base || '',
+    })
+    const buildDataCache = new DataStore()
+
     // Build-specific: pre-populate DataStore so EntityStore can resolve data during prerender.
     // hydrateDataStore handles cache-key derivation + value-shape wrapping
     // — same helper used by the browser SPA boot and by the Cloudflare
@@ -1090,14 +1035,43 @@ export async function prerenderSite(siteDir, options = {}) {
         }
       }
 
+      // ⭐ WHAT THIS PAGE'S RENDER WILL READ — asked by the rule the render itself uses
+      // (`loadPageData`, `@uniweb/runtime/ssr`) and answered from this build's own files. It walks
+      // the page's blocks: its body, the layout areas it draws, child blocks and insets.
+      //
+      // ⛔ Until 2026-09-20 this lane worked the answer out its own way, and got two things wrong
+      // that nothing else could see: a LAYOUT section's data was never fetched at all — the
+      // executor walks the site, each page and each page's sections, and layout areas sit beside
+      // the pages — and an expanded page's views came from the payload walk, which cannot build a
+      // record's own address from the record. Both render empty in the HTML and fill in once the
+      // SPA boots, so only a crawler ever saw them.
+      //
+      // One cache for the whole run, so an address every page asks for is read once; the author's
+      // `prerender: false` is honoured, which is what `'author'` means and what a baking lane owes.
+      const asked = await loadPageData({
+        website,
+        route: page,
+        fetch: fileTransport,
+        prerender: 'author',
+        cache: buildDataCache,
+      })
+      hydrateDataStore(website, asked)
+      // Filed under this page, the way a route-bound view always has been: `scopeFetchedData`
+      // embeds it in this page's HTML and nowhere else, and one address embedded twice collapses.
+      for (const entry of asked) {
+        if (entry.outcome !== 'fetched') continue
+        siteContent.fetchedData.push({ ...entry, _scope: page.route, _routeBound: true })
+      }
+
       onProgress(`Rendering ${outputRoute}...`)
 
       // ⭐ `renderer.render` IS the sequence this loop used to spell out —
       // renderPage → classify → injectPageContent. It was moved into
       // `@uniweb/runtime/ssr` because an SSR isolate assembles the same three steps
-      // per request, and two hand-written copies of one sequence is how the two
-      // lanes drift. This lane passes the Page it already holds; the isolate passes
-      // a route. See `runtime/src/page-renderer.js` for what it leaves to the host.
+      // for the page a visit starts on, and two hand-written copies of one sequence
+      // is how the two lanes drift. This lane passes the Page it already holds; the
+      // isolate passes a route. See `runtime/src/page-renderer.js` for what it leaves
+      // to the host.
       const result = renderer.render(page)
 
       if (result.outcome === 'failed') {

package/src/site/data-fetcher.js

@@ -412,10 +412,19 @@ function refuseSourceKeys(fetch, context) {
 
 /**
  * ⚠️ TWO BINDINGS UNDER ONE KEY AT ONE LEVEL — ruled 2026-09-13 [Diego]: *"Duplicates
- * should not exist."* The first is used on every lane (`resolveFetchConfigs` keeps
- * the first per key, and so does the build's prerender) and the rest are ignored;
- * this says so once per key per file. Warned, not refused: the first binding still
- * delivers what it says.
+ * should not exist."* Warned, not refused, once per key per file.
+ *
+ * ⛔ **What happens to the second one depends on something this parser cannot see** — whether
+ * a component declares that key — so the message says both, and this comment no longer claims
+ * one. Ruled 2026-09-20 [Diego]: *"if there are x fetches of schema Y, and x+ keys for schema
+ * Y, and there is no `as` key that tells us how to pair, then we can auto-pair positionally."*
+ *   - **a component declares the key** → the first fills it and the rest fill nothing;
+ *   - **none declares it** → they pair POSITIONALLY with that schema's still-empty declared
+ *     keys, in order, so the second is used (`fillDeclaredKeys`, measured 2026-09-20).
+ *
+ * ⚠️ This comment and the message said *"the rest are ignored"* until 2026-09-20, which is
+ * false in the second case — and the build's own executor believed it, so a second binding's
+ * data was never fetched and the key it fills rendered empty.
  *
  * @param {Array<Object>} list - one level's bindings, parsed or as authored
  * @param {string} context - where the declaration sits, for the message
@@ -435,8 +444,10 @@ export function warnDuplicateBindings(list, context) {
     if (warnedDuplicateBindings.has(memo)) continue
     warnedDuplicateBindings.add(memo)
     console.warn(
-      `[uniweb] ${context}: more than one binding delivers content.data.${key} — the first is used ` +
-        `and the rest are ignored. Give each binding its own \`as:\`.`
+      `[uniweb] ${context}: more than one binding is named ${key}. A component that declares ` +
+        `content.data.${key} receives the first, and the rest fill nothing; if none declares it, ` +
+        `they pair in order with the declared keys of their schema. Give each binding its own ` +
+        `\`as:\` to say which is which.`
     )
   }
 }

package/src/site/file-transport.js

@@ -0,0 +1,79 @@
+/**
+ * A `fetch`-shaped transport over the files this build has already produced.
+ *
+ * ⭐ **Why a transport rather than a reader.** The render's data step
+ * (`@uniweb/runtime/ssr::loadPageData`) asks for what a page's render will read, by the rule the
+ * render itself uses, and dispatches every request through one function the caller supplies. A host
+ * gives it the network; this lane gives it `dist/` and `public/`. So the build asks the same
+ * question as every other lane and only the answering differs — which is the whole point of
+ * `kb/framework/plans/what-a-page-needs.md`.
+ *
+ * ⛔ **A remote `url:` is still the browser's lane by default.** Nothing here decides that: the
+ * author's `prerender:` does, and the step is run with `prerender: 'author'` so a deferred request
+ * is never dispatched. One that IS asked for at build time is fetched the way a browser would.
+ *
+ * ⚖️ **`dist/` first, then `public/`** — a non-default locale's data is written under
+ * `dist/{locale}/data/…` and the resolver localizes the path, so the localized address is found
+ * where it was written; everything else sits in `public/`, which is where the query processor
+ * compiles a query's file.
+ *
+ * @module
+ */
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+/** The site-relative path an address names, with the site's base removed. */
+function pathOf(target, base) {
+  const clean = String(target).split('#')[0]
+  if (!base || base === '/') return clean
+  const prefix = base.endsWith('/') ? base.slice(0, -1) : base
+  return clean.startsWith(prefix) ? clean.slice(prefix.length) || '/' : clean
+}
+
+const response = (body, contentType) => ({
+  ok: true,
+  status: 200,
+  statusText: 'OK',
+  headers: { get: (name) => (String(name).toLowerCase() === 'content-type' ? contentType : null) },
+  json: async () => JSON.parse(body),
+  text: async () => body,
+})
+
+const missing = (path) => ({
+  ok: false,
+  status: 404,
+  statusText: `no file for ${path}`,
+  headers: { get: () => 'text/plain' },
+  json: async () => null,
+  text: async () => '',
+})
+
+/**
+ * @param {Object} where
+ * @param {string} where.siteRoot - the site directory
+ * @param {string|null} [where.distDir] - its build output, searched first
+ * @param {string} [where.publicDir] - the static directory under `siteRoot`
+ * @param {string} [where.base] - the site's base path, which addresses carry and files do not
+ * @returns {(input: *, init?: Object) => Promise<Object>} a `fetch`
+ */
+export function createFileTransport({ siteRoot, distDir = null, publicDir = 'public', base = '' }) {
+  const roots = [distDir, join(siteRoot, publicDir)].filter(Boolean)
+
+  return async function fileTransport(input, init) {
+    const target = String(input?.url ?? input)
+    // Absolute: a remote address, fetched as the browser would.
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(target)) return globalThis.fetch(target, init)
+
+    const path = pathOf(target, base)
+    for (const root of roots) {
+      const file = join(root, path)
+      if (!existsSync(file)) continue
+      const body = await readFile(file, 'utf8')
+      return response(body, path.endsWith('.json') ? 'application/json' : 'text/plain')
+    }
+    // ⚖️ Not an error here. A page can ask for a per-record file a `deferred:` query never wrote,
+    // and the step reports the outcome so the caller can see it rather than crash a build.
+    return missing(path)
+  }
+}

package/src/validate-data.js

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