@webjsdev/server 0.8.91 → 0.10.0

package/src/route-report.js

@@ -0,0 +1,130 @@
+/**
+ * What each route costs the browser (#1686).
+ *
+ * A page, layout or boundary never ships; the boot loads the components it
+ * renders, its frontier (`route-frontier.js`). This report runs the same walk
+ * the dev server runs and projects it into a sorted, app-relative,
+ * JSON-serializable object:
+ *
+ *   - `routeModules`: every page, layout and boundary with its kind, the
+ *     component modules the boot imports in its place (`emits`, empty means
+ *     the route loads no JavaScript), and `hints`: code in it that looks meant
+ *     for the browser but runs only on the server (`routeModuleBrowserHints`).
+ *   - `orphans`: a `class X extends WebComponent` with no literal-tag
+ *     registration, either because there is no registration call or because
+ *     the tag is computed. The scanner never sees it (invariant 3 requires a
+ *     literal tag), so it is never booted and never upgrades unless something
+ *     that ships imports it.
+ *
+ * Consumed by `webjs doctor` (`ROUTE_BROWSER_CODE` and `ORPHAN_COMPONENTS`,
+ * which share ONE call so the module graph is built once per run). Advisory
+ * only: it never fails anything.
+ *
+ * Nothing is cached here. Every out-of-process consumer runs the analysis once
+ * and exits, so a cache would never hit and would only add a staleness bug.
+ */
+import { readFile, stat } from 'node:fs/promises';
+import { join, relative, resolve } from 'node:path';
+
+import { buildModuleGraph } from './module-graph.js';
+import { scanComponents, findOrphanComponents } from './component-scanner.js';
+import { buildRouteTable } from './router.js';
+import { routeModuleBrowserHints } from './client-signals.js';
+import { routeFrontiers, routeModuleKinds, leadsToComponent } from './route-frontier.js';
+
+/**
+ * @typedef {'page'|'layout'|'error'|'loading'|'not-found'|'forbidden'|'unauthorized'|'global-not-found'} RouteModuleKind
+ * @typedef {{ file: string, kind: RouteModuleKind, emits: string[], hints: string[] }} RouteModuleRow
+ * @typedef {{ file: string, className: string }} OrphanRow
+ * @typedef {{ routeModules: number, zeroJs: number, carriers: number, orphans: number }} RouteReportSummary
+ * @typedef {{ analysed: boolean, skipped: 'no-app'|'unanalysable'|null, routeModules: RouteModuleRow[], orphans: OrphanRow[], summary: RouteReportSummary }} RouteReport
+ */
+
+/**
+ * @param {string} appDir
+ * @returns {Promise<RouteReport>}
+ */
+export async function analyzeRouteModules(appDir) {
+  // Every path the analysis compares is absolute, so a relative app dir would
+  // match nothing and report empty frontiers.
+  appDir = resolve(appDir);
+  // No `app/` means this is not a routable app (a bare component library, a
+  // lib-only fixture); there is nothing to report on.
+  if (!(await pathExists(join(appDir, 'app')))) return empty('no-app');
+
+  let moduleGraph, components, routeTable, orphans;
+  try {
+    moduleGraph = await buildModuleGraph(appDir);
+    components = await scanComponents(appDir);
+    routeTable = await buildRouteTable(appDir);
+    orphans = await findOrphanComponents(appDir);
+  } catch {
+    // A malformed app the analysis cannot process degrades to no report (the
+    // dev server and `webjs check` surface the real problem).
+    return empty('unanalysable');
+  }
+
+  const rel = (/** @type {string} */ f) => relative(appDir, f) || f;
+  const byFile = (/** @type {{ file: string }} */ a, /** @type {{ file: string }} */ b) => a.file.localeCompare(b.file);
+
+  // The same frontier walk the dev server runs, so `emits` is exactly what the
+  // boot imports in each route module's place.
+  const kinds = routeModuleKinds(routeTable);
+  const routeFiles = new Set(kinds.keys());
+  const componentFileSet = new Set(components.map((c) => c.file));
+  const frontiers = routeFrontiers([...routeFiles], moduleGraph, componentFileSet, routeFiles);
+  const carriesComponent = leadsToComponent(moduleGraph, componentFileSet);
+  /** @type {RouteModuleRow[]} */
+  const routeRows = [];
+  for (const [f, kind] of kinds) {
+    /** @type {string[]} */
+    let hints = [];
+    try {
+      hints = routeModuleBrowserHints(await readFile(f, 'utf8'), {
+        file: f, appDir, isComponent: (abs) => componentFileSet.has(abs), carriesComponent,
+      });
+    } catch { /* unreadable: no advice */ }
+    routeRows.push({
+      file: rel(f),
+      kind,
+      emits: (frontiers.get(f) || []).map(rel).sort(),
+      hints,
+    });
+  }
+  routeRows.sort(byFile);
+
+  /** @type {OrphanRow[]} */
+  const orphanRows = orphans
+    .map((o) => ({ file: rel(o.file), className: o.className }))
+    .sort((a, b) => byFile(a, b) || a.className.localeCompare(b.className));
+
+  return {
+    analysed: true, skipped: null,
+    routeModules: routeRows, orphans: orphanRows,
+    summary: {
+      routeModules: routeRows.length,
+      zeroJs: routeRows.filter((r) => r.emits.length === 0).length,
+      carriers: routeRows.filter((r) => r.emits.length > 0).length,
+      orphans: orphanRows.length,
+    },
+  };
+}
+
+/**
+ * The empty report, naming WHY nothing was analysed so a machine consumer can
+ * tell "this is not an app" from "the analysis could not run".
+ * @param {'no-app'|'unanalysable'} skipped
+ * @returns {RouteReport}
+ */
+function empty(skipped) {
+  return {
+    analysed: false, skipped,
+    routeModules: [], orphans: [],
+    summary: { routeModules: 0, zeroJs: 0, carriers: 0, orphans: 0 },
+  };
+}
+
+/** @param {string} p @returns {Promise<boolean>} */
+async function pathExists(p) {
+  try { await stat(p); return true; } catch { return false; }
+}

