@uniweb/core 0.37.1 → 0.38.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/core",
-  "version": "0.37.1",
+  "version": "0.38.0",
   "description": "Core classes for the Uniweb platform - Uniweb, Website, Page, Block",
   "type": "module",
   "exports": {
@@ -49,8 +49,8 @@
     "vitest": "^4.1.7"
   },
   "dependencies": {
-    "@uniweb/theming": "^0.2.0",
-    "@uniweb/semantic-parser": "^1.5.1"
+    "@uniweb/semantic-parser": "^1.5.1",
+    "@uniweb/theming": "^0.2.0"
   },
   "scripts": {
     "test": "vitest run"

package/src/data-keys.js

@@ -24,49 +24,55 @@
 
 import { fetchEntries } from './fetch-config.js'
 
-/** The suffix that asks for whole records: `'@std/article/*'`. */
-export const WHOLE_SUFFIX = '/*'
-
 /**
- * A declared key's schema ref, and whether its component expects WHOLE records — as `data:`
- * spells it: a ref string (`'@std/article'`), an entry naming one (`{ schema: '@/member' }`),
- * or neither for an inline shape — a field map or a form — which names no schema.
- *
- * ⭐ `/*` after the ref asks for whole records (`'@std/article/*'`) — the record as stored, one
- * key per section — where a bare ref asks for briefs, the brief's fields at the top (ruled
- * 2026-09-27 [Diego]). The runtime asks each key's question accordingly; a key declared whole
- * that its fetch cannot fill whole is `null`.
- *
- * Who passes what. The runtime: a section type's LEAN `data` — a ref string or null, from the
- * runtime schema the build extracts (`@uniweb/build`'s `runtime-schema.js`) — and the foundation's
- * own `main.js` `data:` as written. A build-time reader: a `meta.js` value as written, or a
- * registered foundation schema's in its normalized form (`schemaFormat: 3`, `@uniweb/schemas`'s
- * `normalizeFoundationSchema`), which writes every ref as `{ kind: 'schema', schema, whole }` — the
- * ref qualified and `whole` said outright.
+ * A declared key's schema ref, and its two flags — as `data:` spells them: a ref string
+ * (`'@std/article'`), the long form (`{ schema: '@std/article', single: true, whole: true }`), or
+ * neither for an inline shape — a field map or a form — which names no schema.
+ *
+ * ⭐ TWO FLAGS, INDEPENDENT (ruled 2026-10-07 [Diego]):
+ *
+ *   - **`single`** — how many: one record, or `null`, where a key holds a list by default. The
+ *     runtime asks for the first record the binding selects (`./page-data.js`) and delivers it.
+ *   - **`whole`** — how much of each: the record as stored, one key per section, where a key holds
+ *     briefs by default, the brief's fields at the top (ruled 2026-09-27). The runtime asks each
+ *     key's question accordingly; a key declared whole that its fetch cannot fill whole is `null`.
+ *
+ * ⛔ `'@std/article/*'` asked for whole records until 2026-10-07, and is retired: the build and
+ * `register` refuse it, so no artifact carries it, and it is not read here.
+ *
+ * Who passes what. The runtime: a section type's LEAN `data` — a ref string, `{ schema, single?,
+ * whole? }` or null, from the runtime schema the build extracts (`@uniweb/build`'s
+ * `runtime-schema.js`) — and the foundation's `main.js` `data:` leaned the same way. A build-time
+ * reader: a `meta.js` value as written, or a registered foundation schema's in its normalized form
+ * (`schemaFormat: 3`, `@uniweb/schemas`'s `normalizeFoundationSchema`), which writes every ref as
+ * `{ kind: 'schema', schema, single, whole }` — the ref qualified and both flags said outright.
  *
  * @param {*} value - one `data:` entry's value, authored, leaned or normalized
- * @returns {{ ref: string|null, whole: boolean }}
+ * @returns {{ ref: string|null, single: boolean, whole: boolean }}
  */
 export function dataRefOf(value) {
-  const raw = typeof value === 'string'
-    ? value
-    : (value && typeof value === 'object' && typeof value.schema === 'string' ? value.schema : '')
-  if (!raw) return { ref: null, whole: false }
-  if (raw.endsWith(WHOLE_SUFFIX)) return { ref: raw.slice(0, -WHOLE_SUFFIX.length) || null, whole: true }
-  return { ref: raw, whole: typeof value === 'object' && value.whole === true }
+  if (typeof value === 'string') return { ref: value || null, single: false, whole: false }
+  // The long form's `schema` is a ref; an inline field map may have a field called `schema`.
+  if (value && typeof value === 'object' && typeof value.schema === 'string' && value.schema.startsWith('@')) {
+    return { ref: value.schema, single: value.single === true, whole: value.whole === true }
+  }
+  return { ref: null, single: false, whole: false }
 }
 
 /**
- * The keys a section's component receives, in order, each with its schema ref and whether
- * it expects whole records (`dataRefOf`) — its component's `data:` first, then its
- * foundation's. A key both declare is the component's.
+ * The keys a section's component receives, in order, each with its schema ref and its two flags
+ * (`dataRefOf`) — its component's `data:` first, then its foundation's. A key both declare is the
+ * component's.
+ *
+ * `data: false`, a missing `data:` or anything that is not a map declares nothing. Each value
+ * may be as authored, as the build leans it, or as a registered schema normalizes it.
  *
- * `data: false`, a missing `data:` or anything that is not a map declares nothing. Each
- * value may be as authored or as the build leans it (`{ key: ref|null }`).
+ * ⚠️ `single` is the FOURTH member, appended 2026-10-07, so a caller destructuring the first three
+ * reads what it always did.
  *
  * @param {Object|false|null|undefined} componentData - the component's `data:`
  * @param {Object|false|null|undefined} [foundationData] - its foundation's `main.js` `data:`
- * @returns {Array<[string, string|null, boolean]>} `[key, ref, whole]`
+ * @returns {Array<[string, string|null, boolean, boolean]>} `[key, ref, whole, single]`
  */
 export function declaredKeys(componentData, foundationData = null) {
   const out = []
@@ -76,8 +82,8 @@ export function declaredKeys(componentData, foundationData = null) {
     for (const [key, value] of Object.entries(data)) {
       if (!key || seen.has(key)) continue
       seen.add(key)
-      const { ref, whole } = dataRefOf(value)
-      out.push([key, ref, whole])
+      const { ref, single, whole } = dataRefOf(value)
+      out.push([key, ref, whole, single])
     }
   }
   return out
@@ -137,7 +143,7 @@ function parseRef(ref) {
  * The mapping says where an answer lands; it renames no fetch. A fetch keeps its `as`
  * for its question, its cache key and its prefetch.
  *
- * @param {Array<[string, string|null, boolean]>} declared - `declaredKeys`
+ * @param {Array<[string, string|null, boolean, boolean]>} declared - `declaredKeys`
  * @param {Array<*>} levels - each level's `fetch`, most specific first; falsy levels skipped
  * @param {Object} [options]
  * @param {Object|null} [options.queries] - the site's `config.queries`, for each fetch's

package/src/index.js

@@ -24,7 +24,7 @@ export { substitutePlaceholders } from './substitute-placeholders.js'
 // reads them and a consumer that needs them imports `@uniweb/core/records-service`.
 export { resolveFetchConfigs, routeQuery, pageRouteQuery, routeSelection, sectionFetches, siteReaches, withoutRouteVariables, CURRENT_MODES, currentFor } from './fetch-config.js'
 export { buildDetailConfig, ROUTE_HANDLE_KEY } from './detail-url.js'
-export { declaredKeys, sameSchema, fillDeclaredKeys, dataRefOf, WHOLE_SUFFIX } from './data-keys.js'
+export { declaredKeys, sameSchema, fillDeclaredKeys, dataRefOf } from './data-keys.js'
 // ⭐ What a page needs — the one rule. `fetchLevels` is the part every lane has an answer for
 // (which fetches reach a block); the drivers and the per-key program are `@uniweb/core/page-data`.
 export { fetchLevels } from './page-data.js'

package/src/page-data.js

@@ -80,13 +80,14 @@ export function fetchLevels({ own = null, page = null, parent = null, route = nu
  * Each filling fetch is resolved on its own, so two fetches of one `as` can fill two keys.
  *
  * @param {Object} input
- * @param {Array<[string, string|null, boolean]>} input.declared - `declaredKeys(meta)`
+ * @param {Array<[string, string|null, boolean, boolean]>} input.declared - `declaredKeys(meta)`
  * @param {Array<*>} input.levels - `fetchLevels`
  * @param {Object} [input.holds] - what the block already holds, by key
  * @param {Object|null} [input.queries] - the site's `config.queries`
  * @param {Object} [input.options] - what each fetch is resolved with (`resolveFetchConfigs`)
- * @returns {Map<string, { cfg: Object, held: *, whole: boolean }>} declared key → its filling config,
- *   and whether its component expects whole records, in the order `declared` lists the keys
+ * @returns {Map<string, { cfg: Object, held: *, whole: boolean, single: boolean }>} declared key → its
+ *   filling config, and its two flags — whether its component expects whole records, and one record —
+ *   in the order `declared` lists the keys
  */
 export function blockFills({ declared, levels, holds = {}, queries = null, options = {} }) {
   const out = new Map()
@@ -102,12 +103,12 @@ export function blockFills({ declared, levels, holds = {}, queries = null, optio
     if (!firstOfKey.has(fetch.as)) firstOfKey.set(fetch.as, `${at}:${index}`)
   }))
 
-  const wholeKeys = new Set(declared.filter(([, , whole]) => whole).map(([key]) => key))
+  const flags = new Map(declared.map(([key, , whole, single]) => [key, { whole: whole === true, single: single === true }]))
   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, whole: wholeKeys.has(key) })
+    out.set(key, { cfg, held, ...flags.get(key) })
   }
   return out
 }
@@ -159,13 +160,19 @@ function heldWhole(peekRecord, match) {
  * reading the cache never does, because the cache holds answers only.
  *
  * ⭐ **What is asked follows what the component expects** (`whole`, from its `data:` —
- * `'@std/article/*'`; ruled 2026-09-27 [Diego]). Briefs by default: the records service's question
- * as it is, a compiled file's list, and on a parametric page the record FOUND in its query's set.
- * Whole records when declared: the question carries `whole: true`, and a list off the service is
+ * `{ schema, whole: true }`; ruled 2026-09-27 [Diego]). Briefs by default: the records service's
+ * question as it is, a compiled file's list, and on a parametric page the record FOUND in its query's
+ * set. Whole records when declared: the question carries `whole: true`, and a list off the service is
  * followed by each record's own request. A key declared whole that cannot be filled whole — its
  * source has no request for one record — is `null`: the contract cannot be met. An external query's
  * records have no data schema and so no brief: what its source answers is each record whole.
  *
+ * ⭐ **And how many** (`single`, ruled 2026-10-07 [Diego]): a key that holds one record asks for one —
+ * the binding's question cut to its first record (`narrow.limit: 1`), so a whole one is fetched whole
+ * alone, never each record of the set. The answer is still a list, of one or none, which the runtime
+ * makes the record or `null` (`runtime/src/prepare-props.js`). A parametric page's record is found in
+ * the query's whole set as before: `current: only` asks for one already.
+ *
  * ⛔ **A failed request delivers NOTHING under its key, and says so.** The key is absent from the
  * returned value and the message rides on `error`, because `[]` is a value: a request that failed
  * must not be indistinguishable from a query with no records. ⛔ Until 2026-09-27 a parametric
@@ -188,9 +195,10 @@ function heldWhole(peekRecord, match) {
  *   and a record found there answers with the brief it holds. No value at all means *unknown*,
  *   which is not the same as `[]`, *not in the set*.
  * @param {boolean} [where.whole] - the component expects whole records
+ * @param {boolean} [where.single] - the component expects one record
  * @returns {Generator<Object|Object[], { value?: *, error?: string, errorConfig?: Object }>}
  */
-export function* keyProgram(cfg, { dynamicContext = null, route = null, held = undefined, peekRecord = null, current: forced = null, opportunistic = false, whole = false } = {}) {
+export function* keyProgram(cfg, { dynamicContext = null, route = null, held = undefined, peekRecord = null, current: forced = null, opportunistic = false, whole = false, single = false } = {}) {
   /** A step this caller can do without: a miss answers `{ missing: true }` instead of stopping. */
   const maybe = (request) => (opportunistic ? { request, optional: true } : request)
   // The block holds this fetch's answer already — a static build prerendered it.
@@ -207,14 +215,19 @@ export function* keyProgram(cfg, { dynamicContext = null, route = null, held = u
   // How this fetch uses the page's record: by the query it names (`currentFor`).
   const current = forced ?? (dynamicContext ? currentFor(cfg, route) : null)
 
+  // What a list of the binding's records is asked as — its first only, for a key holding one — and
+  // the answer cut to it here too, since a source need not honour `narrow` (a foundation's transport).
+  const listed = single ? firstOnly(cfg) : cfg
+  const cut = (data) => (single && Array.isArray(data) ? data.slice(0, 1) : data)
+
   if (current === 'exclude') {
     // The query's records without this page's, its `limit` counting the others.
-    const view = othersView(cfg)
+    const view = othersView(listed)
     const asked = whole && cfg.ask ? { ...view, whole: true } : view
     const answer = yield asked
     if (answer.error) return { error: answer.error, errorConfig: asked }
     if (answer.data === undefined || answer.data === null) return {}
-    const others = othersOf(answer.data, cfg, isPageRecord(dynamicContext, cfg.routeField))
+    const others = othersOf(answer.data, listed, isPageRecord(dynamicContext, cfg.routeField))
     if (!whole || cfg.ask) return { value: others }
     return yield* wholeRecordsOf(cfg, others)
   }
@@ -273,12 +286,21 @@ export function* keyProgram(cfg, { dynamicContext = null, route = null, held = u
 
   // A fetch the page's record plays no part in, and `current: include`: the records as the fetch
   // describes them, the page's among the rest.
-  const asked = whole && cfg.ask ? { ...cfg, whole: true } : cfg
+  const asked = whole && cfg.ask ? { ...listed, whole: true } : listed
   const answer = yield asked
   if (answer.error) return { error: answer.error, errorConfig: asked }
   if (answer.data === undefined || answer.data === null) return {}
-  if (!whole || cfg.ask) return { value: answer.data }
-  return yield* wholeRecordsOf(cfg, answer.data)
+  if (!whole || cfg.ask) return { value: cut(answer.data) }
+  return yield* wholeRecordsOf(cfg, cut(answer.data))
+}
+
+/**
+ * A `single` key's question: the binding's own, cut to its first record. The fetch's `narrow` is
+ * where a cut belongs — applied after the query's set on every lane — and a `limit` of its own is at
+ * least one, so the first record is the same either way.
+ */
+function firstOnly(cfg) {
+  return { ...cfg, narrow: { ...(cfg.narrow || {}), limit: 1 } }
 }
 
 /**
@@ -340,14 +362,14 @@ function asSteps(value) {
 /**
  * Every filling key's program, ready to run.
  *
- * @param {Map<string, { cfg: Object, held: *, whole?: boolean }>} fills - `blockFills`
+ * @param {Map<string, { cfg: Object, held: *, whole?: boolean, single?: boolean }>} fills - `blockFills`
  * @param {Object} where - passed to each `keyProgram`
  * @returns {Map<string, Generator>}
  */
 export function planFor(fills, where = {}) {
   const plan = new Map()
-  for (const [key, { cfg, held, whole = false }] of fills) {
-    plan.set(key, keyProgram(cfg, { ...where, held, whole }))
+  for (const [key, { cfg, held, whole = false, single = false }] of fills) {
+    plan.set(key, keyProgram(cfg, { ...where, held, whole, single }))
   }
   return plan
 }

package/src/records-service.js

@@ -36,13 +36,16 @@
  *
  * ## ⛔ The HOST tier only — and the reason is mechanical, not a policy
  *
- * `resolveService` reads the site's authored tier first and the host's second.
- * This does not, because it cannot: its caller `resolveFetchConfigs` is a leaf
- * that runs in an SSR isolate over a plain content object with no `Website` to
- * hand. It reads `config.services` directly, so the authored tier is not
- * available here. ⇒ **A site does not declare its own record provider**, which
- * is also the standing ruling — a third-party source is a foundation transport,
- * not site-level config *(2026-09-04, the retired `fetcher:` vocabulary)*.
+ * `resolveService` reads two tiers: the host's offer, then the site's authored
+ * declaration for what the host does not offer. *(This said "the site's authored
+ * tier first" until 2026-10-06; the host's offer has come first since 2026-09-10.)*
+ * This reads the host's alone, because it cannot read the other: its caller
+ * `resolveFetchConfigs` is a leaf that runs in an SSR isolate over a plain
+ * content object with no `Website` to hand. It reads `config.services` directly,
+ * so the authored tier is not available here. ⇒ **A site does not declare its
+ * own record provider**, which is also the standing ruling — a third-party
+ * source is a foundation transport, not site-level config *(2026-09-04, the
+ * retired `fetcher:` vocabulary)*.
  *
  * ## ⛔ A pattern, not a base — and the reason is a deleted function
  *

package/src/services.js

@@ -16,10 +16,11 @@ import { applyBasePath } from './base-path.js'
  *      deployment offers, which the site never had to know about. When a host
  *      offers a service, that is the answer: it is the authority on what a
  *      hosted site is given.
- *   2. **The site**, authored — `search:`, `submit:`, `assistant:`, `tracking:`
- *      in site.yml. The operator's own declaration — used for anything the host
- *      does not provide, and on a static site, where no host speaks, the whole
- *      answer.
+ *   2. **The site**, authored — its entry under `services:` in site.yml, which a
+ *      built site carries as `config.<name>`. The operator's own declaration —
+ *      used for anything the host does not provide, and on a static site, where
+ *      no host speaks, the whole answer. *(This named the top-level `search:`,
+ *      `submit:`, `assistant:` and `tracking:` keys, retired 2026-10-06.)*
  *
  * ## ⛔ THE TWO TIERS ARE NOT TWO SOURCES OF ONE KIND OF THING
  *

package/src/website.js

@@ -1158,7 +1158,7 @@ export default class Website {
    * The registry is open: any name resolves, whether or not the framework ships
    * a client for it.
    *
-   * @param {string} name - the service name — `search`, `submit`, `api`, …
+   * @param {string} name - the service name — `search`, `submit`, `backend`, …
    * @returns {boolean}
    */
   isServiceEnabled(name) {