@uniweb/runtime 0.17.0 → 0.17.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/runtime",
-  "version": "0.17.0",
+  "version": "0.17.2",
   "description": "Minimal runtime for loading Uniweb foundations",
   "type": "module",
   "exports": {
@@ -36,7 +36,7 @@
     "node": ">=20.19"
   },
   "dependencies": {
-    "@uniweb/core": "^0.22.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.39.0"
+    "@uniweb/build": "0.41.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

@@ -12,11 +12,22 @@
  *
  * ⇒ 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).
+ * page render uses**, applying each saved query's own `scope` and `where` — and
+ * asks through the same client.
+ *
+ * ## ⛔ `limit` IS DROPPED, and it is the one place a corpus must diverge
+ *
+ * A saved query's `limit` is the LIST PAGE's presentation: `limit: 20` means the
+ * page shows twenty. **Its detail pages still exist for every record matching
+ * `scope` + `where`** — so a corpus that honoured `limit` would index twenty and
+ * miss every page beyond them, which is worse than indexing nothing because the
+ * gap is invisible.
+ *
+ * ⚠️ **This shipped wrong in 0.17.0 and was found by the consumer, not by us**
+ * (2026-09-06): the config was passed through unchanged, `limit` crossed as the
+ * question's own, and the corpus was capped. The claim that this surface met
+ * "the population its detail pages can reach" was made *"read charitably"* — a
+ * phrase doing work that one `sed` would have done better.
  *
  * ## What the caller supplies
  *
@@ -46,13 +57,29 @@ import { createDefaultFetcher } from './default-fetcher.js'
  * @param {Function} options.fetch - the transport, `(url, init) => Response`
  * @param {AbortSignal} [options.signal]
  * @param {string[]} [options.only] - restrict to these query names
+ * @param {'brief'|'full'} [options.depth='brief'] - what to ask for. `brief` is
+ *   what a list shows; **`full` is what an index wants** — a brief index cannot
+ *   match body text the record's own detail page displays, and a reader who
+ *   finds a word on the page and not in search meets the inconsistency two
+ *   rankings would produce. The cost is the caller's and is bounded by `maxPages`.
+ * @param {number} [options.maxPages] - the caller's own bound on the walk. The
+ *   default is a bound, not a target; a caller that knows its per-request budget
+ *   passes its own.
  * @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.
+ *   same and is null when nothing failed; `meta[name]` carries
+ *   `{ depth, pages, partial?, bound? }`.
+ *
+ *   ⭐ **`partial` means NOT THE WHOLE POPULATION**, and a key can be in BOTH
+ *   `records` and `errors`: a walk that failed or was aborted with pages already
+ *   in hand keeps them, marked. ⛔ Losing them would be indistinguishable from
+ *   "this query has no records", and on an abort every in-flight key fails at
+ *   once — so discarding would lose the corpus, not a key.
  */
