@uniweb/runtime 0.16.0 → 0.17.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/runtime",
-  "version": "0.16.0",
+  "version": "0.17.1",
   "description": "Minimal runtime for loading Uniweb foundations",
   "type": "module",
   "exports": {
@@ -36,7 +36,7 @@
     "node": ">=20.19"
   },
   "dependencies": {
-    "@uniweb/core": "^0.21.0",
+    "@uniweb/core": "^0.23.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.38.0"
+    "@uniweb/build": "0.40.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/background-shared.js

@@ -0,0 +1,72 @@
+/**
+ * The two helpers the background renderers share — one home, because they are
+ * not rendering.
+ *
+ * ## Why this module exists
+ *
+ * Backgrounds are an L3 pair by design: `components/Background.jsx` renders
+ * with hooks and DOM, `ssr-renderer.js` renders with `React.createElement`
+ * only, and the runtime-layer rule (framework `CLAUDE.md` gotcha #2) says that
+ * pair is twinned on purpose. ⛔ **What it also says is that only the RENDERING
+ * is twinned — "pure data → L1, one home" — and two pure helpers had been
+ * dragged across the seam with it**: a base-path joiner and a colour-opacity
+ * converter, byte-identical in both files.
+ *
+ * ⚠️ **And the copies had already drifted from the rule they were copying.**
+ * The base-path joiner is `@uniweb/core`'s `applyBasePath`, whose own docblock
+ * says it moved down to core *"rather than grow a second copy (the failure
+ * `@uniweb/core/route-match` was created to end, after one matcher was
+ * implemented twice and the copies diverged)"*. Two copies grew anyway, in the
+ * runtime, and **both were missing its protocol-relative guard** — so an author
+ * writing `//cdn.example.com/hero.jpg` on a site with `base: /docs/` got
+ * `/docs//cdn.example.com/hero.jpg`. Measured 2026-09-06; the exact garbage
+ * `applyBasePath` documents itself as existing to prevent.
+ *
+ * ⇒ The lesson is narrower than "don't duplicate": **when a twinned pair needs a
+ * helper, the helper is the thing that must not be twinned.** A twin is a
+ * commitment to keep two renderers in step; every pure function pulled inside it
+ * silently joins that commitment.
+ */
+
+import { applyBasePath } from '@uniweb/core/base-path'
+
+/**
+ * A site-root-relative URL with the deployment base applied.
+ *
+ * The base comes off the active website rather than being passed in, because
+ * both callers render from the singleton and neither has it to hand. The join
+ * itself is core's — protocol-relative and absolute URLs pass through, and an
+ * already-based path is not based twice.
+ *
+ * @param {string} url
+ * @returns {string}
+ */
+export function siteUrl(url) {
+  return applyBasePath(url, globalThis.uniweb?.activeWebsite?.basePath || '')
+}
+
+/**
+ * A colour with an alpha applied, for an overlay drawn over a background.
+ *
+ * Hex and `rgb()` / `rgba()` are converted; anything else — a named colour, a
+ * `var(--token)`, `oklch(…)` — is returned unchanged, because a wrong guess
+ * here paints the wrong colour rather than failing.
+ *
+ * @param {string} color
+ * @param {number} opacity
+ * @returns {string}
+ */
+export function withOpacity(color, opacity) {
+  if (typeof color !== 'string' || !color) return color
+  if (color.startsWith('#')) {
+    const r = parseInt(color.slice(1, 3), 16)
+    const g = parseInt(color.slice(3, 5), 16)
+    const b = parseInt(color.slice(5, 7), 16)
+    return `rgba(${r}, ${g}, ${b}, ${opacity})`
+  }
+  if (color.startsWith('rgb')) {
+    const match = color.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)/)
+    if (match) return `rgba(${match[1]}, ${match[2]}, ${match[3]}, ${opacity})`
+  }
+  return color
+}

package/src/collect-records.js

