@uniweb/runtime 0.14.2 → 0.16.0

package/src/isolate-api.js

@@ -0,0 +1,87 @@
+/**
+ * The isolate API — what `@uniweb/runtime/ssr` promises a host that renders in an
+ * isolate, and the runtime version below which that promise does not hold.
+ *
+ * ⭐ THE ONE PLACE THE NUMBER IS STATED. A host loads the SITE'S pinned runtime as a
+ * dynamically-loaded artifact — never an import — so it cannot link-check what it
+ * calls; it feature-detects, and an export that is missing looks exactly like an old
+ * runtime. The backend evaluates a site's runtime at publish and holds this floor as
+ * a constant of its own [Diego, 2026-09-04: "We will set a runtime version floor that
+ * guarantees they are there"], composing it as `max(absoluteFloor, foundationFloors)`.
+ * That constant is copied from here, and `tests/isolate-api.test.js` is what keeps
+ * this file honest: every export of `src/ssr.js` must appear below with the version
+ * it first shipped in, and every name below must still be exported — by the source
+ * and by the built `dist/ssr.js` when it is present. Forgetting to stamp a new export
+ * fails HERE, in the repo where the change happens; a rename fails here too.
+ *
+ * ⛔ A floor is a promise about a VERSION, not a rename guard. A site on a newer
+ * runtime with a renamed export is still a missing symbol; the test above is what
+ * makes that fail before it ships, and the announcement to the consumer is still
+ * ours to send, because a consumer that bundles this package by workspace link
+ * gets the change at commit time, with no version to pin against.
+ *
+ * ⛔ Not `runtime-pin.json`. That file is emitted per FOUNDATION build and records an
+ * observed fact ("built against"), never a guarantee; an isolate-API floor is a
+ * guarantee and is not a property of any foundation. Different kind of claim,
+ * different home.
+ *
+ * "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.
+ */
+
+/** Every export of `@uniweb/runtime/ssr`, with the version it first shipped in. */
+export const ISOLATE_API = Object.freeze({
+  // props preparation
+  prepareProps: '0.2.15',
+  applySchemas: '0.2.15',
+  applyDefaults: '0.2.15',
+  guaranteeContentStructure: '0.2.15',
+  getComponentMeta: '0.2.15',
+  getComponentDefaults: '0.2.15',
+  // rendering
+  getWrapperProps: '0.6.14',
+  renderBackground: '0.6.14',
+  renderBlock: '0.6.14',
+  renderBlocks: '0.6.14',
+  renderLayout: '0.6.14',
+  renderPage: '0.2.15',
+  classifyRenderError: '0.6.14',
+  injectPageContent: '0.6.14',
+  escapeHtml: '0.6.14',
+  generate404Html: '0.6.16',
+  // initialization
+  initPrerender: '0.6.14',
+  initPrerenderForLocale: '0.8.9',
+  sliceContentForLocale: '0.8.9',
+  hydrateDataStore: '0.8.9',
+  prefetchIcons: '0.6.14',
+  renderAppearanceBootScript: '0.8.30',
+  // page resolution
+  resolvePage: '0.9.5',
+  // server-side prefetch — the runtime executing a page's fetches for a host
+  findPageForRoute: '0.14.1',
+  resolvePageFetchConfigs: '0.14.1',
+  executeFetchConfigs: '0.14.1',
+  prefetchPageData: '0.14.1',
+  // the composed render entry
+  createPageRenderer: '0.14.2',
+  prefetchAndHydrate: '0.14.2',
+})
+
+/**
+ * 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')
+
+/** Compare two `x.y.z` versions numerically. Returns <0, 0 or >0. */
+export function compareVersions(a, b) {
+  const pa = String(a).split('.').map((n) => parseInt(n, 10) || 0)
+  const pb = String(b).split('.').map((n) => parseInt(n, 10) || 0)
+  for (let i = 0; i < Math.max(pa.length, pb.length); i += 1) {
+    const d = (pa[i] || 0) - (pb[i] || 0)
+    if (d !== 0) return d
+  }
+  return 0
+}

