@uniweb/runtime 0.14.0 → 0.14.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/runtime",
-  "version": "0.14.0",
+  "version": "0.14.2",
   "description": "Minimal runtime for loading Uniweb foundations",
   "type": "module",
   "exports": {
@@ -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.35.0"
+    "@uniweb/build": "0.37.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/default-fetcher.js

@@ -92,7 +92,12 @@ const KNOWN_OPERATORS = new Set(['where', 'limit', 'sort'])
  *   does not carry warns.
  * @returns {{ resolve: (req: Object, ctx: Object) => Promise<{ data, error? }> }}
  */
-export function createDefaultFetcher({ basePath = '', config = {}, dev = false } = {}) {
+export function createDefaultFetcher({ basePath = '', config = {}, dev = false, records = null, fetch: fetchImpl = null } = {}) {
+  // The transport is injectable: a host executing fetches outside a browser (an SSR isolate)
+  // decides how a site-relative address such as `/_records/members` is dispatched — through its
+  // own origin or a service binding — and hands that in. Defaults to the global `fetch`, resolved
+  // at call time so a test stub installed later is honoured.
+  const doFetch = (input, init) => (fetchImpl || globalThis.fetch)(input, init)
   const pathPrefix = basePath && basePath !== '/' ? basePath.replace(/\/$/, '') : ''
 
   const baseUrl = typeof config?.baseUrl === 'string'
@@ -140,6 +145,22 @@ export function createDefaultFetcher({ basePath = '', config = {}, dev = false }
     : null
   const envelope = { ...(style.defaultEnvelope || {}), ...(siteEnvelope || {}) }
 
+  // ⭐ The LIVE LANE's envelope is the backend's. `config.records` is stamped by the backend
+  // that answers a records request, so where the array sits in ITS response is its to
+  // declare: `records.envelope.records` — the KEY says what it holds, the VALUE is the JSON
+  // key the array sits under (`{ records: "entries" }` ⇒ body.entries). That spelling is the
+  // agreed one (2026-08-30: `collection` retired; ⛔ not `list`, which is a URL pattern on the
+  // same stamp). It applies only to a request that resolved to that lane (`endpoint` set)
+  // and wins over the site's own `fetcher.envelope`, which describes the author's backend.
+  // Ruled 2026-09-03 [Diego]: the backend sets `config.records`; the fetch comes from the
+  // runtime. Until this line the runtime resolved `list`/`record` off the stamp and ignored
+  // its envelope.
+  const stampedArrayKey = (records?.envelope && typeof records.envelope === 'object'
+    && typeof records.envelope.records === 'string' && records.envelope.records.length)
+    ? records.envelope.records
+    : null
+  const laneEnvelope = stampedArrayKey ? { list: stampedArrayKey } : null
+
   return {
     /**
      * Cache-key function. The default-fetcher's cache key includes only
@@ -287,7 +308,7 @@ export function createDefaultFetcher({ basePath = '', config = {}, dev = false }
       if (Object.keys(headers).length) init.headers = headers
 
       try {
-        const response = await fetch(target, init)
+        const response = await doFetch(target, init)
 
         // Per-request envelope (set by object-form `detail:`) wins over
         // site-level envelope. This lets a detail query declare its own
@@ -295,7 +316,8 @@ export function createDefaultFetcher({ basePath = '', config = {}, dev = false }
         const requestEnvelope = (request.envelope && typeof request.envelope === 'object')
           ? request.envelope
           : null
-        const effectiveEnvelope = requestEnvelope ?? envelope
+        const effectiveEnvelope = requestEnvelope
+          ?? (endpoint && laneEnvelope ? { ...envelope, ...laneEnvelope } : envelope)
 
         if (!response.ok) {
           // If `envelope.error` is configured, try to extract a human message

package/src/page-renderer.js

@@ -0,0 +1,158 @@
+/**
+ * The composed render entry — resolve a route, render it, inject it into a shell.
+ *
+ * ⭐ **This exists because framework had two callers of one unshared sequence, not
+ * because a consumer asked.** `@uniweb/runtime/ssr` exported every step of the
+ * per-page render and never the sequence, so each host assembled it:
+ *
+ *   - `@uniweb/build`'s `prerender.js` — `renderPage` → classify → `injectPageContent`,
+ *     once per page in its loop.
+ *   - an SSR isolate rendering per request — `resolvePage` → `renderPage` →
+ *     `injectPageContent`, and it wrote the route lookup three times in three files
+ *     before `resolvePage` was exported at all (see that function's header).
+ *
+ * Two unlike callers is what makes the interface honest: a build bakes files and an
+ * isolate answers a request, so anything only one of them needs stayed out.
+ *
+ * ⛔ WHAT IS DELIBERATELY NOT IN HERE, and the boundary is the point:
+ *
+ *   - **Shell assembly.** The shell arrives built. The import map, the CDN base and
+ *     cache headers are host layout, and a runtime that assembled them would be
+ *     modelling a deployment it cannot see (hosting drew this line themselves,
+ *     2026-09-03; `framework/CLAUDE.md` § *Serve locations are read, never constructed*).
+ *   - **Init and hydration.** The two lanes differ REALLY here, not incidentally: a
+ *     build initializes once and hydrates every collection up front, an isolate
+ *     initializes per locale and prefetches per route. Folding either in would fit
+ *     one caller and lie to the other. `initPrerender` / `initPrerenderForLocale` /
+ *     `prefetchPageData` / `hydrateDataStore` stay separate exports, and
+ *     `prefetchAndHydrate` below is the isolate's two-step, not a general one.
+ *   - **Anything build-only.** `injectBuildData` stays in the build lane; it is the
+ *     other half of the head seam and has its own parity guard.
+ */
+import { resolvePage, renderPage, classifyRenderError, injectPageContent } from './ssr-renderer.js'
+import { hydrateDataStore } from './wire-foundation.js'
+import { prefetchPageData } from './prefetch.js'
+
+/**
+ * A renderer bound to one initialized Website and one shell.
+ *
+ * Create it once per locale (the Website is already locale-sliced by
+ * `initPrerenderForLocale`) and call `render` per route or per page.
+ *
+ * @param {Object} opts
+ * @param {Object} opts.website - `uniweb.activeWebsite`, already initialized
+ * @param {string} opts.shell - the HTML shell to inject into, taken as given
+ * @returns {{ website: Object, render: Function }}
+ */
+export function createPageRenderer({ website, shell }) {
+  if (!website) throw new Error('createPageRenderer: `website` is required')
+  if (typeof shell !== 'string') throw new Error('createPageRenderer: `shell` must be an HTML string')
+
+  /**
+   * Render one page.
+   *
+   * ⭐ Returns an OUTCOME rather than throwing or returning a bare string, because
+   * the two callers branch differently on the same three cases and neither wants an
+   * exception: a build logs and keeps going so one broken section cannot fail a whole
+   * site, an isolate decides a status code and a cache policy. Same reasoning as
+   * `prefetchPageData`'s per-entry outcome.
+   *
+   * @param {string|Object} target - a route (`/blog/1`, resolved through the same
+   *   matcher the browser uses, so a dynamic route works) or an already-resolved
+   *   Page, which the build lane already holds from its own loop.
+   * @param {Object} [options]
+   * @param {Object} [options.inject] - extra options forwarded to `injectPageContent`
+   * @returns {{ outcome: 'rendered'|'notFound'|'failed', html: string|null,
+   *   page: Object|null, error: {type: string, message: string}|null }}
+   */
+  function render(target, { inject = {} } = {}) {
+    const page = typeof target === 'string' ? resolvePage(website, target) : target
+
+    // ⛔ Not an error: nothing matched, which is a genuine 404 and the caller's to
+    // turn into one — a build skips it, an isolate serves its 404 page with a 404
+    // status. Returning `failed` here would make those indistinguishable.
+    if (!page) return { outcome: 'notFound', html: null, page: null, error: null }
+
+    let result
+    try {
+      result = renderPage(page, website)
+    } catch (err) {
+      // `renderPage` handles its own errors, but a foundation can throw from
+      // module scope in ways it does not catch. Classify rather than propagate,
+      // so one page cannot take down a build loop or an isolate's request.
+      return { outcome: 'failed', html: null, page, error: classifyRenderError(err) }
+    }
+
+    if (result.error) return { outcome: 'failed', html: null, page, error: result.error }
+
+    // ⛔ `sectionOverrideCSS` LAST, so a caller's `inject` cannot displace it. It is
+    // computed by `renderPage` for this page — theme pinning and component vars —
+    // and a caller passing a same-named key would silently drop it, rendering a page
+    // that looks fine and is unstyled in exactly the places the author pinned. That
+    // is the empty-success shape this module keeps refusing elsewhere; the spread was
+    // the other way round for one commit.
+    const html = injectPageContent(shell, result.renderedContent, page, {
+      ...inject,
+      sectionOverrideCSS: result.sectionOverrideCSS,
+    })
+    return { outcome: 'rendered', html, page, error: null }
+  }
+
+  return { website, render }
+}
+
+/**
+ * Prefetch a route's data and hydrate it onto the graph — the isolate's two-step.
+ *
+ * ⭐ Its whole purpose is that a host stops assembling our structure by hand. It
+ * returns the prefetch outcomes rather than swallowing them, because a host reads
+ * them to tell "nothing was tried" from "everything tried failed", which is a
+ * different cache decision.
+ *
+ * ⛔ The build lane does NOT call this: it hydrates every collection once, before
+ * its page loop, from its own executor that honours the author's `prerender:` flag.
+ * That difference is why this is a named isolate helper and not a step inside
+ * `render`.
+ *
+ * @returns {Promise<Array<{config: Object, outcome: string, data: any, error?: string}>>}
+ */
+export async function prefetchAndHydrate({ website, content, route, locale = null, fetch = null, dev = false, prerender = 'always' }) {
+  // ⛔ Guarded for the same reason `createPageRenderer` is, and it was not for one
+  // commit. `hydrateDataStore` no-ops on a graph with no `dataStore`, so a caller
+  // passing the wrong object gets a successful-looking prefetch, an unhydrated graph
+  // and a page that renders empty — no error anywhere. Fail where the mistake is.
+  if (!website?.dataStore) {
+    throw new Error('prefetchAndHydrate: `website` must be an initialized Website with a dataStore')
+  }
+
+  // ⛔ THE TRANSPORT IS REQUIRED HERE, unlike on `prefetchPageData`, and this is the
+  // one place the difference matters.
+  //
+  // A function does NOT survive every isolate boundary. Measured by hosting under
+  // `wrangler dev` against a real Worker Loader, 2026-09-03: passed through an
+  // entrypoint's `fetch(Request)` with a JSON body the transport arrives
+  // **`undefined`**; passed as an argument to an RPC method it arrives as a callable
+  // function and the isolate invokes it. Only the RPC shape carries it.
+  //
+  // ⚠️ And `undefined` is not where it stops, which is the part their measurement
+  // could not see from outside our code. `createDefaultFetcher` resolves the
+  // transport as `fetchImpl || globalThis.fetch`, so a transport that failed to cross
+  // silently becomes THE ISOLATE'S OWN NETWORK — outside the host's timeout, byte
+  // budget and site-relative address resolution. With an absolute address it does not
+  // even fail: the request goes out from the wrong place and comes back
+  // `outcome: 'fetched'`. A wiring mistake wearing a success.
+  //
+  // ⇒ So the entry whose only caller crosses that boundary demands a real function
+  // rather than defaulting. A Node or browser caller that genuinely wants the global
+  // passes `fetch: globalThis.fetch` — one word, and it says so.
+  if (typeof fetch !== 'function') {
+    throw new Error(
+      'prefetchAndHydrate: `fetch` must be a function. A transport does not survive a ' +
+      'JSON-serialized isolate boundary — pass it as an RPC method argument. ' +
+      'To use the ambient fetch deliberately, pass `fetch: globalThis.fetch`.'
+    )
+  }
+  const fetched = await prefetchPageData({ content, route, locale, fetch, dev, prerender })
+  hydrateDataStore(website, fetched)
+  return fetched
+}

package/src/prefetch.js

@@ -0,0 +1,154 @@
+/**
+ * Server-side data prefetch — the runtime executing a page's fetches for a host.
+ *
+ * L2 (graph state, no React): reads a payload, resolves the fetch configs the way the
+ * entity store does at render time, executes them through the runtime's own default
+ * fetcher, and returns the `[{ config, data }]` list `hydrateDataStore` expects.
+ *
+ * ⭐ Why this exists — one implementation of the fetch, in the runtime. A host that renders
+ * pages in an isolate hands the isolate `fetchedData`. Until this module the host had to
+ * compute that itself: resolve the configs, issue the requests, unwrap the responses in the
+ * shape the datastore expects — a copy of the runtime's logic, in another repo, drifting
+ * (the records envelope went silently unread that way on 2026-09-02). [Diego, 2026-09-03]:
+ * *the backend sets `config.records`; the fetch comes from the runtime.* The host now calls
+ * this and carries no copy. Hosting agreed to exactly that shape the same day.
+ *
+ * ⛔ Contract with the host, deliberately small:
+ *   - `content`  the render payload (`site-content.json` / `__DATA__`), config included —
+ *                `config.records`, `config.fetcher`, `config.base` are read from it.
+ *   - `route`    the page to prefetch for; a `[slug]` template resolves through the same
+ *                matcher the SPA uses, so `/blog/post-1` finds `/blog/:slug`.
+ *   - `fetch`    how to dispatch a request. The runtime composes the address; the host
+ *                decides how a site-relative one is reached (its origin, a binding).
+ *                ⛔ **Crossing an isolate boundary, this survives only as an RPC method
+ *                argument.** Through an entrypoint's `fetch(Request)` with a serialized
+ *                body it arrives `undefined` (hosting, measured under `wrangler dev`
+ *                against a real Worker Loader, 2026-09-03) — and the fetcher then falls
+ *                back to `globalThis.fetch`, so the request leaves from the isolate,
+ *                outside whatever budget the host wrapped around it. `prefetchAndHydrate`
+ *                refuses a non-function for exactly this reason; this entry keeps the
+ *                permissive default because the build and browser lanes call it in-process.
+ *   - `prerender`  whether a fetch is tried — `'always'` (default) tries every config; `'author'`
+ *                honours the author's `prerender: false`. ⛔ The default is `'always'` because this
+ *                entry has exactly one kind of caller: an isolate rendering per request, where the
+ *                flag means nothing and always prerendering is the product ([Diego, 2026-07-28 and
+ *                2026-09-03]: "`prerender: false` is not for the isolate"). The build lane, which
+ *                bakes static artifacts and does honour the flag, uses its own executor
+ *                (`build/src/prerender.js`) and never calls this. `'author'` is the explicit opt-in
+ *                for a caller that bakes; omitting the option must not silently reproduce the
+ *                2026-07-28 outcome — prefetch a no-op on a live-data template, page still 200.
+ *   - returns    one entry per DECLARED config, `{ config, outcome, data, error? }`, keyed
+ *                downstream by `deriveCacheKey(config)`. `outcome` is `fetched`, `failed`
+ *                (transport or HTTP error, `error` says which) or `skipped` (the author
+ *                deferred it to the browser with `prerender: false`). `hydrateDataStore`
+ *                takes the list as-is and hydrates only `fetched` entries — a host reads the
+ *                outcomes to tell "nothing was tried" from "everything tried failed", which
+ *                is a different cache decision (hosting, 2026-09-03).
+ *
+ * It resolves nothing the host owns and models no host route layout: every address is
+ * `{base}/…` from the payload, or an endpoint the host itself published in `config.records`.
+ */
+import { resolveFetchConfigs } from '@uniweb/core/fetch-config'
+import { deriveCacheKey } from '@uniweb/core/datastore'
+import { routePatternToRegex } from '@uniweb/core/route-match'
+import { resolveDefaultLocale } from '@uniweb/core/locale-config'
+import { createDefaultFetcher } from './default-fetcher.js'
+
+const isRefinement = (f) => f && typeof f === 'object' && f.refine === true
+
+/** The page a route names — exact first, then the `[slug]` templates, like the SPA. */
+export function findPageForRoute(content, route) {
+  const pages = content?.pages || []
+  const exact = pages.find((p) => p.route === route)
+  if (exact) return { page: exact, params: {} }
+  for (const page of pages) {
+    if (!page.isDynamic || !page.route) continue
+    const compiled = routePatternToRegex(page.route)
+    const m = compiled?.regex ? compiled.regex.exec(route) : null
+    if (m) return { page, params: Object.fromEntries((compiled.paramNames || []).map((n, i) => [n, m[i + 1]])) }
+  }
+  return { page: null, params: {} }
+}
+
+/**
+ * Every fetch config a page will need at render time, resolved once and de-duplicated by
+ * cache key: the site-level fetch, the page's, its parent's, and each section's own
+ * (including nested sections), each through `resolveFetchConfigs` — the same resolver the
+ * entity store uses, so a host prefetches exactly what the render will ask for.
+ *
+ * @returns {Object[]} resolved fetch configs
+ */
+export function resolvePageFetchConfigs(content, route, { locale = null } = {}) {
+  const { page } = findPageForRoute(content, route)
+  if (!page) return []
+  const pages = content?.pages || []
+  const parent = page.parent ? pages.find((p) => p.route === page.parent) : null
+  const options = {
+    locale,
+    defaultLocale: resolveDefaultLocale(content?.config) ?? null,
+    queries: content?.config?.queries ?? null,
+    records: content?.config?.records ?? null,
+  }
+  const out = new Map()
+  const add = (sources) => {
+    for (const cfg of resolveFetchConfigs(sources, options).values()) {
+      const key = deriveCacheKey(cfg)
+      if (!out.has(key)) out.set(key, cfg)
+    }
+  }
+  // The cascade a block sees: its own fetch (unless a refinement), page, parent, site.
+  add([page.fetch ?? null, parent?.fetch ?? null, content?.config?.fetch ?? null])
+  const walk = (sections) => {
+    for (const s of sections || []) {
+      if (s?.fetch && !isRefinement(s.fetch)) add([s.fetch, page.fetch ?? null, parent?.fetch ?? null, content?.config?.fetch ?? null])
+      if (s?.subsections) walk(s.subsections)
+    }
+  }
+  walk(page.sections)
+  return [...out.values()]
+}
+
+/**
+ * Execute resolved fetch configs through the runtime's default fetcher.
+ *
+ * @param {Object[]} configs  resolved configs (from `resolvePageFetchConfigs` or the host's own
+ *                             call to `resolveFetchConfigs`)
+ * @param {Object} opts
+ * @param {Object} opts.content  the payload — `config.base`, `config.fetcher`, `config.records`
+ * @param {Function} [opts.fetch]  the transport; defaults to the global `fetch`
+ * @param {boolean} [opts.dev]
+ * @returns {Promise<Array<{ config: Object, outcome: 'fetched'|'failed'|'skipped', data: any, error?: string }>>}
+ */
+export async function executeFetchConfigs(configs, { content, fetch = null, dev = false, prerender = 'always' } = {}) {
+  if (prerender !== 'author' && prerender !== 'always') {
+    throw new Error(`executeFetchConfigs: prerender must be 'author' or 'always', got ${JSON.stringify(prerender)}`)
+  }
+  const fetcher = createDefaultFetcher({
+    basePath: content?.config?.base || '',
+    config: content?.config?.fetcher ?? {},
+    records: content?.config?.records ?? null,
+    dev,
+    fetch,
+  })
+  const ctx = { website: null }
+  const out = []
+  for (const config of configs || []) {
+    if (!config) continue
+    if (prerender === 'author' && config.prerender === false) {
+      // The author deferred this one to the browser and the caller honours that. Present, so a
+      // host can count what was declared against what was tried; not hydrated.
+      out.push({ config, outcome: 'skipped', data: null })
+      continue
+    }
+    const result = await fetcher.resolve(config, ctx)
+    if (result?.error) out.push({ config, outcome: 'failed', data: null, error: result.error })
+    else out.push({ config, outcome: 'fetched', data: result?.data ?? null })
+  }
+  return out
+}
+
+/** Resolve and execute in one call: what a host passes the isolate as `fetchedData`. */
+export async function prefetchPageData({ content, route, locale = null, fetch = null, dev = false, prerender = 'always' }) {
+  const configs = resolvePageFetchConfigs(content, route, { locale })
+  return executeFetchConfigs(configs, { content, fetch, dev, prerender })
+}

package/src/setup.js

@@ -244,8 +244,11 @@ function buildDefaultFetcher(content) {
   // recognizes `baseUrl` and `envelope`; foundations with their own fetchers
   // may read additional keys from the same block via ctx.website.config.fetcher.
   const config = content?.config?.fetcher ?? {}
+  // The host's live-records stamp (`config.records`), when a backend set one: the fetcher
+  // reads its `envelope` for requests that resolved to that lane.
+  const records = content?.config?.records ?? null
   const dev = !!(import.meta.env && import.meta.env.DEV)
-  return createDefaultFetcher({ basePath, config, dev })
+  return createDefaultFetcher({ basePath, config, dev, records })
 }
 
 /**

package/src/ssr.js

@@ -56,6 +56,22 @@ export {
   generate404Html,
 } from './ssr-renderer.js'
 
+// Server-side prefetch — the runtime executing a page's fetches for a host, so an isolate
+// receives `fetchedData` computed by our fetcher and the host carries no copy of it.
+// [Diego, 2026-09-03]: the backend sets config.records; the fetch comes from the runtime.
+export {
+  findPageForRoute,
+  resolvePageFetchConfigs,
+  executeFetchConfigs,
+  prefetchPageData,
+} from './prefetch.js'
+
+// The composed render entry — resolve, render, inject, as one call. Built because
+// framework itself had two callers of this unshared sequence (the build's prerender
+// loop and an SSR isolate), not because a consumer asked; see page-renderer.js for
+// what it deliberately leaves to the host.
+export { createPageRenderer, prefetchAndHydrate } from './page-renderer.js'
+
 // Appearance. injectPageContent() already emits this for every prerendered
 // page; exported for lanes that assemble a shell without a per-page render.
 export { renderAppearanceBootScript } from './appearance.js'

package/src/wire-foundation.js

@@ -163,6 +163,9 @@ export function sliceContentForLocale(content, locale) {
 export function hydrateDataStore(website, fetchedData) {
   if (!website?.dataStore || !fetchedData?.length) return
   for (const entry of fetchedData) {
+    // A `prefetchPageData` list carries every declared config with an `outcome`; only what was
+    // actually fetched enters the store. A list without outcomes (the SSG lane's) is all fetched.
+    if (entry.outcome && entry.outcome !== 'fetched') continue
     website.dataStore.set(deriveCacheKey(entry.config), { data: entry.data })
   }
 }