@@ -0,0 +1,99 @@
+/**
+ * Every record a site's declared queries return — for a host building something
+ * over the whole corpus rather than rendering one page.
+ *
+ * ## Why this is framework's and not the caller's
+ *
+ * A host that indexes a site has to ask the same questions the site's pages ask.
+ * ⛔ **If it composes its own, the index and the page can disagree**, and the way
+ * they disagree is the worst one available: the index offers a result whose page
+ * then renders empty. That is the two-answers-to-one-question failure the GET
+ * lane was retired for, reintroduced one lane over.
+ *
+ * ⇒ So the composition is not duplicated here either. This walks the site's
+ * `config.queries`, hands each one to `resolveFetchConfigs` — **the same rule a
+ * page render uses**, applying each saved query's own `scope` / `where` / `sort`
+ * / `limit` — and asks through the same client. What differs from a page is two
+ * fields and nothing else: `depth: 'brief'` (an index wants what a list shows)
+ * and `exhaustive: true` (a corpus is not a page, so it follows `cursors` to the
+ * end; the records contract bounds a single answer at 100).
+ *
+ * ## What the caller supplies
+ *
+ * ⭐ **The transport, and nothing else.** A host outside a browser decides how a
+ * site-relative address is dispatched — through its own origin, a service
+ * binding, a forwarding table that turns `/_…` into an upstream — and hands that
+ * in as `fetch`. **Framework decides what to ask and how to read the answer;
+ * the host decides how the bytes travel.** That split is the whole of the
+ * boundary here.
+ *
+ * ⛔ **A site with no records service is not an error.** It has no live records,
+ * so this returns empty rather than throwing: a static site's corpus comes from
+ * its own compiled artifacts, which the caller already has.
+ */
+
+import { resolveFetchConfigs } from '@uniweb/core/fetch-config'
+import { resolveRecordsService } from '@uniweb/core/records-service'
+import { createDefaultFetcher } from './default-fetcher.js'
+
+/**
+ * Ask a site's records service for every record its declared queries return.
+ *
+ * @param {Object} content - the render payload (`config.services`, `config.queries`)
+ * @param {Object} options
+ * @param {string} options.locale - the locale to ask in; it is a route segment
+ *   of the service's address, so there is no asking without one
+ * @param {Function} options.fetch - the transport, `(url, init) => Response`
+ * @param {AbortSignal} [options.signal]
+ * @param {string[]} [options.only] - restrict to these query names
+ * @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,
+ *   truncated? }` — `truncated` meaning the loop hit its own bound, never that
+ *   the site has more.
+ */
+export async function collectSiteRecords(content, { locale, fetch, signal, only = null } = {}) {
+  const config = content?.config
+  const services = config?.services ?? null
+  const queries = config?.queries ?? null
+
+  // No service, no queries, or no locale to ask in ⇒ nothing to collect. Each is
+  // an ordinary state of a site, not a fault: the caller reads its own artifacts.
+  if (!queries || typeof queries !== 'object') return empty()
+  if (!resolveRecordsService(services, locale)) return empty()
+
+  const names = Object.keys(queries).filter((n) => (only ? only.includes(n) : true))
+  if (names.length === 0) return empty()
+
+  // One synthetic source per query — `as` is the query's own name, so the answer
+  // comes back under the name the caller asked by.
+  const configs = resolveFetchConfigs(
+    names.map((name) => ({ query: name, as: name })),
+    { services, queries, locale, defaultLocale: config?.defaultLanguage ?? locale },
+  )
+
+  const fetcher = createDefaultFetcher({ fetch, basePath: config?.base ?? '' })
+  const records = {}
+  const errors = {}
+  const meta = {}
+
+  await Promise.all([...configs].map(async ([name, cfg]) => {
+    // ⛔ Only a config the service answers. A query that resolved to a compiled
+    // `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
+    const result = await fetcher.resolve({ ...cfg, depth: 'brief', exhaustive: true }, { signal })
+    if (result?.error) {
+      errors[name] = result.error
+      return
+    }
+    records[name] = Array.isArray(result?.data) ? result.data : []
+    if (result?.meta) meta[name] = result.meta
+  }))
+
+  return { records, errors: Object.keys(errors).length ? errors : null, meta }
+}
+
+function empty() {
+  return { records: {}, errors: null, meta: {} }
+}

package/src/components/Background.jsx