-export async function collectSiteRecords(content, { locale, fetch, signal, only = null } = {}) {
+export async function collectSiteRecords(
+  content,
+  { locale, fetch, signal, only = null, depth = 'brief', maxPages } = {},
+) {
   const config = content?.config
   const services = config?.services ?? null
   const queries = config?.queries ?? null
@@ -82,12 +109,18 @@ export async function collectSiteRecords(content, { locale, fetch, signal, only
     // `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 : []
+    // `limit` is the list page's, never the corpus's — see the header.
+    const { limit, ...population } = cfg
+    const asked = { ...population, depth, exhaustive: true }
+    if (typeof maxPages === 'number' && maxPages > 0) asked.maxPages = maxPages
+
+    const result = await fetcher.resolve(asked, { signal })
+    if (result?.error) errors[name] = result.error
+    // ⭐ Data and an error are not exclusive: a partial walk reports both, and
+    // the caller decides whether partial is usable. Only a walk that collected
+    // nothing leaves the key out of `records` entirely.
+    if (Array.isArray(result?.data)) records[name] = result.data
+    else if (!result?.error) records[name] = []
     if (result?.meta) meta[name] = result.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

@@ -276,6 +276,8 @@ function toQuestion(request) {
   // `exhaustive` deliberately does NOT cross — it is a client instruction about
   // how many times to ask, not part of the question being asked.
   if (typeof request.cursor === 'string' && request.cursor) q.cursor = request.cursor
+  // ⛔ `maxPages` does not cross either, for the same reason `exhaustive` does not:
+  // both say how many times to ask, never what is being asked.
   return q
 }
 
@@ -310,7 +312,7 @@ function renameOperators(where) {
  *
  * Two behaviours, deliberately not one:
  *
- *   - **a page render REPORTS** — `meta.truncated` and `meta.bound` ride the
+ *   - **a page render REPORTS** — `meta.partial` 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.
@@ -320,8 +322,16 @@ function renameOperators(where) {
  *     a service that always answers with a cursor cannot spin.
  */
 
-/** Pages an exhaustive request will follow before giving up and reporting truncation. */
-const MAX_PAGES = 50
+/**
+ * Pages an exhaustive request follows before stopping and reporting the answer
+ * as partial. A caller sets its own with `request.maxPages`.
+ *
+ * ⚖️ **20 is a bound, not a target** — it is the value a real caller chose for a
+ * real per-request budget (a search index, 20 × 100), taken as the default
+ * because any bound prevents a runaway and a low one fails visibly rather than
+ * expensively. A caller that knows its budget passes its own.
+ */
+const DEFAULT_MAX_PAGES = 20
 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.
@@ -362,7 +372,15 @@ async function flushAsked(url, queue, doFetch) {
     parsed = await response.json()
   } catch (error) {
     const message = error?.name === 'AbortError' ? 'aborted' : (error?.message || String(error))
-    for (const entry of queue) entry.resolve({ data: null, error: message })
+    // ⛔ AN ABORT KEEPS WHAT ARRIVED. On an exhaustive walk every in-flight key
+    // fails at once here, so discarding held pages loses the whole corpus rather
+    // than one key — the "rejection that loses every key" a caller cannot have.
+    for (const entry of queue) {
+      const held = Array.isArray(entry.collected) && entry.collected.length ? entry.collected : null
+      entry.resolve(held
+        ? { data: held, error: message, meta: withMeta({ partial: true, pages: entry.page }) }
+        : { data: null, error: message })
+    }
     return
   }
   const data = parsed && typeof parsed.data === 'object' && parsed.data ? parsed.data : {}
@@ -373,13 +391,20 @@ async function flushAsked(url, queue, doFetch) {
   const limits = parsed && typeof parsed.limits === 'object' && parsed.limits ? parsed.limits : {}
   queue.forEach((entry, i) => {
     const key = keys[i]
+    // ⛔ A FAILURE MUST NOT DISCARD PAGES ALREADY COLLECTED. An exhaustive walk
+    // that fails on page 7 has six pages in hand, and a caller that asked for a
+    // corpus would rather have them marked partial than lose the key — losing it
+    // is indistinguishable from "this query has no records".
+    const held = Array.isArray(entry.collected) && entry.collected.length ? entry.collected : null
     if (key in errors) {
       // A per-key error is `{ code, detail }` — `schema_not_found`,
       // `field_not_in_brief`, `scope_not_found`… The sentence is `detail`; `code`
       // rides beside it for a reader that wants to branch on it.
       const e = errors[key]
       const detail = typeof e === 'string' ? e : (e?.detail || e?.message || JSON.stringify(e))
-      const out = { data: null, error: detail }
+      const out = held
+        ? { data: held, error: detail, meta: withMeta({ partial: true, pages: entry.page }) }
+        : { data: null, error: detail }
       if (e && typeof e === 'object' && typeof e.code === 'string') out.code = e.code
       entry.resolve(out)
       return
@@ -400,12 +425,15 @@ async function flushAsked(url, queue, doFetch) {
     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) {
+      const cap = typeof entry.request.maxPages === 'number' && entry.request.maxPages > 0
+        ? entry.request.maxPages
+        : DEFAULT_MAX_PAGES
+      if (page <= cap) {
         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 }) })
+      // The caller's own bound, not the service's: report rather than spin.
+      entry.resolve({ data: acc, meta: withMeta({ depth, bound, partial: true, pages: cap }) })
       return
     }
 
@@ -413,10 +441,20 @@ async function flushAsked(url, queue, doFetch) {
     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,
+      // ⭐ ONE FLAG, MEANING **NOT THE WHOLE POPULATION** — asked for by name, so
+      // a caller has one boolean to branch on rather than three signals to
+      // combine. It is set in every case that means it:
+      //   · a cursor came back and this caller does not page (a page render);
+      //   · a cursor came back and the caller's `maxPages` stopped the walk;
+      //   · the walk failed or aborted with pages already in hand;
+      //   · the service reported it BOUNDED the answer and offered no cursor.
+      // ⚠️ The last is why `limits` is read at all: a cursor is the signal for a
+      // query that declared no `limit`, and `limits` is the signal for one whose
+      // author limit was clamped (the records contract §5). Neither alone covers
+      // both. ⛔ Named `truncated` when it shipped in 0.17.0 this morning; renamed
+      // the same day, before any consumer adopted it, because "truncated" says
+      // something was cut and this also means "there is more you did not ask for".
+      partial: (cursor || bound !== undefined) ? true : undefined,
       pages: entry.page && entry.page > 1 ? entry.page : undefined,
     })
     entry.resolve(meta ? { data: collected, meta } : { data: collected })

package/src/isolate-api.js

@@ -106,7 +106,7 @@ export const ISOLATE_API = Object.freeze({
   createPageRenderer: '0.14.2',
   prefetchAndHydrate: '0.14.2',
   // the whole corpus, for a host that indexes rather than renders
-  collectSiteRecords: UNRELEASED,
+  collectSiteRecords: '0.17.0',
 })
 
 /**

package/src/ssr-renderer.js

@@ -18,6 +18,7 @@ import React from 'react'
 import { renderToString } from 'react-dom/server'
 import { createUniweb, resolveDefaultLocale } from '@uniweb/core'
 import { sectionDomId } from '@uniweb/core/section-id'
+import { siteUrl, withOpacity } from './background-shared.js'
 import { routePatternToRegex } from '@uniweb/core/route-match'
 import { DEFAULT_ICON_BASE, iconUrl } from '@uniweb/core/icon-corpus'
 import { buildSectionOverrides, FONT_LINKS_MARKER } from '@uniweb/theming'
@@ -86,37 +87,6 @@ export function getWrapperProps(block) {
   return { id: sectionDomId(block), style, className, background }
 }
 
-/**
- * Convert hex/rgb color to rgba with opacity.
- * Mirrors withOpacity() in Background.jsx.
- */
-function withOpacity(color, opacity) {
-  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
-}
-
-/**
- * Resolve a URL against the site's base path.
- * Mirrors resolveUrl() in Background.jsx.
- */
-function resolveUrl(url) {
-  if (!url || !url.startsWith('/')) return url
-  const basePath = globalThis.uniweb?.activeWebsite?.basePath || ''
-  if (!basePath) return url
-  if (url.startsWith(basePath + '/') || url === basePath) return url
-  return basePath + url
-}
 
 /**
  * Render a background element for SSR.
@@ -189,7 +159,7 @@ export function renderBackground(background) {
         style: {
           position: 'absolute',
           inset: '0',
-          backgroundImage: `url(${resolveUrl(img.src)})`,
+          backgroundImage: `url(${siteUrl(img.src)})`,
           backgroundPosition: img.position || 'center',
           backgroundSize: img.size || 'cover',
           backgroundRepeat: 'no-repeat',