@uniweb/core 0.28.0 → 0.29.1

package/src/entity-store.js

@@ -14,15 +14,9 @@
  * and in-flight dedup.
  */
 
-import { resolveFetchConfigs, pageRouteQuery, routeSelection, currentOf, othersView, othersOf, siteReaches } from './fetch-config.js'
+import { resolveFetchConfigs, fetchEntries, pageRouteQuery, routeSelection, currentFor, othersView, othersOf, siteReaches } from './fetch-config.js'
+import { declaredKeys, fillDeclaredKeys } from './data-keys.js'
 import { fillRoutePattern, matchesRouteParam } from './route-match.js'
-
-/**
- * A fetch config's binding key — the `content.data.<key>` a component reads.
- * `as` is the name; `schema` is what it was called until 2026-09-02 and still
- * arrives on any payload published before then. See `fetch-config.js`.
- */
-const bindingKeyOf = (cfg) => cfg?.as
 import { buildDetailConfig } from './detail-url.js'
 
 export default class EntityStore {
@@ -39,34 +33,36 @@ export default class EntityStore {
   }
 
   /**
-   * Which schemas does this component want delivered?
+   * The fetches that reach a block, one level each, most specific first: its own, its
+   * page's, its parent page's, a nested page's route binding, and the site's.
    *
-   * - meta missing → default-on: collect all available schemas.
-   * - meta.inheritData === false → opt out entirely.
-   * - Anything else → collect all (legacy inheritData arrays collapse here).
+   * ⭐ A page nested inside a parametric page receives its capturing page's route binding
+   * — the cascade reaches one parent up, and the binding may sit above that
+   * (`pageRouteQuery`). Its key only; the rest does not cascade. The site's binding
+   * reaches a layout section and a top-level page's sections, and nothing deeper
+   * (`siteReaches`).
    */
-  _getRequestedSchemas(meta) {
-    if (!meta) return []
-    if (meta.inheritData === false) return null
-    return []
+  _levels(block, route = this._route(block)) {
+    const page = block.page
+    return [
+      block.fetch,
+      page?.fetch,
+      page?.parent?.fetch,
+      route?.nested ? route.config : null,
+      siteReaches(page?.parent) ? block.website?.config?.fetch : null,
+    ]
   }
 
   /**
-   * Walk the four-level hierarchy and collect fetch configs for the
-   * requested schemas. First match per schema wins.
-   *
-   * This method's job is to read the four source slots off the object graph;
-   * the rule applied to them (precedence, first-match-per-schema, locale
-   * normalization, deferred-detail injection) lives in `./fetch-config.js`,
-   * shared with every other host that has to answer the same question. Do not
-   * re-inline it here — divergence between copies is what the extraction
-   * exists to prevent.
+   * The options each fetch of a block is resolved with. The rule applied to a fetch
+   * (locale normalization, route variables, deferred-detail injection) lives in
+   * `./fetch-config.js`, shared with every other host that has to answer the same
+   * question. Do not re-inline it here — divergence between copies is what the
+   * extraction exists to prevent.
    */
-  _findFetchConfigs(block, requested, route = this._route(block)) {
-    const blockFetch = block.fetch
-    const page = block.page
+  _resolveOptions(block) {
     const website = block.website
-    const dynamicContext = block.dynamicContext || page?.dynamicContext
+    const dynamicContext = block.dynamicContext || block.page?.dynamicContext
     // The route's variables, for a query that binds `:path` / `:dir` / `:slug` —
     // `routeBinding`'s, carried as `params` by every parametric page this runtime
     // or its build makes. A page that carries only its capture gets the same three
@@ -81,36 +77,69 @@ export default class EntityStore {
             }
           : null))
       : null
+    return {
+      locale: website?.getActiveLocale?.() ?? null,
+      defaultLocale: website?.getDefaultLocale?.() ?? null,
+      // ⚠️ `queries`, matching `resolveFetchConfigs`. This passed `collections`
+      // after the payload key was renamed — a dead option name, silently: the
+      // resolver simply saw no queries and stopped injecting `detail:`.
+      queries: website?.config?.queries ?? null,
+      // The host's services; its `records` row is the live-records lane.
+      // Absent on every static site and on local dev, which is why
+      // `resolveQuerySource` treats absence as the ordinary case and reads
+      // the compiled artifact without comment.
+      services: website?.config?.services ?? null,
+      variables,
+    }
+  }
 
-    return resolveFetchConfigs(
-      [
-        blockFetch,
-        page?.fetch,
-        page?.parent?.fetch,
-        // ⭐ A page nested inside a parametric page receives its capturing page's
-        // route binding — the cascade reaches one parent up, and the binding may sit
-        // above that (`pageRouteQuery`). Its key only; the rest does not cascade.
-        route?.nested ? route.config : null,
-        // The site's binding reaches a layout section and a top-level page's
-        // sections, and nothing deeper (`siteReaches`).
-        siteReaches(page?.parent) ? website?.config?.fetch : null,
-      ],
-      {
-        schemas: requested,
-        locale: website?.getActiveLocale?.() ?? null,
-        defaultLocale: website?.getDefaultLocale?.() ?? null,
-        // ⚠️ `queries`, matching `resolveFetchConfigs`. This passed `collections`
-        // after the payload key was renamed — a dead option name, silently: the
-        // resolver simply saw no queries and stopped injecting `detail:`.
-        queries: website?.config?.queries ?? null,
-        // The host's services; its `records` row is the live-records lane.
-        // Absent on every static site and on local dev, which is why
-        // `resolveQuerySource` treats absence as the ordinary case and reads
-        // the compiled artifact without comment.
-        services: website?.config?.services ?? null,
-        variables,
-      },
-    )
+  /**
+   * ⭐ WHAT THIS SECTION RECEIVES, AND FROM WHICH FETCH — ruled 2026-09-14 [Diego]. The keys
+   * its component declares and its foundation's (`website.declaredKeys`), each paired with
+   * the fetch that fills it by the one rule (`fillDeclaredKeys`, automatic `as`) over the
+   * levels that reach the block. A declared key the block already holds — a tagged data
+   * block, or its own fetch's prerendered answer under that name — is not the store's to
+   * fill, and a fetch that fills no declared key is not asked. Each filling fetch is
+   * resolved on its own, so two fetches of one `as` can fill two keys.
+   *
+   * ⭐ `held` is the answer the block already holds for a filling fetch, under the fetch's
+   * own key: a static build prerenders a section's own fetch into its content by `as`, so
+   * a component that names the key differently still receives it without the browser
+   * asking again. Only for the first fetch of that key reaching the block — the one whose
+   * answer a build put there.
+   *
+   * ⛔ Until 2026-09-14 every fetch reaching the block was resolved and delivered under its
+   * `as` — the first per key — whether the component read it or not, and a component
+   * declaring its key under another name received nothing.
+   *
+   * @returns {Map<string, { cfg: Object, held: * }>} declared key → the resolved config of
+   *   the fetch that fills it, and the answer the block holds for it (undefined when none)
+   */
+  _fills(block, meta, route) {
+    const website = block.website
+    const declared = website?.declaredKeys ? website.declaredKeys(meta) : declaredKeys(meta?.data)
+    const out = new Map()
+    if (declared.length === 0) return out
+    const holds = block.heldData || {}
+    const levels = this._levels(block, route)
+    const fills = fillDeclaredKeys(declared, levels, {
+      queries: website?.config?.queries ?? null,
+      held: declared.map(([key]) => key).filter((key) => holds[key] !== undefined),
+    })
+    // where the first fetch of each key reaching the block sits — the one a held answer
+    // belongs to
+    const firstOfKey = new Map()
+    levels.forEach((level, at) => fetchEntries(level).forEach((fetch, index) => {
+      if (!firstOfKey.has(fetch.as)) firstOfKey.set(fetch.as, `${at}:${index}`)
+    }))
+    const options = this._resolveOptions(block)
+    for (const [key, { fetch, level, index }] of fills) {
+      const cfg = resolveFetchConfigs([fetch], options).get(fetch.as)
+      if (!cfg) continue
+      const held = firstOfKey.get(fetch.as) === `${level}:${index}` ? holds[fetch.as] : undefined
+      out.set(key, { cfg, held })
+    }
+    return out
   }
 
   /**
@@ -144,27 +173,66 @@ export default class EntityStore {
   }
 
   /**
-   * Post-process assembled records: for each fetch config that declares a
-   * `detailPage` page-ref, resolve it to a locale route template (O(1), via the
-   * Website's `_pageIdMap`) and inject a `route` on each record — so a dynamic-list
-   * card links to the query's canonical detail page regardless of which page
-   * the list sits on. Runs after `data` is fully assembled, in BOTH the sync (peek)
-   * and async (fetch) paths. Replaces the old runtime `getQueryDetailRoute`
-   * page-tree scan. A dangling `detailPage` (unresolvable ref) is a no-op — the
-   * component degrades gracefully; records with a baked `route` (file lane) are kept.
+   * ⭐ EVERY RECORD LINKS TO ITS QUERY'S PAGE — `$route`, filled here at render time, on
+   * every lane (ruled 2026-09-14 [Diego]). For each delivered key, the page is the
+   * fetch's `detailPage` when it names one that resolves, else the page whose route
+   * query is the fetch's query (`website.recordPageFor`); each record gets that page's
+   * route filled from its own fields (`fillRoutePattern`) as `$route`, and a record that
+   * cannot fill it, or a key whose query has no page, gets none.
+   *
+   * ⭐ `$` marks a system field, as on `$uuid`, `$name` and `$tags` — so the link never
+   * lands in the author's namespace. A component writes `<Link href={item.$route}>`. ⛔ Until 2026-09-14 the link was `route`: the build baked
+   * it into compiled records from `route:` on a query, overwriting an entity's own
+   * `route`, and this filled it only from a `detailPage`, skipping any record that
+   * already had one.
+   *
+   * Runs after `data` is assembled, in the sync (peek) and async (fetch) paths alike.
+   * Records are copied, never mutated: one cached record backs every section that
+   * shows it, each of which may link it to a different page.
    */
-  _applyDetailRoutes(data, configs, website) {
-    if (!data || !website?.resolveDetailPageTemplate) return
-    for (const [schema, cfg] of configs) {
-      if (!cfg.detailPage) continue
-      const items = data[schema]
+  _applyRecordRoutes(data, configs, website) {
+    if (!data || !website) return
+    for (const [key, cfg] of configs) {
+      const items = data[key]
       if (!Array.isArray(items) || items.length === 0) continue
-      const template = website.resolveDetailPageTemplate(cfg.detailPage)
+      const template = recordRouteTemplate(cfg, website)
       if (!template) continue
-      data[schema] = items.map((item) => addDetailRoute(item, template))
+      const linked = items.map((item) => withRecordRoute(item, template))
+      // an unchanged list keeps its identity, so a render that re-links changes nothing
+      if (linked.some((item, i) => item !== items[i])) data[key] = linked
     }
   }
 
+  /**
+   * `$route` on the records a section holds under its own fetch's key — what a static
+   * build prerendered into its content (`block.heldData`). ⭐ A declared key the block holds
+   * is filled from what it holds, not from this store (`runtime/src/prepare-props.js::
+   * assembleData`), so those records never passed `_applyRecordRoutes`; without this, a list
+   * a section fetches for itself reached its component with no links on a prerendered
+   * site. Linked by the same rule, on every render and idempotently: data that is already
+   * linked is left as it is, so its identity survives a re-render. (A held answer this store
+   * delivers under another key is linked where it is delivered.)
+   *
+   * The block's data object is replaced, never written into, since the object the build
+   * delivered may back more than this block.
+   *
+   * @param {Object} block
+   */
+  linkOwnRecords(block) {
+    const held = block?.parsedContent?.data
+    if (!held || typeof held !== 'object' || !block.fetch) return
+    const website = block.website ?? this.website
+    const configs = resolveFetchConfigs([block.fetch], {
+      queries: website?.config?.queries ?? null,
+      services: website?.config?.services ?? null,
+      locale: website?.getActiveLocale?.() ?? null,
+      defaultLocale: website?.getDefaultLocale?.() ?? null,
+    })
+    const linked = { ...held }
+    this._applyRecordRoutes(linked, configs, website)
+    if (Object.keys(linked).some((key) => linked[key] !== held[key])) block.parsedContent.data = linked
+  }
+
   /**
    * Build a detail-URL fetch config from a query config + dynamic context.
    *
@@ -198,22 +266,10 @@ export default class EntityStore {
    */
   resolve(block, meta) {
     const dispatcher = this.website?.fetcher
-    let requested = this._getRequestedSchemas(meta)
-
-    // If the component hasn't declared data inheritance but the block itself
-    // has a fetch config, target the block's schema explicitly rather than
-    // collecting all cascade matches.
-    if (requested === null && block.fetch) {
-      const blockFetchList = Array.isArray(block.fetch) ? block.fetch : [block.fetch]
-      const schemas = blockFetchList.filter(bindingKeyOf).map(bindingKeyOf)
-      if (schemas.length > 0) requested = schemas
-    }
-
-    if (requested === null) return { status: 'none', data: null }
-
     const route = this._route(block)
-    const configs = this._findFetchConfigs(block, requested, route)
-    if (configs.size === 0) return { status: 'none', data: null }
+    const fills = this._fills(block, meta, route)
+    if (fills.size === 0) return { status: 'none', data: null }
+    const configs = new Map([...fills].map(([key, { cfg }]) => [key, cfg]))
 
     const dynamicContext = block.dynamicContext || block.page?.dynamicContext
     const ctx = this._ctx(block)
@@ -221,11 +277,16 @@ export default class EntityStore {
     const data = {}
     let allCached = true
 
-    for (const [schema, cfg] of configs) {
-      // `current:` applies under the key the page's URL narrows, and nowhere else.
-      const current = dynamicContext && route && schema === route.key ? currentOf(cfg) : null
+    for (const [schema, { cfg, held }] of fills) {
+      if (held !== undefined) {
+        // The block holds this fetch's answer already — a static build prerendered it.
+        data[schema] = held
+        continue
+      }
+      // How this fetch uses the page's record: by the query it names (`currentFor`).
+      const current = dynamicContext ? currentFor(cfg, route) : null
       if (current === 'exclude') {
-        // The route query's records without this page's, `limit` counting the others.
+        // The query's records without this page's, `limit` counting the others.
         const cached = dispatcher?.peek(othersView(cfg), ctx)
         if (cached) {
           data[schema] = othersOf(cached.data, cfg, isPageRecord(dynamicContext))
@@ -245,8 +306,9 @@ export default class EntityStore {
       } else if (current === 'only') {
         // Detail page: deliver the focused record as a length-1 array under the
         // query key. A deferred/remote query fetches the full per-record;
-        // others use the matched record. Not found → []. Found in the route
-        // query's whole selection, never in a list its `limit` cut (`routeSelection`).
+        // others use the matched record. Not found → []. Found in the set of the
+        // query the fetch names — the route query's, or another's under `current: only`
+        // — never in a list a fetch narrowed (`routeSelection`).
         const cached = dispatcher?.peek(routeSelection(cfg), ctx)
         if (cached) {
           const { paramName, paramValue } = dynamicContext
@@ -279,8 +341,8 @@ export default class EntityStore {
           allCached = false
         }
       } else {
-        // Any other key — and `current: include`, the route query's list as the
-        // binding describes it, this page's record among the rest.
+        // A fetch the page's record plays no part in (`currentFor`), and `current:
+        // include`: the records as the fetch describes them, the page's among the rest.
         const cached = dispatcher?.peek(cfg, ctx)
         if (cached) {
           data[schema] = cached.data
@@ -291,7 +353,7 @@ export default class EntityStore {
     }
 
     if (allCached) {
-      this._applyDetailRoutes(data, configs, block.website)
+      this._applyRecordRoutes(data, configs, block.website)
       return { status: 'ready', data }
     }
     return { status: 'pending', data: null }
@@ -319,17 +381,10 @@ export default class EntityStore {
     const dispatcher = this.website?.fetcher
     if (!dispatcher) return { data: null, errors: null }
 
-    let requested = this._getRequestedSchemas(meta)
-    if (requested === null && block.fetch) {
-      const blockFetchList = Array.isArray(block.fetch) ? block.fetch : [block.fetch]
-      const schemas = blockFetchList.filter(bindingKeyOf).map(bindingKeyOf)
-      if (schemas.length > 0) requested = schemas
-    }
-    if (requested === null) return { data: null, errors: null }
-
     const route = this._route(block)
-    const configs = this._findFetchConfigs(block, requested, route)
-    if (configs.size === 0) return { data: null, errors: null }
+    const fills = this._fills(block, meta, route)
+    if (fills.size === 0) return { data: null, errors: null }
+    const configs = new Map([...fills].map(([key, { cfg }]) => [key, cfg]))
 
     const dynamicContext = block.dynamicContext || block.page?.dynamicContext
     const ctx = this._ctx(block, { signal })
@@ -342,12 +397,18 @@ export default class EntityStore {
       reportFetchFailure(this.dev, block, key, cfg, message)
     }
 
-    for (const [schema, cfg] of configs) {
-      // `current:` applies under the key the page's URL narrows, and nowhere else.
-      const current = dynamicContext && route && schema === route.key ? currentOf(cfg) : null
+    for (const [schema, { cfg, held }] of fills) {
+      if (held !== undefined) {
+        // The block holds this fetch's answer already — a static build prerendered it.
+        data[schema] = held
+        continue
+      }
+      // How this fetch uses the page's record: by the query it names (`currentFor`).
+      const current = dynamicContext ? currentFor(cfg, route) : null
       if (current === 'exclude') {
-        // The route query's records without this page's, `limit` counting the others:
-        // asked one longer (`othersView`), so removing the record still leaves enough.
+        // The query's records without this page's, the fetch's `limit` counting
+        // the others: its `narrow.limit` asked one higher (`othersView`), so removing
+        // the record still leaves enough.
         const view = othersView(cfg)
         parallelFetches.push(dispatcher.dispatch(view, ctx).then((result) => {
           if (result?.error) {
@@ -360,14 +421,15 @@ export default class EntityStore {
         }))
       } else if (current === 'only' && cfg.ask) {
         // ⭐ THE RECORDS SERVICE needs no list to find the record: the record is the
-        // same question narrowed by the route's handle, so list and record are
-        // asked together — one round trip, and no client-side scan gating the
-        // fetch (F13, the live half). The list is asked too, because the record
-        // index files its briefs; the record's own answer is the answer.
+        // query's set narrowed by the route's handle, so its one question
+        // answers the record if the set holds it and `[]` if not — no client-side
+        // scan gating the fetch (F13, the live half).
+        //
+        // ⛔ The list was asked beside it until 2026-09-14, for the record index to
+        // file its briefs, while the record question dropped the query's `sort` and
+        // `limit` and so could not say whether the set held the record. It checks the
+        // set now, and the list sent the whole set to render one record of it.
         const detailCfg = this._buildDetailConfig(cfg, dynamicContext)
-        parallelFetches.push(dispatcher.dispatch(cfg, ctx).then((result) => {
-          if (result?.error) fail(schema, cfg, result.error)
-        }))
         parallelFetches.push(dispatcher.dispatch(detailCfg, ctx).then((result) => {
           if (result?.error) {
             fail(schema, detailCfg, result.error)
@@ -377,9 +439,9 @@ export default class EntityStore {
           data[schema] = answer.slice(0, 1) // a route resolves to ONE; `[]` is not found
         }))
       } else if (current === 'only') {
-        // Detail page: focused record as a length-1 array under the query key,
-        // found in the route query's whole selection (`routeSelection`) — a record
-        // past a list's `limit` still has its page.
+        // Detail page: focused record as a length-1 array under the fetch's key,
+        // found in its query's set (`routeSelection`) — a record past a
+        // fetch's `limit` still has its page, and one past the query's has none.
         const { paramName, paramValue } = dynamicContext
         const selection = routeSelection(cfg)
 
@@ -450,7 +512,7 @@ export default class EntityStore {
     }
 
     if (parallelFetches.length > 0) await Promise.all(parallelFetches)
-    this._applyDetailRoutes(data, configs, block.website)
+    this._applyRecordRoutes(data, configs, block.website)
     return { data, errors: Object.keys(errors).length ? errors : null }
   }
 }
@@ -505,20 +567,37 @@ function peekArray(dispatcher, cfg, ctx) {
 }
 
 /**
- * Interpolate a record's fields into a detail-page route template to build its
- * `route` (the canonical href for a card). `/blog/:slug` + `{ slug: 'a-post' }`
- * → `/blog/a-post`. Returns a SHALLOW COPY with `route` added — never mutates the
- * cached record (the same query may back several sections with different
- * detail pages). Idempotent + back-compat: a record that already carries a `route`
- * (the file lane bakes one via the query processor) is returned untouched. A
- * `:param` with no matching record field → no `route` (graceful; degrades to the
- * component's own fallback rather than emitting a broken href).
+ * The route template a fetch's records link to — its `detailPage`, else its query's page.
+ *
+ * ⭐ A `detailPage` that no longer resolves — its page deleted, or no longer parametric —
+ * falls back to the query's own page rather than taking every card's link away: the
+ * author picked among the query's pages, and the query still has one. (The website warns
+ * in dev when a ref dangles.)
+ *
+ * @param {Object} cfg - a resolved config
+ * @param {Object} website
+ * @returns {string|null}
+ */
+function recordRouteTemplate(cfg, website) {
+  if (cfg?.detailPage) {
+    const picked = website.resolveDetailPageTemplate?.(cfg.detailPage)
+    if (picked) return picked
+  }
+  return typeof cfg?.query === 'string' ? (website.recordPageFor?.(cfg.query)?.route ?? null) : null
+}
+
+/**
+ * A record with its `$route` — the template filled from the record's own fields
+ * (`/blog/:slug` + `{ $name: 'a-post' }` → `/blog/a-post`). A SHALLOW COPY, never the
+ * cached record. A record that cannot fill the template — a `:param` with no value on it
+ * — is returned as it is, with no `$route`, so a component renders no link rather than a
+ * broken one.
  *
- * ⭐ The encoding is `fillRoutePattern`'s, shared with the build's bake, so the
- * two producers of `item.route` agree — they did not (F14, 2026-09-04).
+ * ⭐ The encoding is `fillRoutePattern`'s: the one encoder for a record's href, which the
+ * route matcher decodes (F14, 2026-09-04).
  */
-function addDetailRoute(item, template) {
-  if (!item || typeof item !== 'object' || item.route !== undefined) return item
+function withRecordRoute(item, template) {
+  if (!item || typeof item !== 'object') return item
   const route = fillRoutePattern(template, item)
-  return route === null ? item : { ...item, route }
+  return route === null || item.$route === route ? item : { ...item, $route: route }
 }