package/src/router.js

@@ -6,6 +6,7 @@ import { findInstrumentationClient } from './instrumentation.js';
  * @typedef {{
  *   pattern: RegExp,
  *   paramNames: string[],
+ *   paramKinds?: ParamKind[],
  *   file: string,
  *   routeDir: string,
  *   layouts: string[],
@@ -37,6 +38,8 @@ import { findInstrumentationClient } from './instrumentation.js';
  *   globalNotFound: string | null,
  *   metadataRoutes: MetadataRoute[],
  *   instrumentationClient: string | null,
+ *   conflicts: { page: string, route: string, url: string }[],
+ *   ignoredJsx: string[],
  *   appDir: string
  * }} RouteTable
  */
@@ -96,6 +99,8 @@ export async function buildRouteTable(appDir) {
   let globalNotFound = null;
   /** @type {MetadataRoute[]} */
   const metadataRoutes = [];
+  /** @type {string[]} */
+  const ignoredJsx = [];
 
   /** @type {Set<string>} */
   const METADATA_STEMS = new Set(['sitemap', 'robots', 'manifest', 'icon', 'apple-icon', 'opengraph-image', 'twitter-image']);
@@ -131,16 +136,25 @@ export async function buildRouteTable(appDir) {
       }
     }
 
+    // A routing file written as `.tsx` / `.jsx` (Next's default) is never a
+    // route here: JSX needs a build. Recorded so validateAppLayout refuses it
+    // loudly instead of the route silently not existing.
+    {
+      const jsx = /^([A-Za-z0-9_.-]+)\.(?:tsx|jsx)$/.exec(base);
+      if (jsx && ROUTING_STEMS.has(jsx[1])) { ignoredJsx.push(file); continue; }
+    }
+
     // Match `<name>.<js|mjs|ts|mts>` conventions. Stem is the name without ext.
     const stem = stemOf(base);
     if (!stem) continue;
 
     if (stem === 'page') {
       const segs = dir === '.' ? [] : dir.split('/');
-      const { pattern, paramNames, isCatchAll } = segmentsToPattern(segs);
+      const { pattern, paramNames, paramKinds, isCatchAll } = segmentsToPattern(segs);
       pages.push({
         pattern,
         paramNames,
+        paramKinds,
         file,
         routeDir: dir,
         layouts: [],
@@ -182,8 +196,8 @@ export async function buildRouteTable(appDir) {
     } else if (stem === 'route') {
       // route.js / route.ts can live anywhere under app/ (matches NextJs).
       const segs = dir === '.' ? [] : dir.split('/');
-      const { pattern, paramNames } = segmentsToPattern(segs);
-      apis.push({ pattern, paramNames, file, routeDir: dir, middlewares: [] });
+      const { pattern, paramNames, paramKinds } = segmentsToPattern(segs);
+      apis.push({ pattern, paramNames, paramKinds, file, routeDir: dir, middlewares: [] });
     }
   }
 
@@ -221,7 +235,21 @@ export async function buildRouteTable(appDir) {
   // the entry, which inverted the pin-is-a-superset invariant. Deriving it in
   // the one place that builds the table makes that class of miss impossible.
   const instrumentationClient = await findInstrumentationClient(appDir);
-  return { pages, apis, notFound, notFounds, globalError, globalNotFound, metadataRoutes, instrumentationClient, appDir };
+  // A page and a route handler answering the same URL (Next refuses this as
+  // "Conflicting route and page"). Compared by the compiled pattern, so a
+  // route group (`app/(a)/x/page.ts` beside `app/x/route.ts`) conflicts too.
+  // validateAppLayout turns each into a boot error and a check violation.
+  /** @type {{ page: string, route: string, url: string }[]} */
+  const conflicts = [];
+  const pageBySource = new Map(pages.map((p) => [p.pattern.source, p]));
+  for (const api of apis) {
+    const page = pageBySource.get(api.pattern.source);
+    if (page) {
+      const a = /** @type any */ (api);
+      conflicts.push({ page: page.file, route: api.file, url: '/' + urlSegmentsOf(a.routeDir).join('/') });
+    }
+  }
+  return { pages, apis, notFound, notFounds, globalError, globalNotFound, metadataRoutes, instrumentationClient, conflicts, ignoredJsx, appDir };
 }
 
 /**
@@ -263,6 +291,13 @@ export function staticMetadataFile(base) {
   return null;
 }
 
+/** Every routing-file stem, for spotting one written as `.tsx` / `.jsx`. */
+const ROUTING_STEMS = new Set([
+  'page', 'layout', 'route', 'error', 'loading', 'not-found', 'forbidden', 'unauthorized',
+  'global-error', 'global-not-found', 'middleware', 'template', 'default',
+  'sitemap', 'robots', 'manifest', 'icon', 'apple-icon', 'opengraph-image', 'twitter-image',
+]);
+
 function stemOf(base) {
   const m = /^([A-Za-z0-9_.-]+)\.(?:m?[jt]s)$/.exec(base);
   return m ? m[1] : null;
@@ -354,6 +389,8 @@ export function compareSpecificity(a, b) {
  */
 function segmentsToPattern(segments, prefix = '') {
   const paramNames = [];
+  /** @type {ParamKind[]} parallel to paramNames */
+  const paramKinds = [];
   let isCatchAll = false;
   let isOptionalCatchAll = false;
   const parts = segments
@@ -362,17 +399,22 @@ function segmentsToPattern(segments, prefix = '') {
       // Optional catch-all: [[...slug]] matches with AND without params
       if (seg.startsWith('[[...') && seg.endsWith(']]')) {
         paramNames.push(seg.slice(5, -2));
+        paramKinds.push('optional');
         isCatchAll = true;
         isOptionalCatchAll = true;
         return '(.*)';
       }
       if (seg.startsWith('[...') && seg.endsWith(']')) {
         paramNames.push(seg.slice(4, -1));
+        paramKinds.push('catchall');
         isCatchAll = true;
-        return '(.*)';
+        // At least one character: a required catch-all never matches its
+        // empty base (`/docs` is a 404 for `docs/[...slug]`, as in Next).
+        return '(.+)';
       }
       if (seg.startsWith('[') && seg.endsWith(']')) {
         paramNames.push(seg.slice(1, -1));
+        paramKinds.push('single');
         return '([^/]+)';
       }
       return escapeRe(seg);
@@ -387,9 +429,44 @@ function segmentsToPattern(segments, prefix = '') {
   const pattern = new RegExp(`^${escapeRe(prefix)}${regexBody}${isOptionalCatchAll ? suffix : '/?$'}`);
   if (!isOptionalCatchAll) {
     // Standard pattern needs end anchor
-    return { pattern: new RegExp(`^${escapeRe(prefix)}${body}/?$`), paramNames, isCatchAll };
+    return { pattern: new RegExp(`^${escapeRe(prefix)}${body}/?$`), paramNames, paramKinds, isCatchAll };
   }
-  return { pattern, paramNames, isCatchAll };
+  return { pattern, paramNames, paramKinds, isCatchAll };
+}
+
+/** @typedef {'single' | 'catchall' | 'optional'} ParamKind */
+
+/** @param {string} s */
+function safeDecode(s) {
+  try { return decodeURIComponent(s); } catch { return s; }
+}
+
+/**
+ * Build a route's params from a pattern match, Next.js style: a dynamic
+ * `[id]` is a string, a catch-all `[...slug]` is a `string[]` (the tail split
+ * on `/`, then each piece decoded), and an EMPTY optional catch-all
+ * `[[...slug]]` omits its key entirely. Returns null when a required
+ * catch-all came back empty (no match).
+ * @param {{ paramNames: string[], paramKinds?: ParamKind[] }} route
+ * @param {RegExpExecArray} m
+ * @returns {Record<string, string | string[]> | null}
+ */
+export function fillParams(route, m) {
+  /** @type {Record<string, string | string[]>} */
+  const params = {};
+  for (let i = 0; i < route.paramNames.length; i++) {
+    const name = route.paramNames[i];
+    const kind = route.paramKinds ? route.paramKinds[i] : 'single';
+    const raw = m[i + 1] || '';
+    if (kind === 'single') { params[name] = safeDecode(raw); continue; }
+    const pieces = raw.replace(/\/+$/, '').split('/').filter((p, j, all) => p !== '' || (j > 0 && j < all.length - 1)).map(safeDecode);
+    if (!pieces.length) {
+      if (kind === 'catchall') return null;
+      continue; // empty optional catch-all: the key is absent, as in Next
+    }
+    params[name] = pieces;
+  }
+  return params;
 }
 
 /** @param {string} s */
@@ -405,9 +482,8 @@ export function matchPage(table, pathname) {
   for (const route of table.pages) {
     const m = route.pattern.exec(pathname);
     if (!m) continue;
-    /** @type {Record<string,string>} */
-    const params = {};
-    route.paramNames.forEach((n, i) => (params[n] = decodeURIComponent(m[i + 1] || '')));
+    const params = fillParams(route, m);
+    if (!params) continue;
     return { route, params };
   }
   return null;
@@ -421,10 +497,41 @@ export function matchApi(table, pathname) {
   for (const route of table.apis) {
     const m = route.pattern.exec(pathname);
     if (!m) continue;
-    /** @type {Record<string,string>} */
-    const params = {};
-    route.paramNames.forEach((n, i) => (params[n] = decodeURIComponent(m[i + 1] || '')));
+    const params = fillParams(route, m);
+    if (!params) continue;
     return { route, params };
   }
   return null;
 }
+
+/**
+ * The URL paths of every STATIC page route in a route table, sorted and
+ * deduped. A DYNAMIC route is excluded rather than guessed at: listing it would
+ * mean inventing param values. A route group `(group)` and a `_private` segment
+ * drop out of the URL, and the root `.` is `/`.
+ *
+ * @param {{ pages?: Array<{ routeDir?: string, paramNames?: string[] }> } | undefined} table  a `buildRouteTable(appDir)` result
+ * @returns {string[]}
+ */
+export function staticPageRoutes(table) {
+  const out = new Set();
+  for (const r of table?.pages || []) {
+    if (r.paramNames && r.paramNames.length) continue;
+    out.add(staticRoutePath(r.routeDir));
+  }
+  return [...out].sort();
+}
+
+/**
+ * `blog` -> `/blog`, the root `.` -> `/`. Route groups and `_private` segments
+ * drop, the same normalization `buildRouteTable` uses for matching.
+ * @param {string|undefined} routeDir
+ * @returns {string}
+ */
+function staticRoutePath(routeDir) {
+  if (!routeDir || routeDir === '.') return '/';
+  const segs = routeDir
+    .split('/')
+    .filter((s) => !(s.startsWith('(') && s.endsWith(')')) && !s.startsWith('_'));
+  return segs.length ? '/' + segs.join('/') : '/';
+}

package/src/session.js

@@ -21,8 +21,9 @@
  */
 
 import { getStore } from './cache.js';
-import { markDynamicAccess } from './context.js';
+import { markDynamicAccess, getRequest } from './context.js';
 import { shared } from './process-shared.js';
+import { devSecret } from './dev-secret.js';
 
 // -- Web Crypto helpers ------------------------------------------------------
 // Same shape as auth.js. We duplicate here rather than share a module
@@ -104,10 +105,20 @@ export class Session {
     };
   }
 
-  /** @param {string} key @returns {unknown} */
+  /**
+   * A value, or a flash value, which reading consumes (Remix's semantics): the
+   * next save drops it, so a "shown once" message is shown once. It used to be
+   * kept and re-serialized on every save, so it never went away.
+   * @param {string} key @returns {unknown}
+   */
   get(key) {
     if (this.#destroyed) return undefined;
-    return this.#data.get(key) ?? this.#flash.get(key);
+    if (this.#data.has(key)) return this.#data.get(key);
+    if (!this.#flash.has(key)) return undefined;
+    const value = this.#flash.get(key);
+    this.#flash.delete(key);
+    this.#dirty = true;
+    return value;
   }
 
   /** @param {string} key @param {unknown} value */
@@ -132,7 +143,8 @@ export class Session {
   }
 
   /**
-   * Set a value that exists for one request only.
+   * Set a value that lasts until the next `get()` of it, as in Remix: flash it
+   * in an action, read it once on the page the redirect lands on.
    * @param {string} key @param {unknown} value
    */
   flash(key, value) {
@@ -316,8 +328,16 @@ const sessionMap = shared('session-map', () => new WeakMap());
  * }} [opts]
  */
 export function session(opts = {}) {
-  const secret = opts.secret || process.env.SESSION_SECRET;
-  if (!secret) throw new Error('session() requires secret option or SESSION_SECRET env var');
+  // In development and tests a missing secret falls back to a generated one
+  // kept in .webjs/dev-secret (dev-secret.js), so a fresh clone or worktree works.
+  const secret = opts.secret || process.env.SESSION_SECRET || devSecret('SESSION_SECRET');
+  if (!secret) {
+    throw new Error(
+      'session() needs a secret to sign its cookie: set SESSION_SECRET in .env (webjs create writes one; '
+      + 'generate another with node -e "console.log(require(\'crypto\').randomBytes(32).toString(\'hex\'))") '
+      + 'or pass session({ secret }). Only a development or test process (NODE_ENV=development or test) gets a generated one.',
+    );
+  }
 
   const storage = opts.storage || cookieSessionStorage();
   const cookieName = opts.cookieName || 'webjs.sid';
@@ -365,20 +385,22 @@ export function session(opts = {}) {
 // ---------------------------------------------------------------------------
 
 /**
- * Get the Session for the current request.
+ * Get the Session for the current request. With no argument it reads the
+ * request in scope, the way `cookies()` and `headers()` do, so a page, action
+ * or route handler calls `getSession()`; passing `getRequest()` works too.
  *
  * ```js
- * const s = getSession(req);
+ * const s = getSession();
  * s.get('userId');
  * s.set('userId', user.id);
  * s.flash('message', 'Saved!');
  * ```
  *
- * @param {Request} req
+ * @param {Request | null} [req]  defaults to the request in scope
  * @returns {Session}
  */
 export function getSession(req) {
-  const s = sessionMap.get(req);
+  const s = sessionMap.get(req ?? /** @type {Request} */ (getRequest()));
   if (!s) throw new Error('getSession() called outside of session middleware');
   // A session read is per-user, so mark the request dynamic so the server HTML
   // cache excludes it even when the page declared `revalidate` (#241).

package/src/ssr/client-router-flag.js

@@ -8,7 +8,7 @@
  * `window.__WEBJS_CLIENT_ROUTER__=false` flag BEFORE the deferred boot module
  * so the bundle's module-end auto-enable skips.
  *
- * A module-level switch (mirroring `setBasePath` / `setElisionFingerprint`) so
+ * A module-level switch (mirroring `setBasePath` / `setServeFingerprint`) so
  * no opt has to thread through every render path. Default true keeps every
  * existing app and test byte-identical.
  *

package/src/ssr/document.js

@@ -1,4 +1,4 @@
-import { collectHoistedHeadTags, hoistHeadTags, wrapHead } from './head.js';
+import { collectHoistedHeadTags, hoistHeadTags, hoistOwnedStylesheets, stylesheetKeys, wrapHead } from './head.js';
 
 /**
  * Derive a layout's segment path from its file path. The path identifies
@@ -150,7 +150,9 @@ export function regionRouteKey(segmentPath, params) {
   const p = params || {};
   /** Encode one substituted value, per slash-piece (catch-alls keep their
    *  literal separators; each piece is comment-safe + delimiter-safe). */
-  const enc = (v) => String(v).split('/').map((s) => encodeURIComponent(s)).join('/');
+  const enc = (v) => (Array.isArray(v) ? v.join('/') : String(v)).split('/').map((s) => encodeURIComponent(s)).join('/');
+  /** A catch-all value present and non-empty (a string[] since Next parity). */
+  const has = (v) => (Array.isArray(v) ? v.length > 0 : !!v);
   /** A STATIC piece is a folder name emitted as-is EXCEPT the boundary/header
    *  delimiter characters (':' would mis-split the `segment:route-key` parses,
    *  ',' the have-entry list, '%' the decode); percent-encode just those so
@@ -166,12 +168,12 @@ export function regionRouteKey(segmentPath, params) {
     // the already-slash-joined tail (may be '' for an empty optional one).
     if (seg.startsWith('[[...') && seg.endsWith(']]')) {
       const v = p[seg.slice(5, -2)];
-      if (v) out.push(enc(v));
+      if (has(v)) out.push(enc(v));
       continue;
     }
     if (seg.startsWith('[...') && seg.endsWith(']')) {
       const v = p[seg.slice(4, -1)];
-      if (v) out.push(enc(v));
+      if (has(v)) out.push(enc(v));
       continue;
     }
     // Dynamic `[name]`.
@@ -213,14 +215,14 @@ export function regionRouteKey(segmentPath, params) {
  */
 export function wrapWithChildrenMarker(tree, segmentPath, params) {
   const routeKey = regionRouteKey(segmentPath, params);
-  return {
-    _$webjs: 'template',
-    strings: [
-      `<!--wj:children:${segmentPath}:${routeKey}-->`,
-      `<!--/wj:children:${segmentPath}-->`,
-    ],
-    values: [tree],
-  };
+  const strings = [
+    `<!--wj:children:${segmentPath}:${routeKey}-->`,
+    `<!--/wj:children:${segmentPath}-->`,
+  ];
+  // `raw` marks the strings as the framework's own markup, which is what the
+  // renderers require of a template result (a tagged template's strings have it).
+  Object.defineProperty(strings, 'raw', { value: strings.slice() });
+  return { _$webjs: 'template', strings, values: [tree] };
 }
 
 /** Internal helpers re-exported for unit testing. */
@@ -286,6 +288,28 @@ export function extractUserShell(body) {
 /** Re-export for unit testing. */
 export const _extractUserShell = extractUserShell;
 
+/**
+ * The root layout's `<html>` / `<body>` attributes with a list of their names
+ * appended (`data-wj-html="lang class"`), so the client router can bring
+ * exactly those attributes up to date after a soft navigation or a form
+ * submission and leave alone any a script set in the browser (#1686). A
+ * changed theme cookie then shows without a reload, as it does in Next.js.
+ * @param {string} attrs the raw attribute text from the layout's tag
+ * @param {string} mark
+ * @returns {string}
+ */
+export function markRootAttrs(attrs, mark) {
+  const re = /([^\s=/>"']+)(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+))?/g;
+  /** @type {string[]} */
+  const list = [];
+  let m;
+  while ((m = re.exec(attrs))) {
+    const n = m[1].toLowerCase();
+    if (n !== mark && !list.includes(n)) list.push(n);
+  }
+  return `${attrs} ${mark}="${list.join(' ')}"`;
+}
+
 /**
  * Inner-only variant of wrapHead: returns just the meta/title/link/script
  * tags that should live INSIDE <head>, without the surrounding
@@ -331,19 +355,27 @@ export function buildDocumentParts(body, wrapOpts) {
   if (shell) {
     const headInner = buildHeadInner(wrapOpts);
     const hoist = collectHoistedHeadTags(shell.userBody);
-    const composedHead = [headInner, shell.userHead.trim(), hoist.tags.join('\n')]
+    const rootHead = [headInner, shell.userHead.trim(), hoist.tags.join('\n')]
       .filter(Boolean)
       .join('\n');
+    // A nested layout's or page's leading stylesheets join the head after the
+    // root's, so the cascade reads root to leaf (#1669).
+    const owned = hoistOwnedStylesheets(hoist.body, stylesheetKeys(rootHead, wrapOpts.pageUrl), wrapOpts.pageUrl);
+    const composedHead = [rootHead, owned.tags.join('\n')].filter(Boolean).join('\n');
     const prefix =
-      `<!doctype html>\n<html${shell.htmlAttrs}>\n<head${shell.headAttrs}>\n` +
+      `<!doctype html>\n<html${markRootAttrs(shell.htmlAttrs, 'data-wj-html')}>\n<head${shell.headAttrs}>\n` +
       composedHead +
-      `\n</head>\n<body${shell.bodyAttrs}>\n`;
-    return { prefix, streamBody: hoist.body, closer: `\n</body>\n</html>` };
+      `\n</head>\n<body${markRootAttrs(shell.bodyAttrs, 'data-wj-body')}>\n`;
+    return { prefix, streamBody: owned.body, closer: `\n</body>\n</html>` };
   }
   // No user shell: framework owns the wrapper.
   const headHtml = wrapHead(wrapOpts);
   const { head, body: bodyOut } = hoistHeadTags(headHtml, body);
-  return { prefix: head, streamBody: bodyOut, closer: `\n</body>\n</html>` };
+  const owned = hoistOwnedStylesheets(bodyOut, stylesheetKeys(head, wrapOpts.pageUrl), wrapOpts.pageUrl);
+  const prefix = owned.tags.length
+    ? head.replace('</head>', () => owned.tags.join('\n') + '\n</head>')
+    : head;
+  return { prefix, streamBody: owned.body, closer: `\n</body>\n</html>` };
 }
 
 /** Re-export for unit testing. */