@uniweb/runtime 0.24.0 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/runtime",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Minimal runtime for loading Uniweb foundations",
   "type": "module",
   "exports": {
@@ -36,7 +36,7 @@
     "node": ">=20.19"
   },
   "dependencies": {
-    "@uniweb/core": "^0.28.0",
+    "@uniweb/core": "^0.29.0",
     "@uniweb/theming": "^0.1.15"
   },
   "devDependencies": {
@@ -44,7 +44,7 @@
     "esbuild": "^0.21.0 || ^0.23.0 || ^0.24.0 || ^0.25.0 || ^0.27.0",
     "vite": "^7.3.1",
     "vitest": "^4.1.7",
-    "@uniweb/build": "0.48.0"
+    "@uniweb/build": "0.49.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/collect-records.js

@@ -15,19 +15,21 @@
  * page render uses**, applying each saved query's own `scope` and `where` — and
  * asks through the same client.
  *
- * ## ⛔ `limit` IS DROPPED, and it is the one place a corpus must diverge
+ * ## ⭐ Each query is asked AS SAVED — its `limit` included
  *
- * A saved query's `limit` is the LIST PAGE's presentation: `limit: 20` means the
- * page shows twenty. **Its detail pages still exist for every record matching
- * `scope` + `where`** — so a corpus that honoured `limit` would index twenty and
- * miss every page beyond them, which is worse than indexing nothing because the
- * gap is invisible.
+ * A query defines its SET: the records its `scope` and `where` select, in its
+ * `sort`, up to its `limit` (ruled 2026-09-14 [Diego]). A parametric page has a URL
+ * for each record of its route query's set and no other, so the set is exactly the
+ * population a site's pages reach — a field note older than a query's 100 most recent
+ * has no page to index. Asked with no `narrow`, the service answers the set whole in
+ * one answer, so a walk has nothing to page; it still follows a cursor if one ever
+ * comes back, bounded by `maxPages`.
  *
- * ⚠️ **This shipped wrong in 0.17.0 and was found by the consumer, not by us**
- * (2026-09-06): the config was passed through unchanged, `limit` crossed as the
- * question's own, and the corpus was capped. The claim that this surface met
- * "the population its detail pages can reach" was made *"read charitably"* — a
- * phrase doing work that one `sed` would have done better.
+ * ⛔ **Until 2026-09-14 this dropped the query's `limit`**, on the rule it replaced — a
+ * `limit` was the list page's presentation and every record matching `scope` + `where`
+ * had a page — which was right under that rule. ⚠️ And that rule's own history: the
+ * first version, in 0.17.0, passed `limit` through while claiming the corpus was the
+ * population detail pages reach, and the consumer found it (2026-09-06).
  *
  * ## What the caller supplies
  *
@@ -61,15 +63,16 @@ import { createDefaultFetcher } from './default-fetcher.js'
  *   list shows; **`true` — whole records — is what an index wants**: a brief index
  *   cannot match body text the record's own detail page displays, and a reader who
  *   finds a word on the page and not in search meets the inconsistency two
- *   rankings would produce. The cost is the caller's and is bounded by `maxPages`.
- *   An external query is never collected — it has no records service to ask.
- * @param {number} [options.maxPages] - the caller's own bound on the walk. The
- *   default is a bound, not a target; a caller that knows its per-request budget
- *   passes its own.
+ *   rankings would produce. The cost is the caller's, and bounded by each query's
+ *   own `limit`. An external query is never collected — it has no records service
+ *   to ask.
+ * @param {number} [options.maxPages] - the caller's own bound on a walk that pages. A
+ *   question with no `narrow` is answered whole with no cursor, so today's walk is one
+ *   request per query; the bound holds should a service page anyway.
  * @returns {Promise<{records: Object, errors: Object|null, meta: Object}>}
  *   `records` is keyed by query NAME, each a flat array; `errors` is keyed the
- *   same and is null when nothing failed; `meta[name]` carries
- *   `{ depth, pages, partial?, bound? }`.
+ *   same and is null when nothing failed; `meta[name]`, when there is anything to
+ *   say, carries `{ whole?, pages?, partial?, unavailable? }`.
  *
  *   ⭐ **`partial` means NOT THE WHOLE POPULATION**, and a key can be in BOTH
  *   `records` and `errors`: a walk that failed or was aborted with pages already
@@ -110,9 +113,8 @@ export async function collectSiteRecords(
     // `path` has no live lane, and reading that file is the caller's business,
     // not ours — it is in the site's own URL space and they already serve it.
     if (!cfg.ask) return
-    // `limit` is the list page's, never the corpus's — see the header.
-    const { limit, ...population } = cfg
-    const asked = { ...population, whole, exhaustive: true }
+    // The query as saved — the set its pages reach, its `limit` included; see the header.
+    const asked = { ...cfg, whole, exhaustive: true }
     if (typeof maxPages === 'number' && maxPages > 0) asked.maxPages = maxPages
 
     const result = await fetcher.resolve(asked, { signal })

package/src/default-fetcher.js

@@ -15,10 +15,11 @@
  *     question the page asked, answered per key (the records contract, as this
  *     client reads it).
  *
- * `where:` / `sort:` / `limit:` are evaluated HERE, locally, over what the
- * first lane returns — with `@uniweb/core`'s one evaluator, the same the build
- * uses to materialize a file — and at the source when asked. Nothing decides
- * that per site: the LANE decides.
+ * A query's set — `scope:` / `where:` / `sort:` / `limit:` — and the `narrow`
+ * a fetch takes of it are evaluated HERE, locally, over what the first lane
+ * returns — with `@uniweb/core`'s one evaluator (`evaluateQuery`), the same the
+ * build uses — and at the source when asked. Nothing decides that per site: the
+ * LANE decides.
  *
  * ⛔ RETIRED 2026-09-04 [Diego]: `fetcher.baseUrl`, `headers`, `envelope`,
  * `supports`, `request.style` / `request.rename` and the `json-body`
@@ -52,8 +53,7 @@
 
 import {
   substitutePlaceholders,
-  matchWhere,
-  applyScope,
+  evaluateQuery,
   sortRecords,
   sortToWire,
   deriveCacheKey,
@@ -230,14 +230,27 @@ export function createDefaultFetcher({ basePath = '', dev = false, fetch: fetchI
 
 /**
  * One question of a batch, in the records service's own vocabulary
- * (the records contract, §2): `schema` required, `scope` a bare path, `sort`
- * one key spelled `date` / `-date`, `whole` when the whole record is wanted,
- * `match` on a parametric page's record. ⭐ The where-object crosses exactly as
- * authored: the evaluator and the service speak one language (`@uniweb/core`'s where evaluator).
- * ⛔ `nin` was respelled `not_in` here until 2026-09-13, when the evaluator took
- * `not_in` as its only spelling. Anything the service does not answer (a dotted
- * path, a retired operator) is sent as written and answered there: never
- * approximated.
+ * (the records contract, §2).
+ * ⭐ TWO LEVELS, ruled 2026-09-14 [Diego]:
+ *
+ *   - **the top level is the query as saved** — `schema` (required), `scope` a bare
+ *     path, `where`, `sort` one key spelled `date` / `-date`, `limit` — and `whole`
+ *     when the whole record is wanted. Its records are the set, and the top level is
+ *     the same on every question about it;
+ *   - **`narrow`** — how this page takes less than the set: `where`, `match` (a
+ *     parametric page's record), `sort`, `cursor` (to resume a previous answer) and
+ *     `limit`. Absent when the question asks for the set as it is.
+ *
+ * ⛔ Until 2026-09-14 the two were one flat question — the page's `where` joined the
+ * query's, its `sort` and `limit` replaced the query's — and `match` and `cursor` sat
+ * at the top level, where the service no longer takes them. There is no fallback:
+ * the service answers an unknown or misplaced field with a `400` for the request.
+ *
+ * ⭐ A where-object crosses exactly as authored: the evaluator and the service speak
+ * one language (`@uniweb/core`'s where evaluator). ⛔ `nin` was respelled `not_in`
+ * here until 2026-09-13, when the evaluator took `not_in` as its only spelling.
+ * Anything the service does not answer (a retired operator) is sent as written and
+ * answered there: never approximated.
  */
 function toQuestion(request) {
   const q = { schema: request.schema }
@@ -248,26 +261,61 @@ function toQuestion(request) {
   const scope = typeof request.scope === 'string' && request.scope ? request.scope : null
   if (scope) q.scope = scope
   if (where) q.where = where
-  // ⭐ The record of a parametric page: the question unchanged plus `match` — one
-  // key and the URL's value, beside the author's `where`, never merged into it
-  // (`buildDetailConfig`; the records contract as we read it, §1d).
-  if (request.match && typeof request.match === 'object') q.match = request.match
-  const sort = sortToWire(request.sort)
+  const sort = wireSort(request.sort)
   if (sort) q.sort = sort
   if (typeof request.limit === 'number' && request.limit > 0) q.limit = request.limit
   // ⛔ ONLY WHEN TRUE. The brief is the default and absent means the brief, so
   // sending `whole: false` would be noise on every list question the client makes.
   if (request.whole === true) q.whole = true
-  // ⭐ `cursor` is the ONLY field here that is not the author's: it is opaque and
-  // it comes from a previous answer's `cursors` (the records contract §2). ⛔ And
-  // `exhaustive` deliberately does NOT cross — it is a client instruction about
-  // how many times to ask, not part of the question being asked.
-  if (typeof request.cursor === 'string' && request.cursor) q.cursor = request.cursor
-  // ⛔ `maxPages` does not cross either, for the same reason `exhaustive` does not:
-  // both say how many times to ask, never what is being asked.
+  const narrow = toNarrow(request.narrow)
+  if (narrow) q.narrow = narrow
+  // ⛔ `exhaustive` and `maxPages` deliberately do NOT cross — they are client
+  // instructions about how many times to ask, never part of what is being asked.
   return q
 }
 
+/**
+ * A question's `narrow`, with only the fields the service takes inside it — any other
+ * is a `400` for the whole request there — or `null` when nothing is left.
+ *
+ *   - `where` crosses as authored;
+ *   - `match` — the record of a parametric page: one key and the URL's value, beside
+ *     the author's `where`, never merged into it (`buildDetailConfig`);
+ *   - `sort` in the service's spelling;
+ *   - ⭐ `cursor` — the ONLY field in a question that is not the author's: opaque, from a
+ *     previous answer's `cursors`, sent back on the same question and nothing else
+ *     changed. A cursor is a narrowing like the rest, so the top level stays the query as
+ *     saved on every page;
+ *   - `limit`, when it cuts.
+ */
+function toNarrow(narrow) {
+  if (!narrow || typeof narrow !== 'object') return null
+  const n = {}
+  if (narrow.where && typeof narrow.where === 'object') n.where = narrow.where
+  if (narrow.match && typeof narrow.match === 'object') n.match = narrow.match
+  const sort = wireSort(narrow.sort)
+  if (sort) n.sort = sort
+  if (typeof narrow.cursor === 'string' && narrow.cursor) n.cursor = narrow.cursor
+  if (typeof narrow.limit === 'number' && narrow.limit > 0) n.limit = narrow.limit
+  return Object.keys(n).length > 0 ? n : null
+}
+
+/**
+ * A `sort` in the service's spelling — `date` / `-date` — or, for one outside the
+ * language, the author's text AS WRITTEN, which the service answers by its own rule
+ * (ignored: the author's arrangement). ⛔ Never a throw: this runs while a page's whole
+ * batch is being composed, before any request, and until 2026-09-14 a sort `parseSort`
+ * refuses — two keys, a bad direction — threw here and left every question of the batch
+ * pending forever.
+ */
+function wireSort(sort) {
+  try {
+    return sortToWire(sort)
+  } catch {
+    return typeof sort === 'string' && sort.trim() ? sort : null
+  }
+}
+
 /**
  * Send one batch to the records service and hand each question its own answer.
  *
@@ -275,8 +323,9 @@ function toQuestion(request) {
  * contract rev D, 2026-09-13), each map absent when empty: `data` answers exactly the
  * keys sent — `[]` when nothing matched, and `[]` too for a question an author got
  * wrong, since the service answers a mistake rather than refusing it; `whole[key]` says
- * a key was served as whole records; `cursors[key]` that more records remain under the
- * question's `limit`; `partial[key]` that a source of the key did not answer. A key
+ * a key was served as whole records; `cursors[key]` that more records remain past the
+ * question's `narrow.limit` — a query's own `limit` defines the set and never produces
+ * one; `partial[key]` that a source of the key did not answer. A key
  * missing from `data` is a protocol violation and is reported as an error, never as
  * silence. ⛔ `errors` and `limits` are not read: the service stopped sending them in
  * the same revision, and this client read both until 2026-09-14.
@@ -430,10 +479,13 @@ async function flushAsked(url, queue, doFetch) {
   if (pending.size === 0) return
   // Re-ask each unfinished key on its own — the cursor is per key, so a batch
   // would have to correlate several independent positions through one body.
+  // ⭐ The cursor rides inside `narrow` and NOTHING ELSE in the question changes: the
+  // service resumes only the question a cursor came from, and answers a cursor sent
+  // with anything else changed with a `400`.
   await Promise.all([...pending].map(([entry, state]) => {
     const next = {
       ...entry,
-      request: { ...entry.request, cursor: state.cursor },
+      request: { ...entry.request, narrow: { ...(entry.request.narrow || {}), cursor: state.cursor } },
       collected: state.collected,
       page: state.page,
     }
@@ -489,20 +541,16 @@ function sortLocale(request, ctx) {
 
 /**
  * Evaluate the query over what the source returned — the ONE evaluator,
- * `@uniweb/core`'s, so the browser orders and filters exactly as the build
- * did when it materialized `/data/<name>.json`.
+ * `@uniweb/core`'s `evaluateQuery`, so the browser orders and filters exactly as
+ * the build does: the query's set first (`scope` over each record's placement,
+ * `where`, `sort`, `limit`), then the fetch's `narrow` of it. Only the sort is this
+ * lane's own, for what it does with a bad `sort:` in production.
  */
 function applyOperators(data, request, { dev = false, locale = null } = {}) {
-  if (!Array.isArray(data)) return data
-  let result = data
-  // `scope` first: it names the branch the rest of the query reads. On this lane
-  // it is evaluated over each record's placement (`path`), as the build did when it
-  // wrote the file — `scope: :dir` bound per page reaches here (2026-09-11).
-  if (typeof request.scope === 'string' && request.scope) result = applyScope(result, request.scope)
-  if (request.where) result = matchWhere(request.where, result)
-  if (request.sort) result = applySort(result, request.sort, dev, locale)
-  if (typeof request.limit === 'number' && request.limit > 0) result = result.slice(0, request.limit)
-  return result
+  return evaluateQuery(data, request, {
+    locale,
+    sort: (items, sortExpr, options) => applySort(items, sortExpr, dev, options.locale),
+  })
 }
 
 /**

package/src/prefetch.js

@@ -50,7 +50,7 @@
  * `{base}/…` from the payload, or the records service the host itself
  * published at `config.services.records`.
  */
-import { resolveFetchConfigs, pageRouteQuery, routeSelection, currentOf, othersView, siteReaches } from '@uniweb/core/fetch-config'
+import { resolveFetchConfigs, fetchEntries, pageRouteQuery, routeSelection, currentFor, othersView, siteReaches } from '@uniweb/core/fetch-config'
 import { deriveCacheKey } from '@uniweb/core/datastore'
 import { findPageForRoute, isDynamicRoute, routeBinding, parentRouteOf } from '@uniweb/core/route-match'
 import { buildDetailConfig } from '@uniweb/core/detail-url'
@@ -149,7 +149,6 @@ export function resolvePageFetchConfigs(content, route, { locale = null } = {})
         site: siteFetch,
       })
     : null
-  const routeKey = chosen?.key ?? null
   // A nested page's sections receive its capturing page's route binding, which the
   // one-parent cascade may not reach — the entity store adds it the same way.
   const routeSource = chosen?.nested ? chosen.config : null
@@ -159,33 +158,42 @@ export function resolvePageFetchConfigs(content, route, { locale = null } = {})
     const key = deriveCacheKey(cfg)
     if (!out.has(key)) out.set(key, cfg)
   }
+  // ⭐ EVERY fetch of every level, each resolved on its own — not the first per key. A section
+  // receives the keys its component declares, and two fetches of one `as` at two levels can
+  // fill two of them (`fillDeclaredKeys`, 2026-09-14), which a prefetch holding no
+  // component's meta cannot rule out. A superset, which a prefetch can afford.
   const add = (sources) => {
-    for (const cfg of resolveFetchConfigs(sources, options).values()) {
-      const current = routeKey && cfg.as === routeKey ? currentOf(cfg) : null
+    const resolved = sources.flatMap((source) => fetchEntries(source).map((entry) => resolveFetchConfigs([entry], options).get(entry.as)))
+    for (const cfg of resolved.filter(Boolean)) {
+      // how the fetch uses the page's record — by the query it names, as the entity store asks
+      const current = currentFor(cfg, chosen)
       if (current === 'exclude') {
         // the list one longer, from which the render removes the page's record
         put(othersView(cfg))
         continue
       }
       if (current !== 'only') {
-        // any other key, or `current: include` — the list as the binding describes it
+        // no part for the page's record, or `current: include` — the list as the fetch describes it
         put(cfg)
         continue
       }
       // ⭐ A parametric page is ABOUT one record, and on a lane with a per-record
       // source (the records service, a `deferred:` query's per-record file) that
-      // record is a request of its own. Built for EVERY config the route key
-      // resolves to — a section re-declaring the route query asks its own record
-      // question — by the one rule the entity store uses (`buildDetailConfig`), so
-      // the question prefetched is the question the render asks.
+      // record is a request of its own. Built for EVERY config that takes the page's
+      // record, by the one rule the entity store uses (`buildDetailConfig`), so
+      // the question prefetched is the question the render asks — and since that
+      // question drops a fetch's own narrowing, sections that narrow differently ask
+      // one record question between them.
       if (cfg.detail && binding.paramValue !== undefined) {
         const detailCfg = buildDetailConfig(cfg, { paramName: binding.paramName, paramValue: String(binding.paramValue) })
         if (detailCfg) put(detailCfg)
       }
-      // On the records service the list is asked beside the record; off it, the
-      // record is FOUND in the route query's whole selection — the list without its
-      // `limit` (`routeSelection`) — which is all the render reads for it.
-      put(cfg.ask ? cfg : routeSelection(cfg))
+      // ⭐ On the records service the record question checks the query's set on its
+      // own, so nothing else is asked. Off it, the record is FOUND in the set —
+      // the query as saved, without the fetch's `narrow` (`routeSelection`) — which is
+      // all the render reads for it. ⛔ Until 2026-09-14 the service's list was asked
+      // beside the record, and the page embedded the whole set to show one record.
+      if (!cfg.ask) put(routeSelection(cfg))
     }
   }
   // The cascade a block sees: its own fetch, page, parent, a nested page's route

package/src/prepare-props.js

@@ -313,27 +313,54 @@ export function applyDefaults(params, defaults) {
 }
 
 /**
- * Merge entity data onto a block's parsedContent.data.
+ * ⭐ `content.data` HOLDS THE KEYS THE COMPONENT DECLARES, AND NOTHING ELSE — ruled 2026-09-14
+ * [Diego]. Every key in its `meta.js` `data:` and its foundation's `main.js` `data:`
+ * (`website.declaredKeys`), each filled, in order, from:
  *
- * Section-level data already on the block (from prerender fetches via
- * blockData.parsedContent.data in the Block constructor) takes priority;
- * entity data only fills missing keys. Mutates `block.parsedContent.data`
- * in place so the vanilla JS layer holds the assembled data and
- * subsequent reads see the same shape.
+ *   1. what the section holds under that key (`block.heldData`) — a tagged data block, or
+ *      its own fetch's answer a static build prerendered into it;
+ *   2. what the entity store delivered for it — the fetch that fills it (`fillDeclaredKeys`);
+ *   3. `null` — nothing fills it, or its fetch is still out (`block.dataLoading`) or failed
+ *      (`block.dataError[key]`). ⭐ Never `[]`, which is an answer with no records.
+ *
+ * A tagged data block under a key the component does not declare is left out, and said so
+ * in dev (`warnUndeclaredBlocks`); it stays in `content.sequence`. The data object is
+ * rebuilt on each render from those sources, never from the last render's.
+ *
+ * ⛔ Until 2026-09-14 this merged every delivered key into what the section held, so a
+ * section received every fetch that reached it and every tagged block it had.
  */
-function mergeEntityData(block, entityData) {
-  if (!entityData) return
-  const current = block.parsedContent.data || {}
-  let changed = false
-  const merged = { ...current }
-  for (const key of Object.keys(entityData)) {
-    if (merged[key] === undefined) {
-      merged[key] = entityData[key]
-      changed = true
-    }
+function assembleData(block, meta, entityData) {
+  const declared = block.website?.declaredKeys ? block.website.declaredKeys(meta) : []
+  const held = block.heldData || {}
+  const data = {}
+  for (const [key] of declared) {
+    if (held[key] !== undefined) data[key] = held[key]
+    else if (entityData && entityData[key] !== undefined) data[key] = entityData[key]
+    else data[key] = null
   }
-  if (changed) {
-    block.parsedContent.data = merged
+  warnUndeclaredBlocks(block, declared)
+  block.parsedContent.data = data
+}
+
+/**
+ * Say once, in dev, that a tagged data block did not reach its section's component — its
+ * key is not declared. The block is still in `content.sequence`, where a component that
+ * renders the sequence finds it.
+ */
+const warnedBlocks = new Set()
+function warnUndeclaredBlocks(block, declared) {
+  if (!block.website?.entityStore?.dev) return
+  const keys = new Set(declared.map(([key]) => key))
+  for (const item of block.parsedContent?.sequence || []) {
+    if (item?.type !== 'dataBlock' || typeof item.tag !== 'string' || keys.has(item.tag)) continue
+    const memo = `${block.type}::${item.tag}`
+    if (warnedBlocks.has(memo)) continue
+    warnedBlocks.add(memo)
+    console.warn(
+      `[uniweb] ${block.type}: the \`${item.tag}\` data block is not in content.data — ${block.type} does not ` +
+        `declare \`${item.tag}\` in its meta.js \`data:\`. It stays in content.sequence.`
+    )
   }
 }
 
@@ -434,8 +461,9 @@ function runPropsHandler(content, params, block) {
  * renderers (`BlockRenderer.jsx` CSR and `ssr-renderer.js` SSG) share
  * the same code path:
  *
- *   1. Merge entity data (resolved by EntityStore) onto
- *      `block.parsedContent.data`.
+ *   1. Assemble `block.parsedContent.data` from the keys the component
+ *      declares: what the section holds, else what EntityStore delivered,
+ *      else `null` (`assembleData`).
  *   2. Run the foundation data handler (if registered) to filter or
  *      reshape the assembled data.
  *   3. Run the foundation content handler (if registered) on the
@@ -456,7 +484,11 @@ function runPropsHandler(content, params, block) {
  * @returns {Object} Prepared props: { content, params }
  */
 export function prepareProps(block, meta, entityData = null) {
-  mergeEntityData(block, entityData)
+  assembleData(block, meta, entityData)
+  // ⭐ A list the section held before the store answered — its own fetch, prerendered
+  // into its content by a static build — gets its records' `$route` by the store's rule,
+  // which the store did not deliver it by (2026-09-14).
+  block.website?.entityStore?.linkOwnRecords?.(block)
   runDataHandler(block)
   runContentHandler(block)
 

package/src/ssr-renderer.js

@@ -231,8 +231,8 @@ export function renderBlock(block, { as = 'section' } = {}) {
     }, `Component not found: ${block.type}`)
   }
 
-  // Resolve inherited entity data synchronously (SSG has no async).
-  // EntityStore walks page/site hierarchy to find data matching meta.inheritData.
+  // Resolve entity data synchronously (SSG has no async): EntityStore fills the keys
+  // the component declares (`meta.data`) from the fetches that reach the block.
   const meta = getComponentMeta(block.type)
   const entityStore = block.website?.entityStore
   let entityData = null