@uniweb/core 0.26.2 → 0.28.0

package/src/fetch-config.js

@@ -24,6 +24,7 @@
  * rather than counted:**
  *
  *     fetch-config → data-paths                                    (leaf)
+ *                  → route-match                                   (leaf)
  *                  → records-service → substitute-placeholders     (leaf)
  *                                    → services → base-path        (leaf)
  *
@@ -51,15 +52,32 @@
 
 import { queryDataUrl, isDataUrl, recordDataUrl } from './data-paths.js'
 import { resolveRecordsService } from './records-service.js'
+// A leaf that imports nothing — `recordRouteBase` is the one rule for which page
+// addresses a record, and a route query is chosen at exactly that page.
+import { recordRouteBase } from './route-match.js'
 
 /**
- * Is this fetch declaration a per-instance *refinement* of an ancestor's
- * config rather than a new source of its own?
+ * ⭐ HOW A SECTION ON A PARAMETRIC PAGE USES THE PAGE'S RECORD — `current:` on its
+ * binding under the page's route key, ruled 2026-09-13 [Diego]:
  *
- * The spelling is `refine: true`. Its earlier alias, `inherit: true`, was
- * accepted with a warning from April 2026 and removed on 2026-09-02: the build
- * refuses it with an error, and `EntityStore` refuses it in dev. This predicate
- * stays silent so it is safe in any environment.
+ *   - `only` — the record, as a list of one. The default: every section gets it;
+ *   - `exclude` — the route query's records without it: "related", "more articles";
+ *   - `include` — all of them, the record among them: a previous / next pager.
+ *
+ * ⛔ It replaces `refine: true` and `detail: false`, a flag three methods consulted
+ * separately, which delivered `exclude` and nothing else, and whose `sort` and
+ * `where` changed nothing (measured 2026-09-13). The build refuses both.
+ */
+export const CURRENT_MODES = Object.freeze(['only', 'exclude', 'include'])
+
+/**
+ * Does a declaration still say `refine: true`?
+ *
+ * ⛔ `refine` is RETIRED (2026-09-13, for `current:` above): the build refuses it and
+ * nothing in the framework calls this. ⚠️ It stays exported because a consumer that
+ * bundles this clone read it through `./fetch-config` (pinned by
+ * `tests/fetch-config-live-contract.test.js`, 2026-09-02) — removing a name a reader
+ * imports breaks them at the commit, so it goes when that reader says it has.
  *
  * @param {Object} cfg - a fetch declaration
  * @returns {boolean}
@@ -68,6 +86,41 @@ export function isFetchRefinement(cfg) {
   return cfg?.refine === true
 }
 
+/** A resolved config's `current:` — `only` when it says nothing, or something else. */
+export function currentOf(cfg) {
+  return CURRENT_MODES.includes(cfg?.current) ? cfg.current : 'only'
+}
+
+/**
+ * The list a `current: exclude` section asks for: its own view, one record longer,
+ * so that removing the page's record still leaves `limit` others. The order is
+ * narrow, sort, remove the record, limit — a `limit` counts the others.
+ *
+ * @param {Object} cfg - a resolved config under the route key
+ * @returns {Object}
+ */
+export function othersView(cfg) {
+  if (!cfg || typeof cfg.limit !== 'number' || cfg.limit <= 0) return cfg
+  return { ...cfg, limit: cfg.limit + 1 }
+}
+
+/**
+ * The records a `current: exclude` section receives, from what `othersView` asked:
+ * the list without the page's record — the first that matches the route's value, the
+ * one `only` delivers — cut to the binding's `limit`.
+ *
+ * @param {Array|*} records - what `othersView(cfg)` answered
+ * @param {Object} cfg - the section's resolved config
+ * @param {(record: Object) => boolean} isCurrent - matches the page's record
+ * @returns {Array|*}
+ */
+export function othersOf(records, cfg, isCurrent) {
+  if (!Array.isArray(records)) return records
+  const at = records.findIndex(isCurrent)
+  const others = at < 0 ? records : [...records.slice(0, at), ...records.slice(at + 1)]
+  return typeof cfg?.limit === 'number' && cfg.limit > 0 ? others.slice(0, cfg.limit) : others
+}
+
 /**
  * Localize a fetch config that reads a local data path.
  *
@@ -89,31 +142,23 @@ function localizeConfig(cfg, locale, defaultLocale) {
 }
 
 /**
- * Auto-inject `detail:` on a query ref whose query declares
- * `deferred:` fields.
- *
- * A deferred query ships a lean list payload, so the full record has to
- * come from somewhere else. Two patterns, picked by what the query
- * declares:
- *
- *   - the query has `detailUrl:` → use it verbatim (a remote source);
- *   - otherwise → `/data/<schema>/{slug}.json`, the per-record file emitted
- *     alongside the lean list.
- *
- * Conventions carried from the original implementation:
- *   - Per-record sources are keyed by `item.slug`, and the injected pattern
- *     uses the `{slug}` placeholder. Substitution works when the dynamic
- *     route's paramName is `slug` (the documented convention); a route using
- *     another param name needs an explicit author-written `detail:`.
- *   - Per-record files are not currently localized. A site needing localized
- *     a deferred query writes its own `detail:` URL.
- *
- * An author-supplied `cfg.detail` always wins; this only fills the default.
- * With no `queries` map available the config passes through untouched —
- * deferred-detail injection is an enhancement, never a correctness
- * requirement, so a caller that does not have query metadata still gets
- * a usable config. That matters for hosts whose content projection may not
- * carry query metadata at all.
+ * Say whether a resolved config has a PER-RECORD source — `detail` — so a
+ * parametric page asks for its record on its own rather than finding it in the list.
+ *
+ *   - the records service → `true`: the record is the list's own question narrowed
+ *     by the URL's value (`buildDetailConfig`);
+ *   - an external query declaring `record:` → `true`: its own request;
+ *   - a query declaring `deferred:` → `/data/<query>/{slug}.json`, the per-record
+ *     file the build emits beside the lean list. Per-record files are keyed by the
+ *     record's slug, and are not localized.
+ *
+ * ⛔ `detail:` is no longer AUTHORED (retired 2026-09-13 [Diego]; the build refuses
+ * it): its `rest`, `query`, pattern and `{ body, envelope }` forms are an external
+ * query's `record:` now, and `detailUrl:` went the same way. The field survives only
+ * as this resolved flag.
+ *
+ * With no `queries` map available the config passes through untouched — a caller
+ * that has no query metadata still gets a usable config.
  *
  * @param {Object} cfg
  * @param {Object|null} queries - the site's `config.queries` map
@@ -125,6 +170,8 @@ function applyDeferredDetail(cfg, queries) {
   // The records service answers a RECORD by the same question narrowed to it,
   // so every asked config has a detail source; `buildDetailConfig` composes it.
   if (cfg.ask) return { ...cfg, detail: true }
+  // An external query's `record:` request.
+  if (cfg.record && typeof cfg.record === 'object') return { ...cfg, detail: true }
 
 
   // ⛔ **`config.queries` is keyed by QUERY NAME, so look it up by the query.**
@@ -146,12 +193,27 @@ function applyDeferredDetail(cfg, queries) {
   if (!collConfig || typeof collConfig !== 'object') return cfg
   const deferred = Array.isArray(collConfig.deferred) ? collConfig.deferred : null
   if (!deferred || deferred.length === 0) return cfg
-  const pattern = typeof collConfig.detailUrl === 'string'
-    ? collConfig.detailUrl
-    : recordDataUrl(queryName, '{slug}')
-  return { ...cfg, detail: pattern }
+  return { ...cfg, detail: recordDataUrl(queryName, '{slug}') }
 }
 
+/**
+ * ⭐ AN EXTERNAL QUERY — a named query with `url:`, ruled 2026-09-13 [Diego]: *"Setting
+ * `url` would classify it as external."* A public, keyless endpoint, fetched from its
+ * own address by the visitor's browser or a host's prerender, and NEVER asked of the
+ * records service. It carries `method`, `body` and `transform`, and `record:` for one
+ * record on a parametric page. An API needing a key, headers or paging is a foundation
+ * transport, not this.
+ *
+ * @param {Object|null} decl - a query declaration
+ * @returns {boolean}
+ */
+export function isExternalQuery(decl) {
+  return Boolean(decl) && typeof decl === 'object' && typeof decl.url === 'string' && decl.url.length > 0
+}
+
+/** Keys a binding may not carry, whatever a stale payload holds — the query supplies them. */
+const QUERY_SUPPLIED = ['scope', 'url', 'method', 'body', 'transform', 'record', 'detail', 'envelope']
+
 /**
  * Resolve a query reference to something the fetcher can call.
  *
@@ -190,6 +252,28 @@ function resolveQuerySource(cfg, services, { queries = null, locale = null, defa
     ? queries[cfg.query]
     : null
 
+  // ⛔ A BINDING ADAPTS ITS QUERY WITH `where`, `sort` AND `limit`, AND NOTHING ELSE —
+  // ruled 2026-09-13 [Diego]. Its own `scope` is not read (*"it belongs to the
+  // query"*; it REPLACED the query's until then), and neither is a source of its own —
+  // `url`, `method`, `body`, `transform`, a `detail` form — which an external query
+  // declares instead. The build refuses all of them on a binding; a payload that still
+  // carries one gets the query's. Dropped from a COPY on every branch below, so the
+  // config itself is read exactly as it was.
+
+  // ⭐ AN EXTERNAL QUERY answers from its own address, on every lane.
+  if (isExternalQuery(decl)) {
+    const { path, url, ...rest } = cfg
+    for (const key of QUERY_SUPPLIED) delete rest[key]
+    const out = { ...rest, url: decl.url }
+    if (typeof decl.method === 'string' && decl.method) out.method = decl.method
+    if (decl.body !== undefined && decl.body !== null) out.body = decl.body
+    if (typeof decl.transform === 'string' && decl.transform) out.transform = decl.transform
+    if (decl.record && typeof decl.record === 'object') out.record = decl.record
+    // a live endpoint is the browser's to fetch, unless the binding says otherwise
+    if (out.prerender === undefined) out.prerender = false
+    return narrowQuery(out, decl, decl.where)
+  }
+
   // ⭐ THE SERVICE FIRST. A host that answers questions gets the whole query —
   // `schema`, `scope`, `where`, `sort`, `limit`, `depth` — and composes no
   // per-query address at all (the records contract, §2). It needs the query's
@@ -202,6 +286,7 @@ function resolveQuerySource(cfg, services, { queries = null, locale = null, defa
     // Drop the transitional `path`: two addresses on one request is an
     // ambiguity the fetcher would have to break by accident of field order.
     const { path, url, ...rest } = cfg
+    for (const key of QUERY_SUPPLIED) delete rest[key]
     if (!schema) {
       // ⛔ LOUD, not a fallthrough. A payload that offers the service and carries no
       // Model ref for the query cannot ask, and reading the compiled file
@@ -210,33 +295,63 @@ function resolveQuerySource(cfg, services, { queries = null, locale = null, defa
       // request is made, and the block's `dataError` says exactly this.
       return { ...rest, ask, schema: null }
     }
-    const asked = { ...rest, ask, schema }
-    // A saved query's own narrowing applies unless the fetch overrides it.
-    if (asked.scope === undefined && typeof decl.scope === 'string') asked.scope = decl.scope
-    if (asked.where === undefined && decl.where && typeof decl.where === 'object') asked.where = decl.where
-    if (asked.sort === undefined && decl.sort !== undefined && decl.sort !== null) asked.sort = decl.sort
-    if (asked.limit === undefined && typeof decl.limit === 'number' && decl.limit > 0) asked.limit = decl.limit
-    return asked
+    return narrowQuery({ ...rest, ask, schema }, decl, decl.where)
   }
 
   // ⭐ THE COMPILED FILE. The build applied the named query's fixed `where` when it
   // wrote `/data/<query>.json`; what it could NOT apply is a clause bound to the
   // route (`where: { tag: :dir }`) — a file is written once and the route differs
-  // per page — and it never applies `scope`, fixed or routed. So those travel here
-  // and are bound per page, exactly as they are on the service
-  // (`bindRouteVariables`, below). A fetch's own `scope` / `where` win, as they do
-  // there. ⛔ Until 2026-09-11 nothing travelled: a named query's `scope: :dir` was
+  // per page — and it applies neither `scope` nor `limit`. So those travel here and
+  // are applied per page, exactly as the service applies them (`bindRouteVariables`,
+  // below). ⛔ Until 2026-09-11 nothing travelled: a named query's `scope: :dir` was
   // ignored on this lane and `where: { tag: :dir }` was applied at build to the
   // literal `':dir'`, compiling to no records (measured).
   const out = { ...cfg, path: queryDataUrl(cfg.query) }
-  if (decl) {
-    if (out.scope === undefined && typeof decl.scope === 'string') out.scope = decl.scope
-    if (out.where === undefined) {
-      const routed = routeVariableClauses(decl.where)
-      if (routed) out.where = routed
-    }
-  }
-  return out
+  for (const key of QUERY_SUPPLIED) delete out[key]
+  return decl ? narrowQuery(out, decl, routeVariableClauses(decl.where)) : out
+}
+
+/**
+ * ⭐ A BINDING NARROWS ITS QUERY, AND NEVER WIDENS IT — ruled 2026-09-13 [Diego]:
+ * *"binding can narrow its query and pick its own order and count, but it can never
+ * add records the query leaves out."* One composition, so the records service is
+ * asked exactly what the compiled file is evaluated with:
+ *
+ *   - `scope` — the query's; a binding has none;
+ *   - `where` — the query's and the binding's must BOTH hold, as `{ and: [ … ] }`;
+ *   - `sort`, `limit` — the binding's, else the query's. A binding's `limit` is not
+ *     bounded by the query's: a count is how many to show, never which records exist.
+ *
+ * ⛔ Until 2026-09-13 each field of a binding REPLACED the query's here, while the
+ * static build had already baked the query's `where`, `sort` and `limit` into the
+ * file — so a binding narrowed inside the query on a static site and replaced it on
+ * a hosted one (measured: `where: { published: true }` plus `{ tag: x }` delivered
+ * published records tagged x from the file and asked the service for `{ tag: x }`).
+ *
+ * @param {Object} out - the binding, addressed
+ * @param {Object} decl - the query's declaration
+ * @param {Object|null} queryWhere - the part of the query's `where` this lane still
+ *   applies: all of it on the service, the routed clauses on the compiled file
+ * @returns {Object}
+ */
+function narrowQuery(out, decl, queryWhere) {
+  const next = { ...out }
+  if (typeof decl.scope === 'string') next.scope = decl.scope
+  const where = bothHold(queryWhere, out.where)
+  if (where) next.where = where
+  else delete next.where
+  if (next.sort === undefined && decl.sort !== undefined && decl.sort !== null) next.sort = decl.sort
+  if (next.limit === undefined && typeof decl.limit === 'number' && decl.limit > 0) next.limit = decl.limit
+  return next
+}
+
+/** Two where-objects that must both hold — `{ and: [a, b] }`, or whichever one there is. */
+function bothHold(a, b) {
+  const some = (w) => Boolean(w) && typeof w === 'object' && !Array.isArray(w) && Object.keys(w).length > 0
+  if (some(a) && some(b)) return { and: [a, b] }
+  if (some(b)) return b
+  if (some(a)) return a
+  return null
 }
 
 /**
@@ -378,12 +493,26 @@ function bindRouteVariables(cfg, variables) {
     const bound = bindWhere(cfg.where, variables)
     if (bound !== cfg.where) {
       const { where, ...rest } = out
-      out = bound === null ? rest : { ...rest, where: bound }
+      out = bound === null ? rest : { ...rest, where: soleMember(bound) }
     }
   }
   return out
 }
 
+/**
+ * An `and` or `or` left holding ONE member once its unbound clauses dropped is that
+ * member. It is how a query whose `where` is all route clauses, joined with its
+ * binding's (`narrowQuery`), asks the list page the binding's `where` alone — the same
+ * question, and the same cache entry, as a binding of a query with no `where`.
+ */
+function soleMember(where) {
+  if (!where || typeof where !== 'object' || Array.isArray(where)) return where
+  const keys = Object.keys(where)
+  if (keys.length !== 1 || (keys[0] !== 'and' && keys[0] !== 'or')) return where
+  const members = where[keys[0]]
+  return Array.isArray(members) && members.length === 1 ? members[0] : where
+}
+
 /** Walk a where-object: bind `:var` VALUES, drop clauses whose variable is unbound. */
 function bindWhere(where, variables) {
   if (Array.isArray(where)) {
@@ -468,7 +597,7 @@ function routeVariableClauses(where) {
  * A named query's narrowing that is FIXED for every page — the top-level `where`
  * clauses that hold no route variable, and its `scope` unless that is routed. The
  * build applies the `where` part when it compiles `/data/<query>.json` (it leaves
- * `scope` to the runtime, so a page's own can replace it); the rest is exactly
+ * `scope` to the runtime, which applies it with the rest of the query); the rest is exactly
  * `routeVariableClauses`, which the runtime binds per page (`resolveQuerySource`
  * carries it there). A clause is split at the TOP level and never inside: an `or`
  * holding one variable goes to the runtime whole, because applying half of it at
@@ -492,6 +621,45 @@ export function withoutRouteVariables({ where = null, scope = null } = {}) {
   return { where: fixed, scope: fixedScope }
 }
 
+/**
+ * ⭐ THE RECORDS A ROUTE QUERY SELECTS, UNCUT — the list a parametric page finds its
+ * record in, and the list its detail pages are made from. A `limit` is how many a
+ * list shows, never which records have a page: a binding `limit: 3` on `/blog` leaves
+ * `/blog/d` a record (ruled 2026-09-13 [Diego]). `sort` stays, as the selection's order.
+ *
+ * ⛔ Until 2026-09-13 the compiled-file lane looked the record up in the LIMITED list,
+ * so `/blog/d` rendered "not found" wherever its route query had a `limit`, and the
+ * static build made no page for it. The records service never had this: its record
+ * question drops `limit` (`buildDetailConfig`).
+ *
+ * @param {Object} cfg - a resolved config
+ * @returns {Object} the config itself when it has no `limit`, else a copy without one
+ */
+export function routeSelection(cfg) {
+  if (!cfg || typeof cfg !== 'object' || cfg.limit === undefined) return cfg
+  const { limit, ...rest } = cfg
+  return rest
+}
+
+/**
+ * ⭐ DOES THE SITE'S BINDING REACH THIS PAGE'S SECTIONS? — ruled 2026-09-13 [Diego]:
+ * *"Site is basically a virtual root page"*, *"meant to reach the layout pseudo-pages
+ * and sections because they belong to the site. and it's meant to reach the root
+ * pages."* So it reaches what a page's binding would if the site were the parent of
+ * the pages directly under it: a page with no parent page — a top-level page, the
+ * homepage included — and a layout area, which has none either. ⛔ Until then it
+ * reached every section on every page.
+ *
+ * Nothing is restructured: every lane keeps the site's fetch as the last level of
+ * its walk, and passes it for these pages only.
+ *
+ * @param {Object|null|undefined} parent - the page's parent page (by `parentRouteOf`), or null
+ * @returns {boolean}
+ */
+export function siteReaches(parent) {
+  return !parent
+}
+
 /** A `fetch` as a list: one declaration, several, or none. */
 function fetchList(fetch) {
   if (!fetch) return []
@@ -554,7 +722,6 @@ export function sectionFetches(sections) {
 export function routeQuery({ page = null, parent = null, site = null, sections = [] } = {}) {
   for (const [level, fetch] of [['page', page], ['parent', parent], ['site', site]]) {
     for (const cfg of fetchList(fetch)) {
-      if (isFetchRefinement(cfg)) continue
       const key = bindingKey(cfg)
       if (key) return { key, config: cfg, level }
     }
@@ -562,7 +729,6 @@ export function routeQuery({ page = null, parent = null, site = null, sections =
   let found = null
   for (const fetch of sections || []) {
     for (const cfg of fetchList(fetch)) {
-      if (isFetchRefinement(cfg)) continue
       const key = bindingKey(cfg)
       if (!key) continue
       if (found && found.key !== key) return null // the sections disagree: no route query
@@ -572,6 +738,57 @@ export function routeQuery({ page = null, parent = null, site = null, sections =
   return found
 }
 
+/**
+ * ⭐ THE ROUTE QUERY OF ANY PAGE ON A PARAMETRIC ROUTE — a nested one included.
+ *
+ * A route variable is captured by exactly one page: the `[slug]` or `[...path]`
+ * folder's, whose route ends in it. A page nested inside that one —
+ * `pages/members/[slug]/cv/`, routed `/members/:slug/cv` — names the same record,
+ * so its route query is found by `routeQuery` AT THE CAPTURING PAGE: that page's own
+ * query, its parent's, the site's, or its sections' shared key. Ruled 2026-09-13
+ * [Diego]: *"a nested page shares the route query of the page that captured its
+ * variable"*. ⛔ Until then every lane looked one parent up from the nested page,
+ * found no query on the `[slug]` page, and `/members/alice/cv` had no record.
+ *
+ * A query the nested page declares under another key is its own data and changes
+ * nothing about what `:slug` names. The caller hands the route binding to the nested
+ * page's sections (`nested`), since the cascade reaches only one parent up.
+ *
+ * ⭐ THE SITE IS THE VIRTUAL ROOT PAGE (ruled 2026-09-13 [Diego]), so the site's
+ * binding is a route query only for a capturing page with no parent page — a
+ * top-level parametric page — the way a page's binding is its children's
+ * (`siteReaches`). ⛔ Until then it was every parametric page's last fallback.
+ *
+ * Shape-agnostic: the object graph and a content document hand in their own
+ * accessors, and every lane climbs by the one parent rule (`parentRouteOf`).
+ *
+ * @param {Object} page - the page, in the caller's shape
+ * @param {Object} access
+ * @param {(page: Object) => string} access.routeOf - its route PATTERN (a concrete page's template route)
+ * @param {(page: Object) => Object|null} access.parentOf - its parent page, or null
+ * @param {(page: Object) => Object|Object[]|null} access.fetchOf - its `fetch`
+ * @param {(page: Object) => Array<Object>|undefined} access.sectionsOf - its raw sections
+ * @param {Object|Object[]|null} [access.site] - the site's `fetch`
+ * @returns {{ key: string, config: Object, level: string, capturing: Object, nested: boolean } | null}
+ *   null off a parametric route, or when the capturing page has no route query
+ */
+export function pageRouteQuery(page, { routeOf, parentOf, fetchOf, sectionsOf, site = null }) {
+  let capturing = page
+  for (let depth = 0; capturing && recordRouteBase(routeOf(capturing)) === null; depth++) {
+    if (depth > 64) return null // a parent cycle in a malformed payload
+    capturing = parentOf(capturing)
+  }
+  if (!capturing) return null
+  const parent = parentOf(capturing)
+  const found = routeQuery({
+    page: fetchOf(capturing),
+    parent: parent ? fetchOf(parent) : null,
+    site: parent ? null : site,
+    sections: sectionFetches(sectionsOf(capturing)),
+  })
+  return found ? { ...found, capturing, nested: capturing !== page } : null
+}
+
 /**
  * Say what a resolved config will GET, so the record index can file it.
  *

package/src/fetcher-dispatcher.js

@@ -3,7 +3,7 @@
  *
  * Assembled by the Website from the primary foundation's named transports
  * plus any extensions'. Resolves which fetcher handles a given request by
- * name lookup — the site selects per-schema in `site.yml fetcher.transports`.
+ * name lookup — the site selects per binding key (`as`) in `site.yml fetcher.transports`.
  *
  * The dispatcher owns cache-key derivation, checks the DataStore, dedups
  * concurrent in-flight requests, and passes an AbortSignal through to the
@@ -148,8 +148,8 @@ export default class FetcherDispatcher {
    * Select the fetcher for a request.
    *
    *   1. Runtime `transport` override (editor preview) wins over everything.
-   *   2. Otherwise, look up the site's per-schema selection in
-   *      `ctx.website.config.fetcher.transports[schema]` → `.transports.default`.
+   *   2. Otherwise, look up the site's per-key selection in
+   *      `ctx.website.config.fetcher.transports[request.as]` → `.transports.default`.
    *      A named match is resolved against the registry of foundation /
    *      extension transports.
    *   3. If the site didn't pick a name (or picked one that's not in the

package/src/field-path.js

@@ -0,0 +1,31 @@
+/**
+ * Field paths — the ONE rule for which dotted keys the query language admits.
+ *
+ * A `where` key and a `sort` field name a field of the record, or a path into it:
+ * `tenure.start`, `education.degree`. Every `.` is a step. ⭐ Two shapes are outside
+ * the language on both lanes (the records service's rule, stated by backend on
+ * 2026-09-14): a path with an **empty step** (`a..b`, `.a`, `a.`), and a path whose first
+ * step starts with **`$`** (`$meta.x`). A single `$` field — `$name`, `$uuid` — is not a
+ * path and stays a field. A `where` key outside the language selects no records; a
+ * `sort` field outside it is refused where it is authored.
+ *
+ * Zero-dependency leaf: the where evaluator and the sort evaluator both read it.
+ */
+
+/**
+ * Why a field key is outside the language, or null when it is inside.
+ *
+ * @param {string} key
+ * @returns {string|null} the problem, as a sentence
+ */
+export function fieldPathProblem(key) {
+  if (typeof key !== 'string' || key.indexOf('.') === -1) return null
+  const steps = key.split('.')
+  if (steps.some((step) => step === '')) {
+    return `\`${key}\` has an empty step — a path is field names joined by single dots`
+  }
+  if (steps[0].startsWith('$')) {
+    return `\`${key}\` starts with \`$\` — a path starts at one of the record's own fields`
+  }
+  return null
+}

package/src/index.js

@@ -22,7 +22,7 @@ export { default as ObservableState } from './observable-state.js'
 export { substitutePlaceholders } from './substitute-placeholders.js'
 // `resolveRecordsService` / `RECORDS_SERVICE` are NOT re-exported here: `./fetch-config.js`
 // reads them and a consumer that needs them imports `@uniweb/core/records-service`.
-export { resolveFetchConfigs, routeQuery, sectionFetches, withoutRouteVariables } from './fetch-config.js'
+export { resolveFetchConfigs, routeQuery, pageRouteQuery, routeSelection, sectionFetches, siteReaches, withoutRouteVariables, CURRENT_MODES } from './fetch-config.js'
 export { buildDetailConfig, ROUTE_HANDLE_KEY } from './detail-url.js'
 // `isWildcardLanguages` is likewise internal — `./locale-config.js` reads it
 // and nothing else does. Same subpath escape hatch: `@uniweb/core/locale-config`.
@@ -50,7 +50,7 @@ export {
   queryNameFromUrl,
   isDataUrl
 } from './data-paths.js'
-export { evaluate as evaluateWhere, match as matchWhere } from './where.js'
+export { evaluate as evaluateWhere, match as matchWhere, whereOutsideLanguage } from './where.js'
 // A query's `scope:` over records that carry their placement — read by the runtime's
 // default fetcher and by `@uniweb/build` when it compiles a query's file.
 export { applyScope, withinScope } from './scope.js'

package/src/layout-name.js

@@ -0,0 +1,61 @@
+/**
+ * Layout names — the ONE rule for when two spellings name one layout.
+ *
+ * A layout is named in four places: a page's `layout:`, the foundation's
+ * `defaultLayout`, the foundation's layout components (`src/layouts/<Name>/`) and a
+ * site's `layout/<name>/` folder. ⭐ Two spellings name one layout when they match
+ * regardless of case, and with or without a trailing `Layout` — so `layout/docs/`,
+ * `layout: Docs` and a foundation's `DocsLayout` are one layout. Ruled 2026-09-13
+ * [Diego]: case — *"case-insensitive matching makes more sense"*; the suffix — *"We
+ * should not require the suffix."* ⛔ Until then a foundation layout named
+ * `DocsLayout` needed the folder `layout/DocsLayout/`, and `layout/docs/` matched
+ * nothing, silently.
+ *
+ * An exact key wins first, then one that differs in case, then one that differs by
+ * the suffix — so a map holding both `Docs` and `DocsLayout` still answers each name
+ * with its own entry.
+ *
+ * Zero-dependency leaf: the site's object graph, a host's prefetch and the build
+ * import it, and none of them should pull more of core to agree on a name.
+ */
+
+const LAYOUT_SUFFIX = /^(.+?)[-_]?layout$/
+
+/**
+ * The key a layout name is compared by: lowercased, a trailing `layout` (after an
+ * optional `-` or `_`) removed when something remains. `DocsLayout`, `docs-layout`
+ * and `Docs` → `docs`; `Layout` → `layout`.
+ *
+ * @param {*} name
+ * @returns {string|null} null for anything that is not a non-empty string
+ */
+export function layoutNameKey(name) {
+  if (typeof name !== 'string') return null
+  const lower = name.trim().toLowerCase()
+  if (!lower) return null
+  const match = lower.match(LAYOUT_SUFFIX)
+  return match ? match[1] : lower
+}
+
+/**
+ * The entry a layout name names in a map keyed by layout name — the site's layout
+ * sets, the foundation's layout components, or their meta.
+ *
+ * @param {Object|null|undefined} map
+ * @param {string|null|undefined} name
+ * @returns {*} the entry, or undefined
+ */
+export function findLayoutEntry(map, name) {
+  if (!map || typeof map !== 'object' || typeof name !== 'string' || !name) return undefined
+  if (Object.prototype.hasOwnProperty.call(map, name)) return map[name]
+  const keys = Object.keys(map)
+  const lower = name.toLowerCase()
+  for (const key of keys) {
+    if (key.toLowerCase() === lower) return map[key]
+  }
+  const wanted = layoutNameKey(name)
+  for (const key of keys) {
+    if (layoutNameKey(key) === wanted) return map[key]
+  }
+  return undefined
+}