webjsdev
diff --git a/‎.agents/skills/webjs/references/routing-and-pages.md‎
Lines changed: 1 addition & 1 deletion b/‎.agents/skills/webjs/references/routing-and-pages.md‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎AGENTS.md‎
Lines changed: 1 addition & 1 deletion b/‎AGENTS.md‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎packages/server/src/ssr/render.js‎
Lines changed: 44 additions & 17 deletions b/‎packages/server/src/ssr/render.js‎
Lines changed: 44 additions & 17 deletions
diff --git a/‎test/ssr/ssr.test.js‎
Lines changed: 32 additions & 1 deletion b/‎test/ssr/ssr.test.js‎
Lines changed: 32 additions & 1 deletion
@@ -217,7 +217,7 @@ Refusals worth knowing: `formaction=${fn}` is supported on a `<button>` anywhere
 - On the **500 path**, a throwing layout is handled by the next `error.{js,ts}` OUT: the walk tries each boundary in the chain, innermost first, and a layout that throws fails every attempt whose wrapped set contains it, so control ends at `global-error` (or the default 500 page) when they are exhausted.
 - On the **404 / 403 / 401 paths** there is NO outward walk. Each renders the one nearest boundary, so a throwing layout degrades that response to a chrome-less standalone render of the boundary with no boot script, keeping its status. A control-flow throw from a wrapped layout there (an auth-gate layout calling `redirect('/login')`) is discarded rather than honoured, deliberately: the status is already decided and the boundary page is the answer to that request.
 
-A genuine layout crash is reported to `onError` (and to the dev overlay on the 404 / 403 / 401 paths, where nothing else claimed the frame) rather than being swallowed; a control-flow sentinel never is, since it is routing rather than a crash.
+A genuine layout crash is reported to `onError` (and to the dev overlay on the 404 / 403 / 401 paths, where nothing else claimed the frame) rather than being swallowed. Repeats of the SAME cause within one request collapse to a single report, keyed on the error's name, message and throw site, because one shared layout can fail several boundary attempts; two DIFFERENT failures are both reported, including `global-error`'s own. A control-flow sentinel never is, since it is routing rather than a crash.
 
 Two further consequences: a layout that fetches runs its fetch again on a boundary response, and a `<webjs-suspense>` inside a wrapped layout shows its fallback, because a boundary response is buffered so its status is final before the first byte. A 404 for a URL that matched NO route has no chain to wrap in and stays a bare document.
 - Root-only (in `app/` exactly): `global-error.ts` is the app-wide catch-all after nested `error` boundaries are exhausted and renders its OWN `<!doctype><html><body>` (returned verbatim, so keep it static HTML with no components or hydration). That verbatim document is exactly why it is the one boundary left UNWRAPPED: a second shell would nest inside the root layout's, wrapping it would re-run the code that just threw, and with no boot script it could not soft-swap anyway. `global-not-found.ts` renders for an unmatched-anywhere URL when no `not-found` matches.
 