@@ -8,6 +8,7 @@
  */
 
 import React from 'react'
+import { siteUrl, withOpacity } from '../background-shared.js'
 
 /**
  * Background modes
@@ -27,20 +28,6 @@ const OVERLAY_COLORS = {
   dark: 'rgba(0, 0, 0, 0.5)',
 }
 
-/**
- * Resolve a URL against the site's base path
- * Prepends basePath to absolute URLs (starting with /) so they work
- * under subdirectory deployments (e.g., /templates/international/)
- */
-function resolveUrl(url) {
-  if (!url || !url.startsWith('/')) return url
-  const basePath = globalThis.uniweb?.activeWebsite?.basePath || ''
-  if (!basePath) return url
-  // Avoid double-prepending
-  if (url.startsWith(basePath + '/') || url === basePath) return url
-  return basePath + url
-}
-
 /**
  * Render gradient overlay
  */
@@ -143,28 +130,6 @@ function GradientBackground({ gradient }) {
   return <div className="background-gradient" style={style} aria-hidden="true" />
 }
 
-/**
- * Convert hex color to rgba with opacity
- */
-function withOpacity(color, opacity) {
-  // Handle hex colors
-  if (color.startsWith('#')) {
-    const r = parseInt(color.slice(1, 3), 16)
-    const g = parseInt(color.slice(3, 5), 16)
-    const b = parseInt(color.slice(5, 7), 16)
-    return `rgba(${r}, ${g}, ${b}, ${opacity})`
-  }
-  // Handle rgb/rgba
-  if (color.startsWith('rgb')) {
-    const match = color.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)/)
-    if (match) {
-      return `rgba(${match[1]}, ${match[2]}, ${match[3]}, ${opacity})`
-    }
-  }
-  // Fallback - return as is
-  return color
-}
-
 /**
  * Image background
  */
