@uniweb/runtime 0.13.7 → 0.14.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/runtime",
-  "version": "0.13.7",
+  "version": "0.14.1",
   "description": "Minimal runtime for loading Uniweb foundations",
   "type": "module",
   "exports": {
@@ -36,7 +36,7 @@
     "node": ">=20.19"
   },
   "dependencies": {
-    "@uniweb/core": "^0.18.0",
+    "@uniweb/core": "^0.19.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.34.0"
+    "@uniweb/build": "0.36.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/default-fetcher.js

@@ -16,7 +16,7 @@
  *       X-Tenant: acme
  *       Accept: application/vnd.example+json
  *     envelope:
- *       collection: data.items
+ *       list: data.items
  *       item: data.article
  *       error: errors.0.message
  *
@@ -64,10 +64,11 @@ import {
   resolveServiceUrl,
 } from '@uniweb/core'
 
-// Phase 2 of the request-styles landing will read `config.request.style`
-// and dispatch through the registry; in Phase 1 we hard-wire the ambient
-// default (json-body) via the same resolver. No behavior change — the
-// resolved style is json-body, which encodes today's conventions.
+// The request style is the wire dialect operators are encoded in. One
+// ships — json-body, the framework's own — and `resolveRequestStyle` is
+// loud on any other name: it throws in dev and logs once in production.
+// Another dialect is a named transport, from the foundation or from an
+// extension the site selects; it is never a second built-in style.
 
 // Operators the default fetcher knows how to handle. When listed in
 // `config.supports`, they're shipped to the source as part of the
@@ -86,11 +87,17 @@ const KNOWN_OPERATORS = new Set(['where', 'limit', 'sort'])
  *   `request.rename`. Unknown keys are ignored (foundations may use the
  *   same block for their own keys). Default behavior (empty config)
  *   matches today's plain GET + JSON.
- * @param {boolean} [options.dev=false] - Enable dev-mode warnings (unknown
- *   style name, unknown rename operator).
+ * @param {boolean} [options.dev=false] - Enable dev-mode diagnostics: an
+ *   unknown request style throws; a rename entry for an operator the wire
+ *   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'
@@ -108,9 +115,10 @@ export function createDefaultFetcher({ basePath = '', config = {}, dev = false }
   // default fetcher serving static files supports nothing natively.
   const supports = normalizeSupports(config?.supports)
 
-  // Request style — how operators get reshaped for the wire. Selected
-  // by name via `site.yml fetcher.request.style`; `null`/absent resolves
-  // to the ambient default (json-body).
+  // Request style — the wire dialect operators are encoded in. Read from
+  // `site.yml fetcher.request.style`; `null`/absent and `json-body` both
+  // resolve to the one shipped style, and any other name is loud (see
+  // `resolveRequestStyle`).
   const requestConfig = (config?.request && typeof config.request === 'object') ? config.request : {}
   const styleName = typeof requestConfig.style === 'string' ? requestConfig.style : null
   const style = resolveRequestStyle(styleName, { dev })
@@ -129,14 +137,30 @@ export function createDefaultFetcher({ basePath = '', config = {}, dev = false }
   //   - envelope.error      — extract error text from non-2xx response body.
   //
   // Priority (highest wins): per-fetch request.envelope > site-level
-  // config.envelope > style.defaultEnvelope. A style that defaults an
-  // envelope (e.g. Strapi's `{ data }` wrapper) still defers to any
-  // explicit site-level override.
+  // config.envelope > style.defaultEnvelope. json-body declares no
+  // envelope; the slot is the encoder's to fill, and a site-level value
+  // always wins over it.
   const siteEnvelope = (config?.envelope && typeof config.envelope === 'object')
     ? config.envelope
     : 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
@@ -155,9 +179,8 @@ export function createDefaultFetcher({ basePath = '', config = {}, dev = false }
       // style will actually push for this request. deriveCacheKey already
       // covers the always-keyed fields.
       //
-      // The key also includes the style name — two sites with different
-      // styles against the same URL produce different wire requests, so
-      // their responses must not alias.
+      // The key also carries the style name. With one shipped style it is
+      // a constant segment, kept so that key shapes do not move.
       const base = deriveCacheKey(request)
       const projected = {}
       for (const op of supports) {
@@ -230,10 +253,10 @@ export function createDefaultFetcher({ basePath = '', config = {}, dev = false }
       // style didn't push get applied as a JS fallback after the response
       // (see the post-fetch block below).
       //
-      // The style owns the wire format. Today's json-body style encodes
-      // GET pushdown as `?_where=<JSON>&_limit=&_sort=` and POST pushdown
-      // as top-level keys merged into an object body. Other styles
-      // (flat-query, strapi) will ship in Phase 3.
+      // The style owns the wire format: json-body encodes GET pushdown as
+      // `?_where=<JSON>&_limit=&_sort=` and POST pushdown as top-level keys
+      // merged into an object body. It is the only shipped wire — another
+      // dialect is a named transport.
       const pushCandidates = new Set()
       if (isRemote) {
         for (const op of KNOWN_OPERATORS) {
@@ -285,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
@@ -293,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/prefetch.js

@@ -0,0 +1,146 @@
+/**
+ * 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).
+ *   - `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,16 @@ 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'
+
 // 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 })
   }
 }