@uniweb/runtime 0.26.5 → 0.26.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/runtime",
-  "version": "0.26.5",
+  "version": "0.26.6",
   "description": "Minimal runtime for loading Uniweb foundations",
   "type": "module",
   "exports": {
@@ -36,7 +36,7 @@
     "node": ">=20.19"
   },
   "dependencies": {
-    "@uniweb/core": "^0.29.4",
+    "@uniweb/core": "^0.29.5",
     "@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.52.7"
+    "@uniweb/build": "0.54.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/isolate-api.js

@@ -102,6 +102,8 @@ export const ISOLATE_API = Object.freeze({
   resolvePageFetchConfigs: '0.14.1',
   executeFetchConfigs: '0.14.1',
   prefetchPageData: '0.14.1',
+  // the render's data step — the same question asked off the graph the render uses
+  loadPageData: UNRELEASED,
   // the composed render entry
   createPageRenderer: '0.14.2',
   prefetchAndHydrate: '0.14.2',

package/src/load-page-data.js

@@ -0,0 +1,138 @@
+/**
+ * THE RENDER'S DATA STEP — the page a visit starts on, fetched by the rule that renders it.
+ *
+ * ⭐ **Why a step at all.** The server render is synchronous: while it renders, a section reads its
+ * data from the cache and never waits for a request (`EntityStore.resolve`). So whatever a page
+ * shows has to be there before the render starts. That is this, and nothing else: it is not an
+ * optimization, it is how a server-rendered page has content.
+ *
+ * ⭐ **Why it runs the render's own rule.** It asks, block by block, exactly what the render will
+ * look for — `EntityStore.fetch`, the same plan `resolve` reads back (`@uniweb/core/page-data`) —
+ * through a dispatcher built from the site's own foundation, so a transport the site chose answers
+ * here too. ⛔ Until 2026-09-19 a host's prefetch worked this out from the payload alone: it could
+ * not know which keys a component declares, which layout the page draws, or which transport a key
+ * is routed to, so it asked for every fetch on every level and still got four cases wrong
+ * (`kb/framework/plans/what-a-page-needs.md` §0). A payload cannot answer those; the graph the
+ * isolate is about to render with can.
+ *
+ * ⚖️ **What it still over-asks.** The blocks are the page's — body, the layout areas it uses, their
+ * child blocks and insets. Whether a component actually draws its children, or a layout its area,
+ * is known only by rendering; a block that declares keys and is never drawn is asked for anyway.
+ * Bounded by what such a block declares, and cheaper than rendering the page twice.
+ *
+ * @module
+ */
+import DataStore, { deriveCacheKey } from '@uniweb/core/datastore'
+import { resolvePage } from './ssr-renderer.js'
+import { getComponentMeta } from './prepare-props.js'
+import { createDefaultFetcher } from './default-fetcher.js'
+
+/**
+ * Every block the page's render can reach: its body and the layout areas it uses (the runtime's own
+ * layout choice — the page's `layout:`, else the foundation's default, else the site's default set,
+ * minus any area the page hides), plus what those blocks hold.
+ */
+function blocksOf(page) {
+  const out = []
+  const walk = (list) => {
+    for (const block of list || []) {
+      if (!block) continue
+      out.push(block)
+      walk(block.childBlocks)
+      walk(block.insets)
+    }
+  }
+  walk(page.getBodyBlocks?.() ?? page.bodyBlocks)
+  for (const area of Object.values(page.getLayoutAreas?.() ?? {})) walk(area)
+  return out
+}
+
+/**
+ * Fetch what one route's render will read.
+ *
+ * @param {Object} options
+ * @param {Object} options.website - the initialized Website the render will use (`initPrerender`)
+ * @param {string|Object} options.route - the route, or an already-resolved Page
+ * @param {Function} options.fetch - the transport, per request
+ * @param {boolean} [options.dev]
+ * @param {string|null} [options.locale] - ⛔ NOT a locale to fetch in: the Website is already
+ *   locale-sliced (`initPrerenderForLocale`) and every address is resolved in ITS locale. Passing
+ *   one that disagrees throws, because the alternative is a page prerendered in one language with
+ *   the data of another, and nothing to see it.
+ * @param {'always'|'author'} [options.prerender] - `'always'` asks for everything, which is what an
+ *   isolate rendering a visit's first page wants; `'author'` honours `prerender: false`.
+ * @returns {Promise<Array<{ config: Object, outcome: 'fetched'|'failed'|'skipped', data: *, meta?: Object, error?: string }>>}
+ *   one entry per request the render will make, keyed downstream by `deriveCacheKey(config)`
+ */
+export async function loadPageData({ website, route, fetch, dev = false, locale = null, prerender = 'always' }) {
+  if (prerender !== 'author' && prerender !== 'always') {
+    throw new Error(`loadPageData: prerender must be 'author' or 'always', got ${JSON.stringify(prerender)}`)
+  }
+  const active = website?.getActiveLocale?.() ?? null
+  if (locale && active && locale !== active) {
+    throw new Error(
+      `loadPageData: this Website renders ${JSON.stringify(active)} and the caller asked for ` +
+      `${JSON.stringify(locale)}. A Website is locale-sliced — build one per locale ` +
+      '(`initPrerenderForLocale`) rather than asking this step for another language.'
+    )
+  }
+  const resolved = typeof route === 'string' ? resolvePage(website, route) : route
+  // Nothing matched: a genuine 404, and the caller's to turn into one. Nothing to fetch.
+  if (!resolved) return []
+  // ⭐ The same promotion the render applies: a content-less folder renders its designated child,
+  // and it is that child's data the page needs.
+  const page = typeof resolved.getRenderableSelf === 'function' ? resolved.getRenderableSelf() : resolved
+
+  // ⛔ A real Page, not page data. `createPageRenderer` tolerates plain data because rendering it
+  // still produces a page; here the same tolerance would walk raw sections, find no blocks and no
+  // graph behind them, and fetch NOTHING — a clean run, an empty page, no error anywhere. That is
+  // the failure this whole step exists to end, so it is refused.
+  if (typeof page.getBodyBlocks !== 'function') {
+    throw new Error('loadPageData: `route` must be a route or a Page from this Website — page data is not enough to say what its render reads.')
+  }
+
+  // A cache of this request's own: the graph's belongs to whatever it is rendering, and a page's
+  // data is asked fresh per request. The site's transports still apply (`dispatcherFor`).
+  const dispatcher = website.dispatcherFor({
+    dataStore: new DataStore(),
+    defaultFetcher: createDefaultFetcher({ basePath: website.config?.base || '', dev, fetch }),
+  })
+
+  /** One entry per request, in the order they were first asked for. */
+  const entries = new Map()
+  const record = (request, entry) => {
+    const key = deriveCacheKey(request)
+    if (!entries.has(key)) entries.set(key, entry)
+  }
+
+  const recording = {
+    peek: (request, ctx) => dispatcher.peek(request, ctx),
+    peekRecord: (id) => dispatcher.peekRecord(id),
+    dispatch: async (request, ctx) => {
+      if (prerender === 'author' && request?.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 fetched, not hydrated.
+        record(request, { config: request, outcome: 'skipped', data: null })
+        return { data: null }
+      }
+      const result = await dispatcher.dispatch(request, ctx)
+      record(request, result?.error
+        ? { config: request, outcome: 'failed', data: null, error: result.error }
+        : { config: request, outcome: 'fetched', data: result?.data ?? null, ...(result?.meta ? { meta: result.meta } : {}) })
+      return result
+    },
+  }
+
+  const store = website.entityStore
+  // ⭐ Every block's first request goes out in the same tick, which is what lets a question door
+  // answer a page in one POST. A step that depends on an answer takes a later one, and only its
+  // own key waits.
+  await Promise.all([
+    // The page's own record: asked whether or not a section declares the route key, because the
+    // page names itself from it and a URL naming no record is a 404.
+    store.fetchPageRecord(page, { dispatcher: recording }),
+    ...blocksOf(page).map((block) => store.fetch(block, getComponentMeta(block.type), { dispatcher: recording })),
+  ])
+
+  return [...entries.values()]
+}

package/src/page-renderer.js

@@ -7,9 +7,10 @@
  *
  *   - `@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).
+ *   - an SSR isolate prerendering the page a visit starts on (the SPA renders every
+ *     page after it) — `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.
@@ -31,7 +32,7 @@
  */
 import { resolvePage, renderPage, classifyRenderError, injectPageContent } from './ssr-renderer.js'
 import { hydrateDataStore } from './wire-foundation.js'
-import { prefetchPageData } from './prefetch.js'
+import { loadPageData } from './load-page-data.js'
 
 /**
  * A renderer bound to one initialized Website and one shell.
@@ -121,6 +122,14 @@ export function createPageRenderer({ website, shell }) {
  * them to tell "nothing was tried" from "everything tried failed", which is a
  * different cache decision.
  *
+ * ⭐ **Since 2026-09-19 it asks what the RENDER will read, block by block** (`loadPageData`),
+ * on the Website it is handed: the keys each component declares, the layout the page actually
+ * draws, and the transport the site chose for a key. `content` is no longer read — the graph
+ * carries everything — and stays in the signature for callers that pass it.
+ * ⛔ `prefetchPageData` works from the payload alone and cannot know any of those; it asks for
+ * every fetch on every level instead, and still gets four cases wrong
+ * (`kb/framework/plans/what-a-page-needs.md` §0). Prefer this entry.
+ *
  * ⛔ 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
@@ -164,7 +173,10 @@ export async function prefetchAndHydrate({ website, content, route, locale = nul
       'To use the ambient fetch deliberately, pass `fetch: globalThis.fetch`.'
     )
   }
-  const fetched = await prefetchPageData({ content, route, locale, fetch, dev, prerender })
+  // ⛔ `locale` is forwarded to be CHECKED, not applied: the Website is locale-sliced already, so a
+  // caller whose two disagree gets an error rather than a page prerendered in one language with the
+  // data of another.
+  const fetched = await loadPageData({ website, route, fetch, dev, locale, prerender })
   hydrateDataStore(website, fetched)
   return fetched
 }

package/src/prefetch.js

@@ -31,13 +31,17 @@
  *                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.
+ *                entry has exactly one kind of caller: an isolate prerendering the page a visit
+ *                starts on, 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").
+ *                ⚠️ That page ONLY: the site is a SPA, and every page after it renders in the
+ *                browser with data the entity store fetches, never through this. (Until 2026-09-19
+ *                this said "an isolate rendering per request", which read as "every page".)
+ *                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, meta?, error? }`, keyed
  *                downstream by `deriveCacheKey(config)`. `outcome` is `fetched`, `failed`
  *                (transport or HTTP error, `error` says which) or `skipped` (the author

package/src/ssr.js

@@ -56,8 +56,18 @@ 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.
+// ⭐ The render's data step — what the page a visit starts on will read, asked block by block on
+// the Website the isolate renders with, so the keys a component declares, the layout the page
+// draws and the transport a key is routed to are all known. A host that hydrates through its own
+// door calls this and hydrates the list itself; `prefetchAndHydrate` is the same step plus the
+// hydration.
+export { loadPageData } from './load-page-data.js'
+
+// Server-side prefetch from the PAYLOAD ALONE — the entry that predates the step above. It cannot
+// know a component's declared keys, a page's layout or a site's transports, so it asks for every
+// fetch on every level and still gets four cases wrong
+// (`kb/framework/plans/what-a-page-needs.md` §0). ⛔ Kept for callers that have no Website to hand;
+// prefer `loadPageData`.
 // [Diego, 2026-09-03]: the backend sets the records service; the fetch comes from the runtime.
 export {
   findPageForRoute,