package/src/page-renderer.js

@@ -18,8 +18,8 @@
  *
  *   - **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*).
+ *     modelling a deployment it cannot see (the host drew this line itself,
+ *     2026-09-03: a serve location is read from the payload, never constructed here).
  *   - **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

package/src/prefetch.js

@@ -15,7 +15,7 @@
  *
  * ⛔ 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.
+ *                `config.records` and `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
@@ -37,7 +37,7 @@
  *                (`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
+ *   - returns    one entry per DECLARED config, `{ config, outcome, data, meta?, 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`
@@ -46,17 +46,23 @@
  *                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`.
+ * `{base}/…` from the payload, or the question door the host itself published at
+ * `config.records.query`.
  */
 import { resolveFetchConfigs } from '@uniweb/core/fetch-config'
 import { deriveCacheKey } from '@uniweb/core/datastore'
-import { routePatternToRegex } from '@uniweb/core/route-match'
+import { routePatternToRegex, decodeRouteValue, splitPathCapture } from '@uniweb/core/route-match'
+import { buildDetailConfig } from '@uniweb/core/detail-url'
 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. */
+/**
+ * The page a route names — exact first, then the `[slug]` / `[...path]` templates, like
+ * the SPA. Captured params are decoded the way `matchDynamicRoute` decodes them (a
+ * catch-all per segment), so the values are what the site's query is bound against.
+ */
 export function findPageForRoute(content, route) {
   const pages = content?.pages || []
   const exact = pages.find((p) => p.route === route)
@@ -65,11 +71,35 @@ export function findPageForRoute(content, route) {
     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]])) }
+    if (m) {
+      const params = {}
+      ;(compiled.paramNames || []).forEach((n, i) => {
+        const raw = m[i + 1]
+        params[n] = n === compiled.catchAll ? raw.split('/').map(decodeRouteValue).join('/') : decodeRouteValue(raw)
+      })
+      return { page, params }
+    }
   }
   return { page: null, params: {} }
 }
 
+/**
+ * The route's variables and the delivery param for a matched template page — the same
+ * binding the SPA makes in `Website._createDynamicPage`: `[slug]` binds the one capture
+ * under the folder's own name; `[...path]` splits its capture into `path` / `dir` /
+ * `slug` and delivers by `slug`, the record's handle.
+ */
+function routeBinding(page, params) {
+  const { catchAll } = routePatternToRegex(page.route)
+  if (catchAll && params[catchAll] !== undefined) {
+    const parts = splitPathCapture(params[catchAll])
+    const paramName = page.paramName || 'slug'
+    return { paramName, paramValue: parts.slug, variables: { ...params, ...parts } }
+  }
+  const paramName = page.paramName || Object.keys(params)[0]
+  return { paramName, paramValue: params[paramName], variables: { ...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
@@ -79,15 +109,17 @@ export function findPageForRoute(content, route) {
  * @returns {Object[]} resolved fetch configs
  */
 export function resolvePageFetchConfigs(content, route, { locale = null } = {}) {
-  const { page } = findPageForRoute(content, route)
+  const { page, params } = findPageForRoute(content, route)
   if (!page) return []
   const pages = content?.pages || []
   const parent = page.parent ? pages.find((p) => p.route === page.parent) : null
+  const binding = page.isDynamic && Object.keys(params).length ? routeBinding(page, params) : null
   const options = {
     locale,
     defaultLocale: resolveDefaultLocale(content?.config) ?? null,
     queries: content?.config?.queries ?? null,
     records: content?.config?.records ?? null,
+    variables: binding?.variables ?? null,
   }
   const out = new Map()
   const add = (sources) => {
@@ -105,6 +137,23 @@ export function resolvePageFetchConfigs(content, route, { locale = null } = {})
     }
   }
   walk(page.sections)
+
+  // ⭐ A template page is ABOUT one record, and the record is a fetch of its own.
+  // The list the page inherits is what the entity store matches the route param
+  // against; when that query has a per-record source (a live lane's record address,
+  // a `deferred:` query's per-record file), the record itself comes from a second
+  // request — which this helper never built, so a host prerendering a template page
+  // got the BRIEF and the body arrived after hydration as a client fetch. The
+  // detail config is built by the one rule the
+  // entity store uses (`buildDetailConfig`), keyed by the route's param.
+  if (binding && binding.paramValue !== undefined && page.parentSchema) {
+    const listCfg = [...out.values()].find((cfg) => cfg.as === page.parentSchema && cfg.detail)
+    const detailCfg = listCfg ? buildDetailConfig(listCfg, { paramName: binding.paramName, paramValue: String(binding.paramValue) }) : null
+    if (detailCfg) {
+      const key = deriveCacheKey(detailCfg)
+      if (!out.has(key)) out.set(key, detailCfg)
+    }
+  }
   return [...out.values()]
 }
 
@@ -114,7 +163,7 @@ export function resolvePageFetchConfigs(content, route, { locale = null } = {})
  * @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 {Object} opts.content  the payload — `config.base`, `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 }>>}
