@uniweb/runtime 0.22.0 → 0.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/runtime",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Minimal runtime for loading Uniweb foundations",
   "type": "module",
   "exports": {
@@ -36,7 +36,7 @@
     "node": ">=20.19"
   },
   "dependencies": {
-    "@uniweb/core": "^0.26.2",
+    "@uniweb/core": "^0.27.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.47.1"
+    "@uniweb/build": "0.47.2"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/default-fetcher.js

@@ -26,16 +26,17 @@
  * foundation level… making the runtime+core lean."* A backend with its own
  * base, headers, wire or query language is a TRANSPORT — a named
  * `{ resolve, cacheKey? }` the foundation (or an extension) registers and
- * the site selects per schema in `fetcher.transports`. The build warns once
+ * the site selects per binding key (`as`) in `fetcher.transports`. The build warns once
  * and drops a retired key from the payload, so an author's backend does not
  * silently stop being reached.
  *
- * Per-fetch, the request may still carry `method: 'POST'` + `body:` for a
- * backend that takes a query in a body (GraphQL, a search endpoint);
- * `{paramName}` placeholders in body strings are substituted from
- * `request.dynamicContext`, so a template page's detail query can reference
- * its route param. `transform:` and the object form of `detail:` (its own
- * `envelope`) stay per fetch too — they describe ONE response, not a backend.
+ * A request may carry `method: 'POST'` + `body:` for an endpoint that takes a
+ * query in a body (GraphQL, a search endpoint) — an external query's, or its
+ * `record:` request's — and `transform:`, a dot-path to the records in ONE
+ * response. `{paramName}` placeholders in body strings are substituted from
+ * `request.dynamicContext`, so a parametric page's record request can reference
+ * its route param. ⛔ `envelope` (the object form of `detail:`) is retired with
+ * it, 2026-09-13: a record request's own `transform` is `record.transform`.
  *
  * Exported from a subpath — `@uniweb/runtime/default-fetcher` — for
  * runtime-level callers (the editor's preview iframe, custom runtime
@@ -192,42 +193,16 @@ export function createDefaultFetcher({ basePath = '', dev = false, fetch: fetchI
         const response = await readOnce(target, init)
         if (ctx.signal?.aborted) return { data: [], error: 'aborted' }
 
-        // A per-request envelope (set by the object form of `detail:`) describes
-        // this one response.
-        const envelope = (request.envelope && typeof request.envelope === 'object')
-          ? request.envelope
-          : {}
-
         if (!response.ok) {
-          // If `envelope.error` names a path, try to extract a human message
-          // from the parsed body; fall back to status text if the path is
-          // missing or the body isn't JSON.
-          let extracted
-          if (envelope.error && typeof response.text === 'string') {
-            const body = safeParseJSON(response.text)
-            if (body !== undefined) {
-              const candidate = getNestedValue(body, envelope.error)
-              if (typeof candidate === 'string' && candidate.length) {
-                extracted = candidate
-              }
-            }
-          }
-          return {
-            data: [],
-            error: extracted ?? `HTTP ${response.status}: ${response.statusText}`,
-          }
+          return { data: [], error: `HTTP ${response.status}: ${response.statusText}` }
         }
 
         let data = response.body
 
-        // Unwrap the response. Per-fetch `transform:` wins; otherwise the
-        // envelope's `item` path on a single-record request, `list` on a list.
-        const isDetailRequest = !!request.dynamicContext
-        const effectiveTransform =
-          transform
-          || (isDetailRequest ? envelope.item : envelope.list)
-        if (effectiveTransform && data !== null && data !== undefined) {
-          data = getNestedValue(data, effectiveTransform)
+        // Unwrap the response: the request's own `transform:`, and nothing else — a
+        // record request carries its `record.transform`, never the list's.
+        if (transform && data !== null && data !== undefined) {
+          data = getNestedValue(data, transform)
         }
 
         // Evaluate the query locally. Only applies to array data
@@ -257,11 +232,12 @@ 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 as authored
- * except for the one spelling the language settled differently from the
- * evaluator's: `nin` is `not_in` there. Anything the service does not accept
- * (`like`, a dotted path) is sent as written and refused there by name: loud,
- * never approximated.
+ * `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.
  */
 function toQuestion(request) {
   const q = { schema: request.schema }
@@ -271,7 +247,7 @@ function toQuestion(request) {
   // [Diego] — the build refuses it now, so there is nothing left to respell.
   const scope = typeof request.scope === 'string' && request.scope ? request.scope : null
   if (scope) q.scope = scope
-  if (where) q.where = renameOperators(where)
+  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).
@@ -292,17 +268,6 @@ function toQuestion(request) {
   return q
 }
 
-const OPERATOR_ALIAS = { nin: 'not_in' }
-function renameOperators(where) {
-  if (Array.isArray(where)) return where.map(renameOperators)
-  if (!where || typeof where !== 'object') return where
-  const out = {}
-  for (const [key, value] of Object.entries(where)) {
-    out[OPERATOR_ALIAS[key] ?? key] = value && typeof value === 'object' ? renameOperators(value) : value
-  }
-  return out
-}
-
 /**
  * Send one batch to the records service and hand each question its own answer.
  *
@@ -491,8 +456,8 @@ async function flushAsked(url, queue, doFetch) {
 /**
  * Read one response and parse its body — the part of a fetch every view of an
  * address shares. A JSON body is parsed as JSON; anything else is tried as JSON
- * and kept as text when it is not. A failed response keeps its text, so a view
- * whose envelope names an error path can read a message out of it.
+ * and kept as text when it is not. A failed response keeps its text, so a caller
+ * can read a message out of it (the records service's problem details).
  */
 async function readResponse(doFetch, target, init) {
   const response = await doFetch(target, init)

package/src/prefetch.js

@@ -50,15 +50,14 @@
  * `{base}/…` from the payload, or the records service the host itself
  * published at `config.services.records`.
  */
-import { resolveFetchConfigs, routeQuery, sectionFetches } from '@uniweb/core/fetch-config'
+import { resolveFetchConfigs, pageRouteQuery, routeSelection, currentOf, 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'
 import { resolveDefaultLocale } from '@uniweb/core/locale-config'
+import { findLayoutEntry } from '@uniweb/core/layout-name'
 import { createDefaultFetcher } from './default-fetcher.js'
 
-const isRefinement = (f) => f && typeof f === 'object' && f.refine === true
-
 /**
  * ⭐ **RE-EXPORTED, NOT IMPLEMENTED HERE — the rule lives in `@uniweb/core/route-match`.**
  *
@@ -88,11 +87,36 @@ function parentPageOf(page, pages) {
   return route ? byRoute.get(route) : null
 }
 
+/**
+ * The layout sections a page may render — every section of the layout areas it can
+ * use, subsections included. A page that names a layout uses that set (matched as the
+ * runtime matches it, `@uniweb/core/layout-name`) and nothing else; a page that names
+ * none uses its foundation's default layout, which a payload does not say, so every
+ * set's sections are included — a superset, which a prefetch can afford.
+ */
+function layoutSectionsFor(content, page) {
+  const sets = content?.layouts && typeof content.layouts === 'object' ? content.layouts : {}
+  const name = typeof page?.layout?.name === 'string' && page.layout.name ? page.layout.name : null
+  const named = name ? findLayoutEntry(sets, name) : undefined
+  const chosen = name ? (named ? [named] : []) : Object.values(sets)
+  const out = []
+  const walk = (sections) => {
+    for (const s of sections || []) {
+      if (!s || typeof s !== 'object') continue
+      out.push(s)
+      walk(s.subsections)
+    }
+  }
+  for (const set of chosen) for (const area of Object.values(set || {})) walk(area?.sections)
+  return out
+}
+
 /**
  * Every fetch config a page will need at render time, resolved once and de-duplicated by
- * cache key: the site-level fetch, the page's, its parent's, and each section's own
- * (including nested sections), each through `resolveFetchConfigs` — the same resolver the
- * entity store uses, so a host prefetches exactly what the render will ask for.
+ * cache key: the page's, its parent's, each section's own (including nested sections),
+ * its layout sections', and the site's where it reaches (`siteReaches`) — each through
+ * `resolveFetchConfigs`, the same resolver the entity store uses, so a host prefetches
+ * exactly what the render will ask for.
  *
  * @returns {Object[]} resolved fetch configs
  */
@@ -113,11 +137,22 @@ export function resolvePageFetchConfigs(content, route, { locale = null } = {})
     variables: binding?.variables ?? null,
   }
   const siteFetch = content?.config?.fetch ?? null
-  // The route query: the key this page's URL names one record of, by the rule the
-  // entity store reads it with (`routeQuery`) — never a payload field.
-  const routeKey = binding
-    ? routeQuery({ page: page.fetch, parent: parent?.fetch, site: siteFetch, sections: sectionFetches(page.sections) })?.key ?? null
+  // The route query: the key this page's URL names one record of, chosen at the page
+  // that captured its variable — by the rule the entity store reads it with
+  // (`pageRouteQuery`) — never a payload field.
+  const chosen = binding
+    ? pageRouteQuery(page, {
+        routeOf: (p) => p.route,
+        parentOf: (p) => parentPageOf(p, pages),
+        fetchOf: (p) => p.fetch ?? null,
+        sectionsOf: (p) => p.sections,
+        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
 
   const out = new Map()
   const put = (cfg) => {
@@ -126,28 +161,47 @@ export function resolvePageFetchConfigs(content, route, { locale = null } = {})
   }
   const add = (sources) => {
     for (const cfg of resolveFetchConfigs(sources, options).values()) {
-      put(cfg)
+      const current = routeKey && cfg.as === routeKey ? currentOf(cfg) : null
+      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
+        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.
-      if (routeKey && cfg.as === routeKey && cfg.detail && binding.paramValue !== undefined) {
+      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))
     }
   }
-  // The cascade a block sees: its own fetch (unless a refinement), page, parent, site.
-  add([page.fetch ?? null, parent?.fetch ?? null, siteFetch])
+  // The cascade a block sees: its own fetch, page, parent, a nested page's route
+  // binding, and the site's — which reaches a top-level page's sections only.
+  const siteForPage = siteReaches(parent) ? siteFetch : null
+  add([page.fetch ?? null, parent?.fetch ?? null, routeSource, siteForPage])
   const walk = (sections) => {
     for (const s of sections || []) {
-      if (s?.fetch && !isRefinement(s.fetch)) add([s.fetch, page.fetch ?? null, parent?.fetch ?? null, siteFetch])
+      if (s?.fetch) add([s.fetch, page.fetch ?? null, parent?.fetch ?? null, routeSource, siteForPage])
       if (s?.subsections) walk(s.subsections)
     }
   }
   walk(page.sections)
+  // ⭐ Layout sections belong to the site: the site's binding reaches them on every
+  // page, beside each one's own fetch. A layout area has no parent page.
+  for (const s of layoutSectionsFor(content, page)) add([s.fetch ?? null, siteFetch])
   return [...out.values()]
 }