@uniweb/runtime 1.2.5 → 1.2.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/runtime",
-  "version": "1.2.5",
+  "version": "1.2.7",
   "description": "Minimal runtime for loading Uniweb foundations",
   "type": "module",
   "exports": {
@@ -36,7 +36,7 @@
     "node": ">=22.12"
   },
   "dependencies": {
-    "@uniweb/core": "~1.4.9",
+    "@uniweb/core": "~1.4.10",
     "@uniweb/theming": "~1.2.1"
   },
   "devDependencies": {
@@ -44,7 +44,7 @@
     "esbuild": "^0.21.0 || ^0.23.0 || ^0.24.0 || ^0.25.0 || ^0.27.0 || ^0.28.0",
     "vite": "^7.3.1",
     "vitest": "^4.1.7",
-    "@uniweb/build": "1.10.6"
+    "@uniweb/build": "1.10.8"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/load-page-data.js

@@ -23,7 +23,7 @@
  * @module
  */
 import DataStore, { deriveCacheKey } from '@uniweb/core/datastore'
-import { resolvePage } from './resolve-page.js'
+import { resolveRequestedPage } from './resolve-page.js'
 import { getComponentMeta } from './prepare-props.js'
 import { createDefaultFetcher } from './default-fetcher.js'
 import { requireTransport } from './require-transport.js'
@@ -53,7 +53,9 @@ function blocksOf(page) {
  *
  * @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 {string|Object} options.route - the route, or an already-resolved Page. A route that names
+ *   no page, or a page served from elsewhere (`rewrite:`), asks for the site's not-found page's
+ *   data, the page its render draws.
  * @param {Function} options.fetch - the transport, per request. Required: a missing one is refused,
  *   never replaced by the ambient `fetch` (`require-transport.js`)
  * @param {boolean} [options.dev]
@@ -93,8 +95,11 @@ export async function loadPageData({ website, route, fetch, dev = false, locale
   // through the global, and a host holding several graphs in one isolate has it naming the newest
   // (`Website#makeCurrent`).
   website.makeCurrent()
-  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.
+  const named = typeof route === 'string' ? resolveRequestedPage(website, route) : route
+  // ⭐ A route that names no page, or a page served from elsewhere (`resolveRequestedPage`), renders
+  // the site's not-found page (`createPageRenderer`), so it is that page's data the render reads.
+  // With no such page: a genuine 404, the caller's to turn into one, and nothing to fetch.
+  const resolved = named ?? (typeof route === 'string' ? website.getNotFoundPage() : null)
   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.

package/src/page-renderer.js

@@ -33,10 +33,12 @@
  *   - **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 { renderPage, classifyRenderError, injectPageContent } from './ssr-renderer.js'
+import { resolveRequestedPage } from './resolve-page.js'
 import { hydrateDataStore } from './wire-foundation.js'
 import { loadPageData } from './load-page-data.js'
 import { requireTransport } from './require-transport.js'
+import { restoreStartPage } from './start-page.js'
 
 /**
  * A renderer bound to one initialized Website and one shell.
@@ -64,7 +66,11 @@ export function createPageRenderer({ website, shell }) {
    *
    * @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.
+   *   Page, which the build lane already holds from its own loop. A route that names
+   *   no page renders the site's not-found page (`website.getNotFoundPage()`), as the
+   *   browser does for it, and so does a route naming a page served from elsewhere
+   *   (`rewrite:`): a request for it that reaches a renderer was not proxied, and the
+   *   browser's first load of it draws the not-found page too.
    * @param {Object} [options]
    * @param {Object} [options.inject] - extra options forwarded to `injectPageContent`
    * @param {Array<{config: Object, data: *, meta?: Object}>} [options.fetchedData] - the entries
@@ -76,12 +82,16 @@ export function createPageRenderer({ website, shell }) {
    * @returns {{ outcome: 'rendered'|'notFound'|'failed', html: string|null,
    *   page: Object|null, error: {type: string, message: string}|null }}
    *   `notFound` means the URL names nothing, and `html` says whether there is a page to
-   *   send for it:
-   *   - `page: null`, `html: null` — no route matched. Send your own not-found page.
-   *   - `page` set, `html` set — the page's record does not exist, and `html` is the page
-   *     rendered in its own not-found state. Send it, with your not-found status.
-   *   - `page` set, `html: null`, `error` set — that not-found state broke while rendering.
-   *     Send your own not-found page; `error` says what broke.
+   *   send for it. Send `html` with your not-found status when it is set, and the shell
+   *   when it is not:
+   *   - `page` set, `html` set — the site's not-found page, for a route that names no page
+   *     or a page served from elsewhere; or a page whose record does not exist, rendered in
+   *     its own not-found state.
+   *   - `page: null`, `html: null` — no route matched, or it names a page served from
+   *     elsewhere, and the site has no not-found page. The browser shows its default
+   *     not-found message.
+   *   - `page` set, `html: null`, `error` set — that page broke while rendering; `error`
+   *     says what broke.
    */
   function render(target, { inject = {}, fetchedData } = {}) {
     if (fetchedData !== undefined && !Array.isArray(fetchedData)) {
@@ -101,11 +111,19 @@ export function createPageRenderer({ website, shell }) {
       website.forgetData()
       hydrateDataStore(website, fetchedData)
     }
-    const resolved = typeof target === 'string' ? resolvePage(website, target) : target
+    const named = typeof target === 'string' ? resolveRequestedPage(website, target) : target
+    // ⭐ A ROUTE THAT NAMES NO PAGE RENDERS THE SITE'S NOT-FOUND PAGE, as the browser does for
+    // it (`PageRenderer.jsx`), and the data step asks for that page's data (`loadPageData`). No
+    // route names it (`/404` is never routable), so this is the only way a route reaches it.
+    // A route naming a page served from elsewhere is answered the same way: the host did not
+    // proxy it (`resolveRequestedPage`).
+    // ⛔ Until 2026-10-26 this answered `notFound` with nothing to send, and a host that wanted
+    // the site's page had to fetch its data and render it as a Page itself.
+    const resolved = named ?? (typeof target === 'string' ? website.getNotFoundPage() : null)
 
-    // ⛔ 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.
+    // ⛔ Not an error: nothing matched and the site has no not-found page — a genuine 404,
+    // and the caller's to turn into one: a build skips it, an isolate sends the shell with a
+    // 404 status. Returning `failed` here would make those indistinguishable.
     if (!resolved) return { outcome: 'notFound', html: null, page: null, error: null }
 
     // ⭐ **THE INDEX-CHILD PROMOTION APPLIES TO BOTH TARGET FORMS** — ruled
@@ -125,11 +143,21 @@ export function createPageRenderer({ website, shell }) {
     // (`Website#_createDynamicPage`), never on a failed or missing fetch. It renders the
     // page's own not-found state — a record miss is not a route miss — and the outcome
     // says `notFound` all the same, so a caller keying its status on the outcome sends a
-    // not-found response without reading anything new. Known before rendering, so it
-    // holds even when that render breaks. ⛔ Until 2026-09-30 this was `rendered`, and a
+    // not-found response without reading anything new. The site's not-found page, rendered
+    // for a route that names no page, is `notFound` the same way. Known before rendering, so
+    // it holds even when that render breaks. ⛔ Until 2026-09-30 this was `rendered`, and a
     // host that answered by the outcome sent 200 for a URL naming no record.
-    const missing = page?.notFound === true
+    const missing = !named || page?.notFound === true
 
+    // ⭐ EVERY RENDER STARTS FROM THE ACTIVE PAGE THE WEBSITE STARTED WITH (`start-page.js`),
+    // then makes active the page the route names, as the browser's boot does (`index.jsx`).
+    // `renderPage` then makes the page it renders active by its route, and the not-found page
+    // has none: it renders with the page a route served from elsewhere names, as in the browser,
+    // or with the start page. ⛔ Until 2026-10-26 it rendered with whatever page this Website
+    // rendered last, so on a Website reused across requests its header could show the previous
+    // request's page.
+    restoreStartPage(website)
+    if (typeof target === 'string') website.setActivePage(target)
     let result
     try {
       result = renderPage(page, website)

package/src/resolve-page.js

@@ -39,3 +39,22 @@
 export function resolvePage(website, route) {
   return website.getPage(route)
 }
+
+/**
+ * The page a request for `route` renders, for the doors that render the page a visit starts on
+ * (`createPageRenderer`, and its data step `loadPageData`): `resolvePage`, except a page served from
+ * elsewhere.
+ *
+ * ⭐ A page with `rewrite:` is the host's to proxy, before the app loads. A request for one that
+ * reaches a renderer was not proxied, so the doors answer it as the browser's first load of it does
+ * (`PageRenderer.jsx`): with the site's not-found page, as a static build emits no file there.
+ * ⛔ Until 2026-10-27 they rendered that page's own content as an ordinary page, and the browser
+ * replaced it with the not-found page at boot.
+ *
+ * @param {Website} website
+ * @param {string} route - The requested path
+ * @returns {Page|undefined} undefined when the route names no page, or a page served from elsewhere
+ */
+export function resolveRequestedPage(website, route) {
+  return website.resolveRoute(route).kind === 'rewrite' ? undefined : resolvePage(website, route)
+}

package/src/ssr-renderer.js

@@ -37,6 +37,7 @@ import { layoutStickiness, sectionStickyProps, sectionScrollMargin, zoneProps }
 import { DefaultLayout } from './default-layout.js'
 import { renderAppearanceBootScript } from './appearance.js'
 import { documentTitle } from './document-title.js'
+import { recordStartPage } from './start-page.js'
 import { escapeHtml } from '@uniweb/core/page-shell'
 
 // Re-export L2 helpers so the public `@uniweb/runtime/ssr` surface
@@ -360,6 +361,8 @@ export function initPrerender(content, foundation, extensionsOrOptions, maybeOpt
   // Uniweb constructor wires foundation, capabilities, layoutMeta, handlers,
   // and extensions at construction time — see `@uniweb/core`'s src/uniweb.js.
   const uniweb = createUniweb(content, foundation, extensions)
+  // Before anything renders: the active page every render starts from (`start-page.js`).
+  recordStartPage(uniweb.activeWebsite)
 
   // Set base path from site config for subdirectory deployments
   if (content.config?.base && uniweb.activeWebsite?.setBasePath) {
@@ -398,7 +401,11 @@ export function initPrerender(content, foundation, extensionsOrOptions, maybeOpt
 
   // Register SSR-safe routing so useRouting()/useActiveRoute() work during prerender.
   // renderPage() calls website.setActivePage() before rendering each page,
-  // so activePage.route always reflects the page being rendered.
+  // so activePage.route reflects the page being rendered — except the site's
+  // not-found page, which no route names. Through `createPageRenderer` it renders
+  // with the page a route served from elsewhere names, else the page the Website
+  // starts with (`start-page.js`); through `generate404Html`, with the page
+  // rendered last.
   const website = uniweb.activeWebsite
   uniweb.routingComponents = {
     useLocation: () => {
@@ -524,7 +531,11 @@ export function classifyRenderError(err) {
  * @returns {{ renderedContent: string, sectionOverrideCSS: string } | { error: { type: string, message: string } }}
  */
 export function renderPage(page, website) {
-  website.setActivePage(page.route)
+  // ⛔ The site's not-found page is never made active by its route. No route names it, and on a
+  // site whose parametric page matches `/404` (a root `/:slug`) that route names THAT page, which
+  // then rendered as the active one. It renders with the active page it finds: the Website's
+  // first, through `createPageRenderer` (`start-page.js`), as in the browser.
+  if (page !== website.getNotFoundPage()) website.setActivePage(page.route)
 
   // A page that claims content but yields no blocks has not been loaded — it is
   // not an empty page. `Page#bodyBlocks` returns [] when its sections are absent

package/src/start-page.js

@@ -0,0 +1,26 @@
+/**
+ * The page a Website starts with as active — recorded when the SSR init builds the graph, and put
+ * back before each render (`createPageRenderer`).
+ *
+ * ⭐ It is what the browser has on a URL that names no page. Core makes the site's index page (or
+ * its first page) active when it builds the Website, and neither the boot nor `PageRenderer` makes
+ * the not-found page active, since no route names it.
+ *
+ * ⛔ `renderPage` makes the page it renders active by its route, so for the not-found page it
+ * changes nothing, and that page rendered with whatever page the Website rendered last: on a
+ * Website reused across requests, the previous request's. Anything that adapts to the active page
+ * — a header, a language switcher, a docs sidebar — showed that page.
+ *
+ * A WeakMap rather than a slot on core's sealed Website: it is SSR state, and core is in every site.
+ */
+const startPages = new WeakMap()
+
+/** Remember `website`'s active page as the one it starts with. Call it before anything renders. */
+export function recordStartPage(website) {
+  if (website && !startPages.has(website)) startPages.set(website, website.activePage)
+}
+
+/** Make `website`'s start page active again. A Website the SSR init did not build is left alone. */
+export function restoreStartPage(website) {
+  if (startPages.has(website)) website.activePage = startPages.get(website)
+}