@@ -125,26 +174,23 @@ export async function executeFetchConfigs(configs, { content, fetch = null, dev
   }
   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
+  // Dispatched together, not one after another: a question door batches the
+  // requests issued in one tick into one POST, and a page's configs are
+  // independent of each other. Order is preserved in the result.
+  return Promise.all((configs || []).filter(Boolean).map(async (config) => {
     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
+      return { config, outcome: 'skipped', data: null }
     }
     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
+    if (result?.error) return { config, outcome: 'failed', data: null, error: result.error }
+    return { config, outcome: 'fetched', data: result?.data ?? null, ...(result?.meta ? { meta: result.meta } : {}) }
+  }))
 }
 
 /** Resolve and execute in one call: what a host passes the isolate as `fetchedData`. */

package/src/prepare-props.js

@@ -266,7 +266,7 @@ function applyRichSchemaToValue(value, schema) {
  * form-definition schema — which cannot name the author's fields — can never
  * reach into them. It fills the envelope defaults its own author declared.
  *
- * (Established with the editor team, 2026-07-31, channel frontend-framework-066d.
+ * (Established with the editor team, 2026-07-31, channel frontend↔framework.
  * The editor shadows a foundation's `form` declaration with its own builder via
  * `builtinSchemas()`; that is about the EDITING UI and is orthogonal to whether a
  * foundation declares a schema for validation.)

package/src/setup.js

@@ -240,15 +240,14 @@ function buildDefaultFetcher(content) {
   // serve data wherever it likes — including intercepting a site-local path and
   // proxying it onward — with no framework change.
   const basePath = content?.config?.base || import.meta.env?.BASE_URL || ''
-  // Per-site transport config from `site.yml fetcher:`. The default fetcher
-  // 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
+  // ⛔ `site.yml fetcher:` is NOT read here — the default fetcher takes no
+  // site-level vocabulary (retired 2026-09-04: baseUrl / headers / envelope /
+  // supports / request). The block is the site's SELECTION of foundation
+  // transports (`fetcher.transports`) plus a transport's own binding config,
+  // which a transport reads through ctx.website.config.fetcher.
+  //
   const dev = !!(import.meta.env && import.meta.env.DEV)
-  return createDefaultFetcher({ basePath, config, dev, records })
+  return createDefaultFetcher({ basePath, dev })
 }
 
 /**

package/src/wire-foundation.js

@@ -166,7 +166,9 @@ export function hydrateDataStore(website, 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 })
+    // `meta` (the depth the records were fetched at) rides along, so the store
+    // files them in its record index exactly as a runtime fetch would.
+    website.dataStore.set(deriveCacheKey(entry.config), entry.meta ? { data: entry.data, meta: entry.meta } : { data: entry.data })
   }
 }