@@ -340,7 +340,7 @@ Default export receives `{ children, params, searchParams, url }`, must embed `c
 
 ### Error / loading / metadata routes
 
-`error.{js,ts}` default-exports `({ error, ...ctx }) => TemplateResult` (catches sibling-page / deeper render errors, innermost wins, prod sends only `error.message`). **A boundary renders INSIDE the layouts at and above its own segment** (#1298), so it carries the keyed `wj:children` pairs and navigating into a failing page is a SOFT navigation with the site chrome and its hydrated state intact; the same holds for `not-found` / `forbidden` / `unauthorized`, which now receive a page-shaped ctx too. A layout deeper than the boundary is not rendered and is not in the boot script, which ships the boundary module instead of the page's. A boundary cannot catch its OWN segment's layout (it renders inside it, Next's `layout -> error -> page` order). On the 500 path a throwing layout falls through to the next `error` boundary OUT, and to `global-error` when the chain is exhausted; the 404 / 403 / 401 paths have no outward walk, so there a throwing layout degrades that one response to a chrome-less standalone render of the boundary (status preserved, no boot script) and a control-flow throw from a wrapped layout is discarded rather than honoured, since the status is already decided. A real layout crash is reported to `onError` instead of vanishing; a sentinel never is. `loading.{js,ts}` wraps the sibling page in `Suspense` with an immediately-flushed fallback. `forbidden.{js,ts}` / `unauthorized.{js,ts}` render the nearest 403 / 401 boundary for a thrown `forbidden()` / `unauthorized()` (#848). Two **root-only** boundaries (`app/` root exactly): `global-error.{js,ts}` is the app-wide catch-all tried after the nested `error` boundaries are exhausted, and it renders its **own** `<!doctype><html><body>` document (returned verbatim, since a root-layout failure is when it fires). It is the sole boundary that is NOT wrapped in layouts: a second shell cannot nest inside the root layout's (invariant 8), wrapping it would re-run the code that just threw, and it ships no boot script anyway. Because it is returned verbatim (no framework `<head>` splice), it ships **no importmap or boot script**, so keep it **static HTML with no components/hydration** (a last-resort page must not depend on the module system that may have just failed); under an opt-in CSP, an inline `<script>` in it must carry the nonce via `cspNonce()` (an inline `<style>` needs one only if you tighten `style-src`, since the default allows inline style outright). `global-not-found.{js,ts}` renders for an unmatched-anywhere URL when no `not-found` matches. `not-found` is nearest-wins from the throwing page's chain (#848 fixed the prior root-only behavior). Metadata routes (`sitemap`, `robots`, `manifest`, `icon`, `apple-icon`, `opengraph-image`, `twitter-image`) live at app root or static segments only and default-export a possibly-async function; `sitemap(entries)` / `sitemapIndex(sitemaps)` from `@webjsdev/server` serialize spec-valid XML. **`icon` / `apple-icon` are auto-LINKED** into the head (`<link rel="icon" href="/icon">`, `<link rel="apple-touch-icon" href="/apple-icon">`, base-path prefixed, no asserted `type` / `sizes` since the route picks its content type at request time), so writing the file is the whole wiring. A declared `metadata.icons` **suppresses** them rather than merging, matching Next's precedence for its static icon files, so an app that outgrows a placeholder route names its real icons instead of deleting it. `opengraph-image` / `twitter-image` are NOT auto-linked (a preview image is a per-page editorial choice): point `metadata.openGraph.images` / `metadata.twitter.images` at them. Declare a favicon through `metadata.icons` or a metadata route, never a hand-written `<link rel="icon">`, since only the root layout may write a shell at all (invariant 8). See `references/routing-and-pages.md`.
+`error.{js,ts}` default-exports `({ error, ...ctx }) => TemplateResult` (catches sibling-page / deeper render errors, innermost wins, prod sends only `error.message`). **A boundary renders INSIDE the layouts at and above its own segment** (#1298), so it carries the keyed `wj:children` pairs and navigating into a failing page is a SOFT navigation with the site chrome and its hydrated state intact; the same holds for `not-found` / `forbidden` / `unauthorized`, which now receive a page-shaped ctx too. A layout deeper than the boundary is not rendered and is not in the boot script, which ships the boundary module instead of the page's. A boundary cannot catch its OWN segment's layout (it renders inside it, Next's `layout -> error -> page` order). On the 500 path a throwing layout falls through to the next `error` boundary OUT, and to `global-error` when the chain is exhausted; the 404 / 403 / 401 paths have no outward walk, so there a throwing layout degrades that one response to a chrome-less standalone render of the boundary (status preserved, no boot script) and a control-flow throw from a wrapped layout is discarded rather than honoured, since the status is already decided. A real layout crash is reported to `onError` instead of vanishing (repeats of the SAME cause within one request collapse to one report, since a shared layout can fail several boundary attempts); a sentinel never is. `loading.{js,ts}` wraps the sibling page in `Suspense` with an immediately-flushed fallback. `forbidden.{js,ts}` / `unauthorized.{js,ts}` render the nearest 403 / 401 boundary for a thrown `forbidden()` / `unauthorized()` (#848). Two **root-only** boundaries (`app/` root exactly): `global-error.{js,ts}` is the app-wide catch-all tried after the nested `error` boundaries are exhausted, and it renders its **own** `<!doctype><html><body>` document (returned verbatim, since a root-layout failure is when it fires). It is the sole boundary that is NOT wrapped in layouts: a second shell cannot nest inside the root layout's (invariant 8), wrapping it would re-run the code that just threw, and it ships no boot script anyway. Because it is returned verbatim (no framework `<head>` splice), it ships **no importmap or boot script**, so keep it **static HTML with no components/hydration** (a last-resort page must not depend on the module system that may have just failed); under an opt-in CSP, an inline `<script>` in it must carry the nonce via `cspNonce()` (an inline `<style>` needs one only if you tighten `style-src`, since the default allows inline style outright). `global-not-found.{js,ts}` renders for an unmatched-anywhere URL when no `not-found` matches. `not-found` is nearest-wins from the throwing page's chain (#848 fixed the prior root-only behavior). Metadata routes (`sitemap`, `robots`, `manifest`, `icon`, `apple-icon`, `opengraph-image`, `twitter-image`) live at app root or static segments only and default-export a possibly-async function; `sitemap(entries)` / `sitemapIndex(sitemaps)` from `@webjsdev/server` serialize spec-valid XML. **`icon` / `apple-icon` are auto-LINKED** into the head (`<link rel="icon" href="/icon">`, `<link rel="apple-touch-icon" href="/apple-icon">`, base-path prefixed, no asserted `type` / `sizes` since the route picks its content type at request time), so writing the file is the whole wiring. A declared `metadata.icons` **suppresses** them rather than merging, matching Next's precedence for its static icon files, so an app that outgrows a placeholder route names its real icons instead of deleting it. `opengraph-image` / `twitter-image` are NOT auto-linked (a preview image is a per-page editorial choice): point `metadata.openGraph.images` / `metadata.twitter.images` at them. Declare a favicon through `metadata.icons` or a metadata route, never a hand-written `<link rel="icon">`, since only the root layout may write a shell at all (invariant 8). See `references/routing-and-pages.md`.
 
 ### Route handlers (`app/**/route.{js,ts}`)
 
 
@@ -414,6 +414,23 @@ async function renderChain(route, ctx, dev, suspenseCtx, have, pageModule) {
   return { html: body + (await loadingTemplates(route, ctx, dev)), reduced: chain.reduced };
 }
 
+/**
+ * A per-request dedup key for a secondary boundary failure: the error's name,
+ * message and throw site. Identity cannot be used, because a layout that
+ * constructs its error yields a fresh object each time it is re-run, and the
+ * whole point is to collapse exactly those repeats while letting a genuinely
+ * different failure through. The first stack frame is the throw site, so two
+ * different layouts raising the same message still read as distinct causes.
+ *
+ * @param {unknown} err
+ * @returns {string}
+ */
+function boundaryErrorKey(err) {
+  if (!(err instanceof Error)) return `raw:${String(err)}`;
+  const site = String(err.stack || '').split('\n')[1] || '';
+  return `${err.name}:${err.message}:${site.trim()}`;
+}
+
 /**
  * Report a throw from a layout wrapped around a boundary page (#1298) to the
  * same sinks a page-render error reaches, then let the caller degrade to the
@@ -435,14 +452,21 @@ async function renderChain(route, ctx, dev, suspenseCtx, have, pageModule) {
  * standalone boundary body, exactly as it does for a real layout crash, and
  * the status the boundary carries is preserved.
  *
- * REPORTED AT MOST ONCE PER REQUEST, via the caller's `once` latch. The 500
- * path tries each boundary in the chain, and a throwing layout that is an
- * ancestor of several of them fails EVERY attempt: `layoutsForBoundary` selects
- * by segment ancestry rather than by boundary depth, so two boundaries at
- * different segments can resolve to the same layout set. Without the latch a
- * root layout that throws is reported once per boundary in the chain. Identity
- * deduplication would not do, because a layout that constructs its error
- * (`throw new Error(...)`) yields a fresh object per attempt.
+ * Deduplicated per request by CAUSE, via the caller's `seen` set. The 500 path
+ * tries each boundary in the chain, and a throwing layout that is an ancestor
+ * of several of them fails EVERY attempt: `layoutsForBoundary` selects by
+ * segment ancestry rather than by boundary depth, so two boundaries at
+ * different segments can resolve to the same layout set. Without dedup a root
+ * layout that throws is reported once per boundary in the chain.
+ *
+ * The key is the error's name, message and throw site rather than its identity,
+ * because a layout that constructs its error (`throw new Error(...)`) yields a
+ * fresh object per attempt. Deduplicating on "any secondary failure already
+ * reported" instead would be wrong in the other direction: an inner boundary
+ * throwing a TypeError would silence a LATER, unrelated root-layout crash, and
+ * would make the `global-error` report below unreachable on every route whose
+ * chain contains a real `error.{js,ts}`, since reaching that block at all means
+ * an earlier attempt already threw. Distinct causes are each reported once.
  *
  * `overlay` says whether this failure may claim the DEV OVERLAY. The overlay
  * holds one retained frame per URL and the dev handler's slot is last-write
@@ -455,13 +479,14 @@ async function renderChain(route, ctx, dev, suspenseCtx, have, pageModule) {
  *
  * @param {unknown} err
  * @param {{ onError?: (e: unknown) => void, onDevError?: (e: unknown) => void }} opts
- * @param {{ what?: string, once?: { reported: boolean }, overlay?: boolean }} [cfg]
+ * @param {{ what?: string, seen?: Set<string>, overlay?: boolean }} [cfg]
  */
 function reportBoundaryLayoutError(err, opts, cfg = {}) {
   if (isRedirect(err) || isNotFound(err) || isForbidden(err) || isUnauthorized(err)) return;
-  if (cfg.once) {
-    if (cfg.once.reported) return;
-    cfg.once.reported = true;
+  if (cfg.seen) {
+    const key = boundaryErrorKey(err);
+    if (cfg.seen.has(key)) return;
+    cfg.seen.add(key);
   }
   const what = cfg.what || 'a layout threw while wrapping a boundary page';
   if (typeof opts.onError === 'function') {
@@ -1070,9 +1095,11 @@ export async function ssrPage(route, params, url, opts) {
     // error page's boot scripts (when moduleUrls is non-empty) and
     // the meta csp-nonce tag both pass strict-CSP enforcement.
     const errNonce = opts.req ? getNonce(opts.req) : undefined;
-    // One latch for the whole 500 path: the walk below, and the global-error
-    // attempt after it, report at most ONE secondary failure between them.
-    const secondary = { reported: false };
+    // One dedup set for the whole 500 path: the walk below and the
+    // global-error attempt after it collapse REPEATS of the same cause (a
+    // shared layout that fails every attempt) while still reporting a
+    // genuinely different failure, including global-error's own.
+    const secondary = new Set();
     // Try nearest error.js (innermost → outermost).
     for (let i = route.errors.length - 1; i >= 0; i--) {
       try {
@@ -1125,7 +1152,7 @@ export async function ssrPage(route, params, url, opts) {
         // a routing decision rather than a crash.
         reportBoundaryLayoutError(nested, opts, {
           what: 'an error boundary or its layout threw while handling a render error',
-          once: secondary,
+          seen: secondary,
           overlay: false,
         });
       }
@@ -1156,7 +1183,7 @@ export async function ssrPage(route, params, url, opts) {
         // that failed.
         reportBoundaryLayoutError(nested, opts, {
           what: 'global-error threw while handling a render error',
-          once: secondary,
+          seen: secondary,
           overlay: false,
         });
       }
 
@@ -2242,11 +2242,16 @@ test('boundary: a broken global-error is reported, not silently swallowed', asyn
   const { route, appDir } = makeBoundaryApp({
     files: {
       'global-error.js': `export default function GE() { throw new Error('global-error-boom'); }\n`,
+      // A REAL error boundary in the chain, which is the shape that matters:
+      // control only reaches global-error because this one threw first, so a
+      // dedup keyed on "any secondary failure already reported" would swallow
+      // global-error's own crash on every route that has an error.ts at all.
+      'error.js': `export default function Err() { throw new Error('boundary-boom'); }\n`,
       'page.js': `export default function Page() { throw new Error('page-boom'); }\n`,
     },
     page: 'page.js',
     layouts: [],
-    errors: [],
+    errors: ['error.js'],
   });
   const seen = [];
   const resp = await SILENT(() => ssrPage(route, {}, new URL('http://localhost/'), {
@@ -2257,9 +2262,35 @@ test('boundary: a broken global-error is reported, not silently swallowed', asyn
   assert.ok(body.includes('Something went wrong'), 'it still degrades to the default 500 page');
   const messages = seen.map((e) => String(e && e.message));
   assert.ok(messages.includes('global-error-boom'), 'the global-error crash reached the sink');
+  assert.ok(messages.includes('boundary-boom'), 'and so did the boundary that failed before it');
   assert.ok(messages.includes('page-boom'), 'alongside the original page error');
 });
 
+test('boundary: dedup collapses REPEATS of one cause, not distinct failures', async () => {
+  // The dedup exists for one layout that fails every attempt. It must not
+  // silence a genuinely different secondary failure: an inner boundary that
+  // throws its own error, then an outer attempt whose layout crashes, are two
+  // causes and both belong in the sink.
+  const { route, appDir } = makeBoundaryApp({
+    files: {
+      'layout.js': `export default function Root() { throw new Error('shared-layout-boom'); }\n`,
+      'error.js': HTML_IMPORT + `export default function Err() { return html\`<p>outer</p>\`; }\n`,
+      'docs/error.js': `export default function Err() { throw new TypeError('inner-boundary-boom'); }\n`,
+      'docs/page.js': `export default function Page() { throw new Error('page-boom'); }\n`,
+    },
+    page: 'docs/page.js',
+    layouts: ['layout.js'],
+    errors: ['error.js', 'docs/error.js'],
+  });
+  const seen = [];
+  await SILENT(() => ssrPage(route, {}, new URL('http://localhost/docs'), {
+    dev: false, appDir, onError: (e) => seen.push(e),
+  }));
+  const messages = seen.map((e) => String(e && e.message));
+  assert.ok(messages.includes('inner-boundary-boom'), 'the inner boundary crash is reported');
+  assert.ok(messages.includes('shared-layout-boom'), 'and the LATER, unrelated layout crash is not swallowed by it');
+});
+
 test('boundary: a boundary response is never storable and never reduced', async () => {
   // Two independent guarantees. The HTML cache refuses a non-200 outright, and
   // the reduced X-Webjs-Have path is structurally unreachable: the boundary