@@ -181,7 +146,7 @@ function ImageBackground({ image }) {
   const style = {
     position: 'absolute',
     inset: 0,
-    backgroundImage: `url(${resolveUrl(src)})`,
+    backgroundImage: `url(${siteUrl(src)})`,
     backgroundPosition: position,
     backgroundSize: size,
     backgroundRepeat: 'no-repeat',
@@ -235,7 +200,7 @@ function VideoBackground({ video }) {
   // Build source list: explicit sources array, or infer from src
   const sourceList = (sources || inferSources(src)).map(s => ({
     ...s,
-    src: resolveUrl(s.src)
+    src: siteUrl(s.src)
   }))
 
   return (
@@ -246,7 +211,7 @@ function VideoBackground({ video }) {
       loop={loop}
       muted={muted}
       playsInline
-      poster={resolveUrl(poster)}
+      poster={siteUrl(poster)}
       aria-hidden="true"
     >
       {sourceList.map(({ src: sourceSrc, type }, index) => (

package/src/default-fetcher.js

@@ -11,21 +11,15 @@
  *
  *   - a compiled file — `path:` under the site's base (`/data/<query>.json`,
  *     a per-record file), or a plain JSON `url:` the author wrote;
- *   - the host's QUESTION DOOR — `door:`, one POST per tick carrying every
- *     question the page asked, answered per key (the records door's contract,
- *     as this client reads it).
+ *   - the host's RECORDS SERVICE — `ask:`, one POST per tick carrying every
+ *     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 by the source on the door. Nothing decides
+ * uses to materialize a file — and at the source when asked. Nothing decides
  * that per site: the LANE decides.
  *
- * ⛔ A third lane — the host's ADDRESS door, a GET per query with the query
- * evaluated locally over the whole set — was retired 2026-09-04 by ruling,
- * with no hosted site to protect: one host answering one query two ways, and a
- * precedence between the two, was where the failure lived. The stamp's `list`,
- * `record` and `envelope` keys are not read.
- *
  * ⛔ RETIRED 2026-09-04 [Diego]: `fetcher.baseUrl`, `headers`, `envelope`,
  * `supports`, `request.style` / `request.rename` and the `json-body`
  * request-style registry. *"3rd party endpoints must be supported at the
@@ -82,34 +76,34 @@ export function createDefaultFetcher({ basePath = '', dev = false, fetch: fetchI
   const pathPrefix = basePath && basePath !== '/' ? basePath.replace(/\/$/, '') : ''
 
 
-  // ⭐ THE QUESTION DOOR — a batch of the misses, one POST, merged per key.
+  // ⭐ THE RECORDS SERVICE — a batch of the misses, one POST, merged per key.
   //
   // The entity store dispatches every config a page needs in one synchronous
-  // loop before awaiting any of them, so a door request enqueued here and
-  // flushed on the next microtask carries every miss of that page in one body
-  // The batch response is never cached as
-  // one: each request gets its own answer, keyed by its own question.
-  const doorQueues = new Map()
-  const askDoor = (request, ctx) => {
-    // ⛔ A door question needs the query's Model ref. A payload that stamps the
-    // door and carries no `config.queries` entry for the query cannot ask; that
-    // is a producer defect and it is said here, per key, with no request made.
+  // loop before awaiting any of them, so a question enqueued here and flushed
+  // on the next microtask carries every miss of that page in one body. The
+  // batch response is never cached as one: each request gets its own answer,
+  // keyed by its own question.
+  const askQueues = new Map()
+  const askRecords = (request, ctx) => {
+    // ⛔ A question needs the query's Model ref. A payload that offers the
+    // service and carries no `config.queries` entry for the query cannot ask;
+    // that is a producer defect and it is said here, per key, with no request.
     if (typeof request.schema !== 'string' || !request.schema) {
       return Promise.resolve({
         data: null,
-        error: `the payload stamps a records door but carries no Model ref for query ` +
-          `"${request.query ?? request.as}" (config.queries) — the door cannot be asked`,
+        error: `the payload offers the records service but carries no Model ref for query ` +
+          `"${request.query ?? request.as}" (config.queries) — it cannot be asked`,
       })
     }
     return new Promise((resolve) => {
-      const url = resolveServiceUrl(request.door, pathPrefix)
-      let queue = doorQueues.get(url)
+      const url = resolveServiceUrl(request.ask, pathPrefix)
+      let queue = askQueues.get(url)
       if (!queue) {
         queue = []
-        doorQueues.set(url, queue)
+        askQueues.set(url, queue)
         queueMicrotask(() => {
-          doorQueues.delete(url)
-          flushDoor(url, queue, doFetch)
+          askQueues.delete(url)
+          flushAsked(url, queue, doFetch)
         })
       }
       queue.push({ request, ctx, resolve })
@@ -118,8 +112,8 @@ export function createDefaultFetcher({ basePath = '', dev = false, fetch: fetchI
 
   return {
     /**
-     * The cache identity is the request's ADDRESS — or, on a question door,
-     * the QUESTION (`deriveCacheKey` hashes every operator of an address-less
+     * The cache identity is the request's ADDRESS — or, when asked of the
+     * records service, the QUESTION (`deriveCacheKey` hashes every operator of an address-less
      * request). Operators evaluated here run over a shared cached value and
      * must NOT split the cache: two pages declaring different `where:` clauses
      * against the same path share one entry — the file is fetched once and
@@ -131,7 +125,7 @@ export function createDefaultFetcher({ basePath = '', dev = false, fetch: fetchI
 
     async resolve(request, ctx = {}) {
       if (!request) return { data: null }
-      if (request.door) return askDoor(request, ctx)
+      if (request.ask) return askRecords(request, ctx)
       const { path, url, transform, body: rawBody } = request
 
       // Normalize method. Only GET and POST are supported by the default
@@ -153,7 +147,7 @@ export function createDefaultFetcher({ basePath = '', dev = false, fetch: fetchI
         // A URL the author wrote, sent exactly as written.
         target = url
       } else {
-        return { data: [], error: 'No path, url or door specified' }
+        return { data: [], error: 'No path, url or ask specified' }
       }
 
       const init = { signal: ctx.signal, method }
@@ -238,7 +232,7 @@ export function createDefaultFetcher({ basePath = '', dev = false, fetch: fetchI
 
         // ⭐ Say what depth was delivered, so the record index can file it — what
         // the config asked for, echoed: a list at brief depth when the query has
-        // a per-record source, a record in full. (A door reports `depths` per
+        // a per-record source, a record in full. (The service reports `depths` per
         // key and overrides this with what it actually served.)
         const depth = request.depth === 'brief' || request.depth === 'full' ? request.depth : undefined
         return depth ? { data: data ?? [], meta: { depth } } : { data: data ?? [] }
@@ -253,16 +247,16 @@ export function createDefaultFetcher({ basePath = '', dev = false, fetch: fetchI
 }
 
 /**
- * One question of a door batch, in the door's own vocabulary
- * (the records door's contract, §2): `schema` required, `scope` a bare
- * path, `sort` one key spelled `date` / `-date`, `depth` brief or full. The
- * where-object crosses as authored except for the two spellings the language
- * settled differently from the evaluator's: `nin` is `not_in` there, and a
- * top-level `path: { under }` — the file lane's way of naming a folder branch —
- * is the door's `scope`. Anything the door does not accept (`like`, a dotted
- * path) is sent as written and refused there by name: loud, never approximated.
+ * 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`, `depth` brief or full. The where-object
+ * crosses as authored except for the two spellings the language settled
+ * differently from the evaluator's: `nin` is `not_in` there, and a top-level
+ * `path: { under }` — the file lane's way of naming a folder branch — is
+ * `scope`. Anything the service does not accept (`like`, a dotted path) is
+ * sent as written and refused there by name: loud, never approximated.
  */
-function doorQuestion(request) {
+function toQuestion(request) {
   const q = { schema: request.schema }
   let where = request.where && typeof request.where === 'object' ? request.where : null
   let scope = typeof request.scope === 'string' && request.scope ? request.scope : null
@@ -277,34 +271,61 @@ function doorQuestion(request) {
   if (sort) q.sort = sort
   if (typeof request.limit === 'number' && request.limit > 0) q.limit = request.limit
   if (request.depth === 'brief' || request.depth === 'full') q.depth = request.depth
+  // ⭐ `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
   return q
 }
 
-const DOOR_OPERATOR = { nin: 'not_in' }
+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[DOOR_OPERATOR[key] ?? key] = value && typeof value === 'object' ? renameOperators(value) : value
+    out[OPERATOR_ALIAS[key] ?? key] = value && typeof value === 'object' ? renameOperators(value) : value
   }
   return out
 }
 
 /**
- * Send one batch to a door and hand each question its own answer.
+ * Send one batch to the records service and hand each question its own answer.
  *
  * The response is `{ data, depths?, errors?, cursors?, limits? }` (contract §5):
  * `data` answers exactly the keys sent, `[]` when nothing matched; a key that
  * ERRORED is absent from `data` and present in `errors`; `depths` says what was
  * actually served, which the record index files rather than what was asked for.
  * A key missing from both is a protocol violation and is reported as an error,
- * never as silence. `cursors` (a next page per key) and `limits` (a `limit` the
- * door bounded) are received and IGNORED, by ruling: framework has no paging
- * concept and is not this door's only client, so whether either is consumed is
- * a product decision, not a client default.
+ * never as silence.
+ *
+ * ⭐ `cursors` AND `limits` ARE READ — 2026-09-06 [Diego], reversing the ruling
+ * that had them "received and IGNORED, because framework has no paging concept."
+ * ⛔ **That ruling described our client and was silently wrong about our USERS:**
+ * the service bounds every answer at 100 (the records contract §4.2/§5), and a
+ * `cursors` entry is how it says there is more. Discarding both meant a hosted
+ * list of 500 rendered 100 — no error, no warning, no way for an author to tell
+ * a bound from the end of the data. **The silent class, on a visitor's page.**
+ *
+ * Two behaviours, deliberately not one:
+ *
+ *   - **a page render REPORTS** — `meta.truncated` and `meta.bound` ride the
+ *     answer, and nothing pages automatically. Auto-paging here would put
+ *     unbounded round trips in front of paint for a section that may only show
+ *     ten rows.
+ *   - **an exhaustive caller PAGES** — `request.exhaustive` follows `cursors`
+ *     until the service stops issuing them. `collectSiteRecords` is the caller
+ *     that wants it (a corpus is not a page), and `maxPages` bounds the loop so
+ *     a service that always answers with a cursor cannot spin.
  */
-async function flushDoor(url, queue, doFetch) {
+
+/** Pages an exhaustive request will follow before giving up and reporting truncation. */
+const MAX_PAGES = 50
+async function flushAsked(url, queue, doFetch) {
+  // One shared page loop: the batch is sent, and any entry that asked to be
+  // exhaustive and came back with a cursor is re-sent alone until it is done.
+  const pending = new Map()
   const body = {}
   const keys = []
   for (const entry of queue) {
@@ -312,7 +333,7 @@ async function flushDoor(url, queue, doFetch) {
     let key = base
     for (let n = 2; key in body; n += 1) key = `${base}#${n}`
     keys.push(key)
-    body[key] = doorQuestion(entry.request)
+    body[key] = toQuestion(entry.request)
   }
   let parsed
   try {
@@ -347,6 +368,9 @@ async function flushDoor(url, queue, doFetch) {
   const data = parsed && typeof parsed.data === 'object' && parsed.data ? parsed.data : {}
   const errors = parsed && typeof parsed.errors === 'object' && parsed.errors ? parsed.errors : {}
   const depths = parsed && typeof parsed.depths === 'object' && parsed.depths ? parsed.depths : {}
+  // Both absent when empty, never `{}` (the records contract §5).
+  const cursors = parsed && typeof parsed.cursors === 'object' && parsed.cursors ? parsed.cursors : {}
+  const limits = parsed && typeof parsed.limits === 'object' && parsed.limits ? parsed.limits : {}
   queue.forEach((entry, i) => {
     const key = keys[i]
     if (key in errors) {
@@ -361,14 +385,62 @@ async function flushDoor(url, queue, doFetch) {
       return
     }
     if (!(key in data)) {
-      entry.resolve({ data: null, error: `the records door answered without the key "${key}"` })
+      entry.resolve({ data: null, error: `the records service answered without the key "${key}"` })
       return
     }
     const depth = depths[key] === 'brief' || depths[key] === 'full'
       ? depths[key]
       : (entry.request.depth === 'brief' || entry.request.depth === 'full' ? entry.request.depth : undefined)
-    entry.resolve(depth ? { data: data[key], meta: { depth } } : { data: data[key] })
+
+    const cursor = typeof cursors[key] === 'string' && cursors[key] ? cursors[key] : null
+    const bound = typeof limits[key] === 'number' ? limits[key] : undefined
+    const rows = Array.isArray(data[key]) ? data[key] : data[key]
+
+    // An exhaustive caller collects the page and asks for the next one.
+    if (cursor && entry.request.exhaustive && Array.isArray(rows)) {
+      const acc = entry.collected ? entry.collected.concat(rows) : rows.slice()
+      const page = (entry.page || 1) + 1
+      if (page <= MAX_PAGES) {
+        pending.set(entry, { cursor, collected: acc, page, depth, bound })
+        return
+      }
+      // The loop's own bound, not the service's: report rather than spin.
+      entry.resolve({ data: acc, meta: withMeta({ depth, bound, truncated: true, pages: MAX_PAGES }) })
+      return
+    }
+
+    const collected = entry.collected ? entry.collected.concat(Array.isArray(rows) ? rows : []) : rows
+    const meta = withMeta({
+      depth,
+      bound,
+      // ⭐ A cursor IS the truncation signal, and it is the only one for a query
+      // that declared no `limit`: `limits` is reported only when an author's own
+      // limit was clamped (the records contract §5).
+      truncated: cursor ? true : undefined,
+      pages: entry.page && entry.page > 1 ? entry.page : undefined,
+    })
+    entry.resolve(meta ? { data: collected, meta } : { data: collected })
   })
+
+  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.
+  await Promise.all([...pending].map(([entry, state]) => {
+    const next = {
+      ...entry,
+      request: { ...entry.request, cursor: state.cursor },
+      collected: state.collected,
+      page: state.page,
+    }
+    return flushAsked(url, [next], doFetch)
+  }))
+}
+
+/** Build a `meta` from the fields that are actually present, or `undefined`. */
+function withMeta(fields) {
+  const out = {}
+  for (const [k, v] of Object.entries(fields)) if (v !== undefined) out[k] = v
+  return Object.keys(out).length ? out : undefined
 }
 
 /**

package/src/isolate-api.js

@@ -28,8 +28,46 @@
  * "since" is the first PUBLISHED version (git tag) whose `@uniweb/runtime/ssr`
  * exported the name — measured with `git log --reverse -S<name> -- src/ssr.js` and
  * `git tag --contains`, 2026-09-04.
+ *
+ * ## ⭐ `UNRELEASED` — and why the mechanism needed it
+ *
+ * ⛔ **This file had no way to stamp an export that has not shipped, and the gap
+ * was invisible because it was written retrospectively** (2026-09-04, at 0.14.2,
+ * stamping names that had all already published). The first genuinely new export
+ * hit it immediately: the test demands every export be stamped, a stamp must be
+ * `<=` package.json's version, and the version an export will ship in **does not
+ * exist until the publish that creates it** — versions are derived from commits
+ * at publish time and never hand-edited.
+ *
+ * ⚠️ **The tempting fix is the dangerous one.** Stamping the current version
+ * (`0.16.0`) would satisfy every check and be **false**: backend reads
+ * `isolateApiFloor` from the channel index and refuses to serve a site below it,
+ * so a floor of 0.16.0 would promise an export that 0.16.0 does not contain —
+ * and a host at the floor is entitled to skip feature detection. That is a
+ * guarantee broken in the one direction the floor exists to prevent.
+ *
+ * ⇒ **`UNRELEASED` says the true thing: this export exists in the tree and in no
+ * published version.** It is stamped like any other name, so nothing rides out
+ * unnoticed, and it is EXCLUDED from the floor — which therefore never promises
+ * more than a published artifact delivers. **The floor rises one step after the
+ * publish, not one step before it**, and the sequence is:
+ *
+ *   1. land the export stamped `UNRELEASED` — the floor does not move;
+ *   2. publish (Diego; agents never publish);
+ *   3. replace `UNRELEASED` with the version that publish produced — the floor
+ *      moves here, and the runtime channel's `isolateApiFloor` follows at the
+ *      next channel publish;
+ *   4. tell backend, which holds the number and must ratchet it.
+ *
+ * ⚖️ **Step 3 is a real obligation, not bookkeeping**: an export left
+ * `UNRELEASED` after it ships keeps the floor below its own API forever, so a
+ * host feature-detects something it could have relied on. The guard is the
+ * test's own message.
  */
 
+/** An export present in the tree and in no published version. Excluded from the floor. */
+export const UNRELEASED = 'UNRELEASED'
+
 /** Every export of `@uniweb/runtime/ssr`, with the version it first shipped in. */
 export const ISOLATE_API = Object.freeze({
   // props preparation
@@ -67,13 +105,22 @@ export const ISOLATE_API = Object.freeze({
   // the composed render entry
   createPageRenderer: '0.14.2',
   prefetchAndHydrate: '0.14.2',
+  // the whole corpus, for a host that indexes rather than renders
+  collectSiteRecords: '0.17.0',
 })
 
 /**
  * The runtime version at or above which EVERY name in `ISOLATE_API` is exported —
  * the absolute floor a host may rely on with no feature detection.
  */
-export const ISOLATE_API_FLOOR = Object.values(ISOLATE_API).reduce((max, v) => (compareVersions(v, max) > 0 ? v : max), '0.0.0')
+export const ISOLATE_API_FLOOR = Object.values(ISOLATE_API)
+  .filter((v) => v !== UNRELEASED)
+  .reduce((max, v) => (compareVersions(v, max) > 0 ? v : max), '0.0.0')
+
+/** The exports that exist here and in no published version — empty is the steady state. */
+export const UNRELEASED_EXPORTS = Object.freeze(
+  Object.entries(ISOLATE_API).filter(([, v]) => v === UNRELEASED).map(([name]) => name),
+)
 
 /** Compare two `x.y.z` versions numerically. Returns <0, 0 or >0. */
 export function compareVersions(a, b) {