From a81bfeed03c025ae2cb77d4a03a5bc1613c6bbdd Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Mon, 10 Aug 2026 21:24:06 +0530
Subject: [PATCH 1/2] feat(server): auto-link app/icon and app/apple-icon
 metadata routes

An icon metadata route served its bytes and nothing referenced them, so
the file every other framework treats as "this is my favicon" produced a
blank tab with no diagnostic. Next links its static icon files; WebJs
shipped the Next-shaped file convention and the Next-shaped config object
and left the two unconnected, which is a trap for anyone arriving with
that muscle memory. It cost the gallery two PRs to notice.

With no metadata.icons declared, app/icon.* and app/apple-icon.* now emit
their link. The href carries basePath, because the listener strips the
prefix before matching and that is where the route answers. No type or
sizes is asserted: the route picks its content type at request time,
which is the reason to use one, so declaring a type here could
contradict the bytes.

A declared metadata.icons SUPPRESSES the routes rather than merging with
them, which is Next's precedence for its static icon files. An author who
names their icons has said which ones they want, and the route is often a
placeholder the app has outgrown.

Bound from the route table at boot and on each rebuild, the
setClientRouterEnabled shape, so no opt threads through every render
path and adding or deleting the file takes effect live.
---
 .../webjs/references/routing-and-pages.md     |  23 ++-
 AGENTS.md                                     |   2 +-
 packages/server/src/dev.js                    |  10 +-
 packages/server/src/ssr.js                    |  67 +++++++-
 test/bun/metadata-icon-routes.mjs             | 151 ++++++++++++++++++
 test/ssr/ssr.test.js                          |  63 +++++++-
 website/app/docs/metadata-routes/page.ts      |  28 ++++
 7 files changed, 336 insertions(+), 8 deletions(-)
 create mode 100644 test/bun/metadata-icon-routes.mjs

diff --git a/.agents/skills/webjs/references/routing-and-pages.md b/.agents/skills/webjs/references/routing-and-pages.md
index 0512c1300..baa4d1583 100644
--- a/.agents/skills/webjs/references/routing-and-pages.md
+++ b/.agents/skills/webjs/references/routing-and-pages.md
@@ -192,7 +192,28 @@ Refusals worth knowing: `formaction=${fn}` is supported on a `<button>` anywhere
 
 Metadata routes (`sitemap.ts`, `robots.ts`, `manifest.ts`, `icon.ts`, `apple-icon.ts`, `opengraph-image.ts`, `twitter-image.ts`) live at app root or static segments and default-export a possibly-async function; `sitemap()` / `sitemapIndex()` from `@webjsdev/server` serialize spec-valid XML.
 
-The IMAGE metadata routes (`icon`, `apple-icon`, `opengraph-image`, `twitter-image`) default-export a function returning a `Response` with an explicit `content-type`, so an inline SVG needs no asset file (buildless). Then point `metadata` at the route via `openGraph.images` / `twitter.images` / `icons` (or drop a static file in `public/` instead).
+The IMAGE metadata routes (`icon`, `apple-icon`, `opengraph-image`, `twitter-image`) default-export a function returning a `Response` with an explicit `content-type`, so an inline SVG needs no asset file (buildless).
+
+**`icon` and `apple-icon` are LINKED for you.** An app that declares no `metadata.icons` gets `<link rel="icon" href="/icon">` and `<link rel="apple-touch-icon" href="/apple-icon">` in the head automatically, for whichever of the two routes it defines (base-path prefixed, since that is where the route answers). No `type` or `sizes` is asserted, because the route picks its content type at request time and the browser sniffs the served one.
+
+Declaring `metadata.icons` **suppresses** the routes rather than merging with them, which is what Next does with its static icon files. So an app that outgrows a placeholder `app/icon.ts` names its real icons and the route stops being linked without having to be deleted:
+
+```ts
+// app/layout.ts  ->  these win; /icon and /apple-icon are no longer linked
+export const metadata = {
+  icons: {
+    icon: [
+      { url: '/public/favicon-192.png', type: 'image/png', sizes: '192x192' },
+      { url: '/public/favicon.svg', type: 'image/svg+xml', sizes: 'any' },
+    ],
+    apple: { url: '/public/apple-touch-icon.png', sizes: '180x180' },
+  },
+};
+```
+
+Declare a favicon through `metadata.icons` (or a metadata route), never as a hand-written `<link rel="icon">`: only the root layout may write a shell at all (invariant 8), so a hand-written tag is unavailable to every other layout. A `public/favicon.ico` needs no declaration either way, since the framework serves it at the origin root for crawlers that read no markup.
+
+`opengraph-image` and `twitter-image` are NOT auto-linked (a preview image is a per-page editorial choice, not a site-wide default). Point `metadata` at those via `openGraph.images` / `twitter.images`.
 
 ```ts
 // app/opengraph-image.ts  (OG is 1200x630; apple-icon 180x180)
diff --git a/AGENTS.md b/AGENTS.md
index 93f0a759d..22167b637 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -305,7 +305,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`). `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). 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.
+`error.{js,ts}` default-exports `({ error, ...ctx }) => TemplateResult` (catches sibling-page / deeper render errors, innermost wins, prod sends only `error.message`). `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). 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}`)
 
diff --git a/packages/server/src/dev.js b/packages/server/src/dev.js
index 3cbe33ff0..a681396c6 100644
--- a/packages/server/src/dev.js
+++ b/packages/server/src/dev.js
@@ -14,7 +14,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { buildRouteTable, matchPage, matchApi } from './router.js';
 import { generateRouteTypes } from './route-types.js';
-import { ssrPage, ssrNotFound, setClientRouterEnabled } from './ssr.js';
+import { ssrPage, ssrNotFound, setClientRouterEnabled, setMetadataIconRoutes } from './ssr.js';
 import { runFormAction, reportFormSubmittedAsGet } from './form-dispatch.js';
 import { handleApi } from './api.js';
 import {
@@ -742,6 +742,12 @@ export async function createRequestHandler(opts) {
   // like env.js / readiness.js), not a router stem. Resolve it once and stash it
   // on the route table so ssrOpts + the browser-servable gate reach it uniformly.
   routeTable.instrumentationClient = await findInstrumentationClient(appDir);
+  // Auto-linked favicons: tell the head builder which icon metadata routes
+  // exist, so `app/icon.*` is linked when the app declares no metadata.icons.
+  // Bound here rather than threaded through ssrOpts, matching
+  // setClientRouterEnabled; re-bound in doRebuild so adding or deleting the
+  // file takes effect without a restart.
+  setMetadataIconRoutes(routeTable.metadataRoutes);
 
   // Emit `.webjs/routes.d.ts` (typed Route union + per-route params, #258) in
   // dev so an editor's tsserver always has up-to-date route types without the
@@ -1207,6 +1213,8 @@ export async function createRequestHandler(opts) {
     // it so routing reflects added/removed route files immediately.
     state.routeTable = await buildRouteTable(appDir);
     state.routeTable.instrumentationClient = await findInstrumentationClient(appDir);
+    // Adding or deleting app/icon.* changes whether the head auto-links it.
+    setMetadataIconRoutes(state.routeTable.metadataRoutes);
     // Refresh the generated route types (#258) so adding/removing a route file
     // updates `.webjs/routes.d.ts` without a manual `webjs types`. Dev only,
     // best-effort (see emitRouteTypes).
diff --git a/packages/server/src/ssr.js b/packages/server/src/ssr.js
index d69feb635..53100b248 100644
--- a/packages/server/src/ssr.js
+++ b/packages/server/src/ssr.js
@@ -1360,6 +1360,54 @@ let _clientRouterEnabled = true;
 export function setClientRouterEnabled(enabled) { _clientRouterEnabled = enabled !== false; }
 function clientRouterEnabled() { return _clientRouterEnabled; }
 
+// Which icon metadata ROUTES the app has (`app/icon.*`, `app/apple-icon.*`).
+// Set at boot and on each route rebuild from the route table, the same shape
+// as setClientRouterEnabled above, so no opt has to thread through every
+// render path. Empty by default, which keeps an app that declares its icons
+// (or has neither route) byte-identical.
+/** @type {{ icon: boolean, apple: boolean }} */
+let _metadataIconRoutes = { icon: false, apple: false };
+
+/**
+ * Record the icon metadata routes the app defines.
+ *
+ * @param {Iterable<{ stem: string }> | null | undefined} metadataRoutes
+ *   The route table's `metadataRoutes`, or nullish to clear.
+ */
+export function setMetadataIconRoutes(metadataRoutes) {
+  const stems = new Set();
+  for (const r of metadataRoutes || []) if (r && r.stem) stems.add(r.stem);
+  _metadataIconRoutes = { icon: stems.has('icon'), apple: stems.has('apple-icon') };
+}
+
+/**
+ * The implicit `metadata.icons` an app's icon routes stand for, or null when
+ * it has none. Base-path prefixed, because that is where the routes are
+ * SERVED: the listener strips the base path before matching, so under
+ * `webjs.basePath` the route answers at `<basePath>/icon`. A user-authored
+ * `icons` URL is deliberately left alone (it may be cross-origin, and the
+ * author writes the path they mean), so only these framework-emitted ones
+ * are prefixed.
+ *
+ * No `type` or `sizes` is emitted. A metadata route picks its own content
+ * type at request time, which is the reason to use one, so declaring a type
+ * here could contradict the bytes; and `sizes` is unknowable without reading
+ * the response. Both are optional in HTML, and a browser sniffs the served
+ * content type.
+ *
+ * @returns {{ icon?: string, apple?: string } | null}
+ */
+function autoMetadataRouteIcons() {
+  const { icon, apple } = _metadataIconRoutes;
+  if (!icon && !apple) return null;
+  const bp = basePath();
+  /** @type {{ icon?: string, apple?: string }} */
+  const out = {};
+  if (icon) out.icon = withBasePath('/icon', bp);
+  if (apple) out.apple = withBasePath('/apple-icon', bp);
+  return out;
+}
+
 function wrapHead(opts) {
   // CSP nonce: if provided, all inline <script> tags get nonce="…" so they
   // pass strict Content-Security-Policy headers. The nonce is extracted from
@@ -1837,10 +1885,21 @@ function wrapHead(opts) {
   //   - apple   → <link rel="apple-touch-icon">
   //   - shortcut→ <link rel="shortcut icon">
   //   - other   → <link rel="…" href="…"> using the entry's `rel` field
-  if (m.icons) {
-    const buckets = typeof m.icons === 'string' || Array.isArray(m.icons)
-      ? { icon: m.icons }
-      : m.icons;
+  //
+  // With no `icons` declared, an `app/icon.*` / `app/apple-icon.*` metadata
+  // ROUTE is linked automatically (Next parity). Those routes served their
+  // bytes and nothing referenced them before, so writing the file that every
+  // other framework treats as "this is my favicon" produced a blank tab and no
+  // diagnostic. A declared `icons` SUPPRESSES the routes rather than merging
+  // with them, which is also what Next does: it merges static icon files only
+  // when the resolved metadata has no `icons` of its own. Suppressing matters
+  // here because the file is frequently a placeholder an app has outgrown, and
+  // an author who names their icons has said which ones they want.
+  const declaredOrRouteIcons = m.icons || autoMetadataRouteIcons();
+  if (declaredOrRouteIcons) {
+    const buckets = typeof declaredOrRouteIcons === 'string' || Array.isArray(declaredOrRouteIcons)
+      ? { icon: declaredOrRouteIcons }
+      : declaredOrRouteIcons;
     /** @param {string} rel @param {unknown} entry */
     const pushIcon = (rel, entry) => {
       if (!entry) return;
diff --git a/test/bun/metadata-icon-routes.mjs b/test/bun/metadata-icon-routes.mjs
new file mode 100644
index 000000000..c32cc1c58
--- /dev/null
+++ b/test/bun/metadata-icon-routes.mjs
@@ -0,0 +1,151 @@
+/**
+ * Cross-runtime proof that an `app/icon.*` metadata ROUTE is auto-linked into
+ * the SSR'd head, on both Node and Bun. Run from the repo root:
+ *
+ *   node test/bun/metadata-icon-routes.mjs
+ *   bun  test/bun/metadata-icon-routes.mjs
+ *
+ * This is runtime-sensitive on two counts, which is why it is here and not
+ * only in test/ssr. It rides the SSR head-emission path, and it is wired
+ * through module state that `createRequestHandler` binds at boot from the
+ * route table, so a unit test of the head builder alone would pass while the
+ * real handler emitted nothing. The route files are `.ts`, so resolving them
+ * also crosses each runtime's TypeScript stripper (Node 24+'s built-in one,
+ * amaro on Bun).
+ *
+ * Asserts, on whichever runtime executes it: the route is linked and serves,
+ * a declared `metadata.icons` suppresses it (the Next precedence rule), an app
+ * with neither emits no icon link, and the auto-emitted href carries the app's
+ * `basePath` because that is where the route actually answers.
+ */
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { createRequestHandler } from '../../packages/server/src/dev.js';
+
+const runtime = process.versions.bun ? `bun ${process.versions.bun}` : `node ${process.versions.node}`;
+
+function makeApp(files) {
+  const appDir = mkdtempSync(join(tmpdir(), 'webjs-icon-routes-'));
+  for (const [rel, body] of Object.entries(files)) {
+    const abs = join(appDir, rel);
+    mkdirSync(join(abs, '..'), { recursive: true });
+    writeFileSync(abs, body);
+  }
+  return appDir;
+}
+
+const PAGE = `export default function Home() { return 'home'; }\n`;
+
+// A genuinely TypeScript metadata route, so each runtime's stripper has to
+// handle it before the router can see the file at all.
+const ICON_ROUTE = [
+  'export default function Icon(): Response {',
+  "  return new Response('<svg xmlns=\"http://www.w3.org/2000/svg\"/>', {",
+  "    headers: { 'content-type': 'image/svg+xml' },",
+  '  });',
+  '}',
+  '',
+].join('\n');
+
+const APPLE_ICON_ROUTE = ICON_ROUTE.replace('function Icon', 'function AppleIcon');
+
+/** Every icon href the rendered head declares. */
+async function headIconHrefs(handle, url = 'http://localhost/') {
+  const res = await handle(new Request(url));
+  assert.equal(res.status, 200, `page did not render on ${runtime}`);
+  const head = (await res.text()).split('</head>')[0];
+  return [...head.matchAll(/<link rel="[^"]*icon[^"]*"[^>]*href="([^"]+)"/g)].map((m) => m[1]);
+}
+
+// app/icon.ts with no declared icons: linked, and the link resolves.
+{
+  const appDir = makeApp({ 'app/page.js': PAGE, 'app/icon.ts': ICON_ROUTE });
+  const h = await createRequestHandler({ appDir, dev: false });
+  await h.warmup?.();
+
+  const hrefs = await headIconHrefs(h.handle);
+  assert.deepEqual(hrefs, ['/icon'], `app/icon.ts was not auto-linked on ${runtime}`);
+
+  // The whole point of the link: the URL it names has to answer.
+  const icon = await h.handle(new Request('http://localhost/icon'));
+  assert.equal(icon.status, 200, `/icon did not serve on ${runtime}`);
+  assert.match(icon.headers.get('content-type') || '', /^image\//, `/icon served no image on ${runtime}`);
+}
+
+// app/apple-icon.ts maps to rel="apple-touch-icon", not a second rel="icon".
+{
+  const appDir = makeApp({
+    'app/page.js': PAGE,
+    'app/icon.ts': ICON_ROUTE,
+    'app/apple-icon.ts': APPLE_ICON_ROUTE,
+  });
+  const h = await createRequestHandler({ appDir, dev: false });
+  await h.warmup?.();
+
+  const res = await h.handle(new Request('http://localhost/'));
+  const head = (await res.text()).split('</head>')[0];
+  assert.match(head, /<link rel="icon" href="\/icon">/, `icon route missing on ${runtime}`);
+  assert.match(
+    head,
+    /<link rel="apple-touch-icon" href="\/apple-icon">/,
+    `apple-icon route missing on ${runtime}`,
+  );
+}
+
+// A declared metadata.icons wins outright, the way Next merges its static icon
+// files only when the resolved metadata declares no icons of its own.
+{
+  const appDir = makeApp({
+    'app/page.js': PAGE,
+    'app/icon.ts': ICON_ROUTE,
+    'app/apple-icon.ts': APPLE_ICON_ROUTE,
+    'app/layout.js': [
+      "export const metadata = { icons: '/public/brand.svg' };",
+      'export default function Layout({ children }) { return children; }',
+      '',
+    ].join('\n'),
+  });
+  const h = await createRequestHandler({ appDir, dev: false });
+  await h.warmup?.();
+
+  const hrefs = await headIconHrefs(h.handle);
+  assert.deepEqual(
+    hrefs,
+    ['/public/brand.svg'],
+    `a declared metadata.icons did not suppress the icon routes on ${runtime}`,
+  );
+}
+
+// Neither route nor declaration: no icon link at all. The counterfactual that
+// keeps every existing app byte-identical.
+{
+  const appDir = makeApp({ 'app/page.js': PAGE });
+  const h = await createRequestHandler({ appDir, dev: false });
+  await h.warmup?.();
+
+  assert.deepEqual(await headIconHrefs(h.handle), [], `an icon link appeared from nowhere on ${runtime}`);
+}
+
+// Under webjs.basePath the route is SERVED at <basePath>/icon (the listener
+// strips the prefix before matching), so the emitted href has to carry it or
+// the link 404s on exactly the deployments that need it most.
+{
+  const appDir = makeApp({
+    'app/page.js': PAGE,
+    'app/icon.ts': ICON_ROUTE,
+    'package.json': JSON.stringify({ name: 'basepath-icon-app', webjs: { basePath: '/app' } }, null, 2),
+  });
+  const h = await createRequestHandler({ appDir, dev: false });
+  await h.warmup?.();
+
+  const hrefs = await headIconHrefs(h.handle, 'http://localhost/app/');
+  assert.deepEqual(hrefs, ['/app/icon'], `the auto-linked icon href ignored basePath on ${runtime}`);
+
+  const icon = await h.handle(new Request('http://localhost/app/icon'));
+  assert.equal(icon.status, 200, `the base-path icon href did not serve on ${runtime}`);
+}
+
+console.log(`metadata icon routes: auto-link, precedence and basePath OK on ${runtime}`);
diff --git a/test/ssr/ssr.test.js b/test/ssr/ssr.test.js
index c5c6f1ea4..1b5414b21 100644
--- a/test/ssr/ssr.test.js
+++ b/test/ssr/ssr.test.js
@@ -20,7 +20,7 @@ const WEBJS_MODULE_URL = pathToFileURL(
   resolve(__dirname, '../../packages/core/index.js')
 ).toString();
 
-let _hoistHeadTags, _extractUserShell, _buildDocumentParts, ssrPage, ssrNotFound;
+let _hoistHeadTags, _extractUserShell, _buildDocumentParts, ssrPage, ssrNotFound, setMetadataIconRoutes;
 let withRequest;
 let tmpDir;
 
@@ -31,6 +31,7 @@ before(async () => {
     _buildDocumentParts,
     ssrPage,
     ssrNotFound,
+    setMetadataIconRoutes,
   } = await import('../../packages/server/src/ssr.js'));
   // The CSP nonce now flows through the per-request AsyncLocalStorage store
   // (issue #233): `cspNonce()` reads the minted nonce there, or falls back
@@ -655,6 +656,66 @@ test('metadata.icons.other: arbitrary rel allowed', () => {
   assert.match(html, /<link rel="mask-icon" href="\/mask\.svg" type="image\/svg\+xml">/);
 });
 
+/* ------------ Auto-linked icon metadata routes ------------ */
+
+// `app/icon.*` served its bytes and nothing linked them, so the file every
+// other framework treats as "this is my favicon" produced a blank tab with no
+// diagnostic. Next links its static icon files; these pin the parity, and the
+// precedence rule that comes with it.
+//
+// setMetadataIconRoutes is module state (the setClientRouterEnabled shape), so
+// each test clears it rather than leaking a link into every later assertion.
+const withIconRoutes = (t, stems) => {
+  setMetadataIconRoutes(stems.map((stem) => ({ stem })));
+  t.after(() => setMetadataIconRoutes(null));
+};
+
+test('icon metadata route: linked automatically when no icons are declared', (t) => {
+  withIconRoutes(t, ['icon']);
+  assert.match(render({}), /<link rel="icon" href="\/icon">/);
+});
+
+test('apple-icon metadata route: linked as apple-touch-icon', (t) => {
+  withIconRoutes(t, ['icon', 'apple-icon']);
+  const html = render({});
+  assert.match(html, /<link rel="icon" href="\/icon">/);
+  assert.match(html, /<link rel="apple-touch-icon" href="\/apple-icon">/);
+});
+
+test('icon metadata route: no type or sizes is asserted for it', (t) => {
+  // The route picks its content type at request time, which is the reason to
+  // use one, so a declared type could contradict the bytes it serves.
+  withIconRoutes(t, ['icon']);
+  assert.match(render({}), /<link rel="icon" href="\/icon">/);
+  assert.doesNotMatch(render({}), /href="\/icon"[^>]*(type|sizes)=/);
+});
+
+test('a declared metadata.icons suppresses the icon route (Next precedence)', (t) => {
+  // Next merges its static icon files only when the resolved metadata has no
+  // `icons`. An author who names their icons has said which ones they want,
+  // and the route is often a placeholder the app has outgrown, which is
+  // exactly the gallery's case.
+  withIconRoutes(t, ['icon', 'apple-icon']);
+  const html = render({ icons: '/public/favicon.svg' });
+  assert.match(html, /<link rel="icon" href="\/public\/favicon\.svg">/);
+  assert.doesNotMatch(html, /href="\/icon"/);
+  assert.doesNotMatch(html, /href="\/apple-icon"/);
+});
+
+test('non-icon metadata routes never emit an icon link', (t) => {
+  // sitemap / robots / manifest / og-image share the metadata-route mechanism
+  // and are not favicons.
+  withIconRoutes(t, ['sitemap', 'robots', 'manifest', 'opengraph-image', 'twitter-image']);
+  assert.doesNotMatch(render({}), /<link rel="[^"]*icon/);
+});
+
+test('no icon route and no declared icons: no icon link at all', (t) => {
+  // The counterfactual for the whole feature. An app with neither must render
+  // byte-identically to before.
+  withIconRoutes(t, []);
+  assert.doesNotMatch(render({}), /<link rel="[^"]*icon/);
+});
+
 test('metadata.icons + metadataBase: relative URLs are absolutified', () => {
   const html = render({
     metadataBase: 'https://example.com',
diff --git a/website/app/docs/metadata-routes/page.ts b/website/app/docs/metadata-routes/page.ts
index ac800726d..df762e1e7 100644
--- a/website/app/docs/metadata-routes/page.ts
+++ b/website/app/docs/metadata-routes/page.ts
@@ -96,6 +96,34 @@ export default function manifest() {
   };
 }</code-block>
 
+    <h2>icon.ts and apple-icon.ts</h2>
+    <p>These two are <strong>linked into the head for you</strong>. Writing the file is the whole wiring, with no <code>&lt;link&gt;</code> to add anywhere:</p>
+    <code-block>// app/icon.ts  ->  serves /icon AND emits the link
+export default function Icon() {
+  const svg = '&lt;svg xmlns="http://www.w3.org/2000/svg" width="32" height="32"&gt;...&lt;/svg&gt;';
+  return new Response(svg, { headers: { 'content-type': 'image/svg+xml' } });
+}</code-block>
+    <code-block>&lt;!-- what lands in &lt;head&gt; --&gt;
+&lt;link rel="icon" href="/icon"&gt;
+&lt;link rel="apple-touch-icon" href="/apple-icon"&gt;</code-block>
+    <p>The href carries your <code>basePath</code>, because that is where the route answers. No <code>type</code> or <code>sizes</code> is asserted: a metadata route picks its content type at request time, which is the reason to use one, so declaring a type here could contradict the bytes it serves. Browsers sniff the served type.</p>
+    <p>Reach for a route when the mark must be computed per request (per theme, per tenant). For a favicon that never changes, a static file in <code>public/</code> declared through <code>metadata.icons</code> is simpler and cacheable.</p>
+
+    <h3>Declaring icons wins</h3>
+    <p>A <code>metadata.icons</code> declaration <strong>replaces</strong> the routes rather than merging with them, the same precedence Next applies to its static icon files. An app that outgrows a placeholder <code>app/icon.ts</code> names its real icons and the route stops being linked, without the file having to be deleted:</p>
+    <code-block>// app/layout.ts  ->  these win; /icon is no longer linked
+export const metadata = {
+  icons: {
+    icon: [
+      { url: '/public/favicon-192.png', type: 'image/png', sizes: '192x192' },
+      { url: '/public/favicon.svg', type: 'image/svg+xml', sizes: 'any' },
+    ],
+    apple: { url: '/public/apple-touch-icon.png', sizes: '180x180' },
+  },
+};</code-block>
+    <p>Declare a favicon one of those two ways, never as a hand-written <code>&lt;link rel="icon"&gt;</code>: only the root layout may write a document shell at all, so a hand-written tag is unavailable to every other layout. A <code>public/favicon.ico</code> needs no declaration either way, since it is served at the origin root for crawlers that read no markup.</p>
+    <p><code>opengraph-image.ts</code> and <code>twitter-image.ts</code> are <em>not</em> auto-linked, because a preview image is a per-page editorial choice rather than a site-wide default. Point <code>openGraph.images</code> / <code>twitter.images</code> at them.</p>
+
     <h2>Page-level metadata</h2>
     <p>For per-page title, description, and Open Graph tags, export a <code>metadata</code> object from any <code>page.ts</code>. Annotate it with the <code>Metadata</code> type (imported from <code>@webjsdev/core</code>) so a misspelled field or a wrong-typed value is a compile-time error:</p>
 

From 7fd3699f4a961a3cfe444f083542c6c3c8cdb83a Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Mon, 10 Aug 2026 21:26:46 +0530
Subject: [PATCH 2/2] fix(website): declare favicons via metadata.icons, not
 hand-written links

The website hand-wrote its three icon <link> tags into the root layout's
shell while the scaffold comment, the skill, and both other apps say to
declare them. That only ever worked because this is the ROOT layout, the
one layout allowed to write a shell at all (invariant 8), so it modelled
a pattern no other layout could copy.

The rendered head is unchanged apart from attribute order: same three
rels, same assets, raster still ahead of the SVG.

Rewrite the icon half of site-seo-tags to RENDER the app instead of
regexing the layout for hand-written markup, which pinned the very
authoring style the docs argue against and could not see a tag the
framework splices in. It now asserts what a browser receives, adds a
resolve check so a head naming a dead URL fails here, and asserts the
declaration itself. The canonical check stays source-level: it asserts
how the value is DERIVED, which one rendered URL cannot show.

Also pin the gallery's suppression. app/icon.ts is auto-linked now, so
the precedence rule is the only thing keeping the brand mark on
gallery.webjs.dev rather than the demo placeholder.
---
 test/repo-health/gallery-favicon.test.mjs |  15 +++
 test/repo-health/site-seo-tags.test.mjs   | 108 +++++++++++++++++-----
 website/app/layout.ts                     |  36 +++++---
 3 files changed, 123 insertions(+), 36 deletions(-)

diff --git a/test/repo-health/gallery-favicon.test.mjs b/test/repo-health/gallery-favicon.test.mjs
index 4e35320e8..62a0b5402 100644
--- a/test/repo-health/gallery-favicon.test.mjs
+++ b/test/repo-health/gallery-favicon.test.mjs
@@ -106,6 +106,21 @@ test('the gallery serves the same brand mark as the website', async () => {
   );
 });
 
+test('the gallery does not link its app/icon.ts demo route', async () => {
+  // app/icon.ts is the metadata-route DEMO, generating a placeholder grey "w".
+  // It is auto-linked in an app that declares no metadata.icons, so the ONLY
+  // thing keeping the brand mark on gallery.webjs.dev is the precedence rule
+  // that a declaration suppresses the routes. Break that and the gallery
+  // silently reverts to the placeholder, which is the exact defect this file
+  // was written for, so assert the suppression rather than infer it.
+  const app = await makeHandler();
+  const paths = await declaredIconPaths(app.handle);
+  assert.ok(!paths.includes('/icon'), '/icon is not linked');
+  assert.ok(!paths.includes('/apple-icon'), '/apple-icon is not linked');
+  // Both still SERVE; they are browsable demos, just not this app's favicon.
+  assert.equal((await app.handle(new Request('http://localhost/icon'))).status, 200);
+});
+
 test('the gallery declares the raster icon ahead of the SVG', async () => {
   // Same rule the website follows: Google's favicon crawler takes the first
   // usable icon and renders raster reliably. metadata.icons emits array order,
diff --git a/test/repo-health/site-seo-tags.test.mjs b/test/repo-health/site-seo-tags.test.mjs
index bf91fcd9d..c00f56abe 100644
--- a/test/repo-health/site-seo-tags.test.mjs
+++ b/test/repo-health/site-seo-tags.test.mjs
@@ -20,9 +20,16 @@
  * them. `docs.webjs.dev` still resolves, but as a Cloudflare redirect rule
  * with nothing indexable of its own, which is the point of the move.
  *
- * These are source-level assertions on the layout file rather than SSR
- * renders, because the three apps have different dependency trees and
- * importing all of them into one test process is not worth the coupling.
+ * The icon assertions RENDER the app rather than reading its layout source.
+ * They used to regex the layout for hand-written `<link>` markup, which
+ * pinned an authoring style the framework tells apps not to use: only a ROOT
+ * layout may write a shell at all (invariant 8), so a hand-written tag is a
+ * pattern no other layout can copy, and favicons are declared through
+ * `metadata.icons`. Rendering asserts what a browser actually receives, which
+ * is the thing that matters and is also the only way to see icons the
+ * framework splices in. The canonical check stays source-level: it asserts
+ * how the value is DERIVED (origin plus pathname, trailing slash stripped),
+ * which one rendered URL cannot show.
  */
 import test from 'node:test';
 import assert from 'node:assert/strict';
@@ -30,6 +37,8 @@ import { readFileSync, existsSync } from 'node:fs';
 import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { createRequestHandler } from '@webjsdev/server';
+
 const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 
 /**
@@ -52,49 +61,88 @@ function pngSize(path) {
   return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
 }
 
+/**
+ * The icon `<link>` tags the app's home page actually serves, in head order.
+ *
+ * Rendering is what makes this honest: the tags may come from hand-written
+ * markup, from `metadata.icons`, or from an auto-linked `app/icon.*` metadata
+ * route, and a browser cannot tell the difference. Neither should this.
+ */
+async function renderedIconLinks(dir) {
+  const app = await createRequestHandler({ appDir: resolve(REPO_ROOT, dir), dev: true });
+  const res = await app.handle(new Request('http://localhost/'));
+  assert.equal(res.status, 200, `${dir} home page renders`);
+  // Browsers ignore a favicon <link> in <body>, so only the head counts.
+  const head = (await res.text()).split('</head>')[0];
+  return [...head.matchAll(/<link rel="[^"]*icon[^"]*"[^>]*>/g)].map((m) => m[0]);
+}
+
+/** Pull an attribute off one rendered tag, order-independently. */
+const attr = (tag, name) => (tag.match(new RegExp(`${name}="([^"]*)"`)) || [])[1];
+
 for (const app of APPS) {
-  test(`${app.name}: the declared favicon size matches the real asset`, () => {
-    const src = layoutOf(app.dir);
-    const m = src.match(/<link rel="icon" href="\/public\/([\w.-]+\.png)" type="image\/png" sizes="(\d+)x(\d+)"/);
-    assert.ok(m, 'declares a PNG icon with an explicit size');
+  test(`${app.name}: the declared favicon size matches the real asset`, async () => {
+    const links = await renderedIconLinks(app.dir);
+    const png = links.find((l) => attr(l, 'type') === 'image/png');
+    assert.ok(png, 'serves a PNG icon with an explicit type');
+
+    const href = attr(png, 'href');
+    const sizes = attr(png, 'sizes');
+    assert.ok(sizes, 'the PNG icon declares a size');
+    const [w, h] = sizes.split('x');
+    assert.equal(w, h, 'declared as square');
 
-    const [, file, w, h] = m;
-    const declared = Number(w);
+    const file = href.replace(/^\/public\//, '');
     const asset = publicFile(app.dir, file);
     assert.ok(existsSync(asset), `${file} exists in public/`);
 
     const real = pngSize(asset);
-    assert.equal(w, h, 'declared as square');
     assert.equal(real.width, real.height, 'the asset really is square');
     // The original bug in one assertion: the markup claimed 32 for a 512 file.
-    assert.equal(declared, real.width, 'the DECLARED size matches the real asset');
+    assert.equal(Number(w), real.width, 'the DECLARED size matches the real asset');
     // The second half: 32 was under the floor, and 512 would have failed too,
     // since 512 % 48 is 32. Hence the 192px asset.
-    assert.equal(declared % 48, 0, 'the size is a multiple of 48px, which Google requires');
+    assert.equal(Number(w) % 48, 0, 'the size is a multiple of 48px, which Google requires');
   });
 
-  test(`${app.name}: the raster icon is declared before the SVG`, () => {
+  test(`${app.name}: the raster icon is served before the SVG`, async () => {
     // Google's favicon crawler takes the first usable icon, and raster is what
     // search results reliably render. All three led with the SVG before.
-    const src = layoutOf(app.dir);
-    const png = src.indexOf('type="image/png"');
-    const svg = src.indexOf('/public/favicon.svg');
-    assert.ok(png > -1 && svg > -1, 'declares both a PNG and an SVG icon');
-    assert.ok(png < svg, 'the PNG is declared ahead of the SVG');
+    const links = await renderedIconLinks(app.dir);
+    const png = links.findIndex((l) => attr(l, 'type') === 'image/png');
+    const svg = links.findIndex((l) => attr(l, 'type') === 'image/svg+xml');
+    assert.ok(png > -1 && svg > -1, 'serves both a PNG and an SVG icon');
+    assert.ok(png < svg, 'the PNG comes first in the head');
   });
 
-  test(`${app.name}: the apple-touch icon points at a correctly sized asset`, () => {
-    const src = layoutOf(app.dir);
-    const m = src.match(/<link rel="apple-touch-icon" sizes="(\d+)x\d+" href="\/public\/([\w.-]+\.png)"/);
-    assert.ok(m, 'declares an apple-touch-icon with an explicit size');
-    const asset = publicFile(app.dir, m[2]);
-    assert.ok(existsSync(asset), `${m[2]} exists in public/`);
-    assert.equal(Number(m[1]), pngSize(asset).width, 'the declared size matches the real asset');
+  test(`${app.name}: the apple-touch icon points at a correctly sized asset`, async () => {
+    const links = await renderedIconLinks(app.dir);
+    const apple = links.find((l) => attr(l, 'rel') === 'apple-touch-icon');
+    assert.ok(apple, 'serves an apple-touch-icon');
+    const file = attr(apple, 'href').replace(/^\/public\//, '');
+    const asset = publicFile(app.dir, file);
+    assert.ok(existsSync(asset), `${file} exists in public/`);
+    assert.equal(Number(attr(apple, 'sizes').split('x')[0]), pngSize(asset).width,
+      'the declared size matches the real asset');
+  });
+
+  test(`${app.name}: every icon it links is actually served`, async () => {
+    // A head naming a URL nothing answers is the failure mode that took
+    // gallery.webjs.dev two PRs to shake out, so resolve each href rather than
+    // trusting the markup.
+    const application = await createRequestHandler({ appDir: resolve(REPO_ROOT, app.dir), dev: true });
+    for (const link of await renderedIconLinks(app.dir)) {
+      const href = attr(link, 'href');
+      const res = await application.handle(new Request(`http://localhost${href}`));
+      assert.equal(res.status, 200, `${href} is served, not a 404`);
+    }
   });
 
   test(`${app.name}: ships a root favicon.ico with a 48x48 entry`, () => {
     // The framework serves /favicon.ico from public/favicon.ico. All three
     // returned 404 for it before, so the no-markup crawler fallback was absent.
+    // Deliberately NOT a rendered assertion: nothing links it, which is the
+    // point (crawlers that parse no HTML fetch the path directly).
     const ico = publicFile(app.dir, 'favicon.ico');
     assert.ok(existsSync(ico), 'public/favicon.ico exists');
     const buf = readFileSync(ico);
@@ -105,6 +153,16 @@ for (const app of APPS) {
     assert.ok(sizes.includes(48), `bundles a 48x48 entry, got ${sizes.join('/')}`);
   });
 
+  test(`${app.name}: declares its favicons, rather than hand-writing the markup`, () => {
+    // The convention the framework documents, and what every other app in the
+    // repo does. A hand-written tag works ONLY in a root layout (invariant 8),
+    // so it is a pattern no other layout can copy, and the docs told readers
+    // not to write it while this app did.
+    const src = layoutOf(app.dir);
+    assert.match(src, /icons:\s*\{/, 'declares metadata.icons');
+    assert.doesNotMatch(src, /<link rel="[^"]*icon/, 'writes no icon <link> by hand');
+  });
+
   test(`${app.name}: the root layout emits a canonical URL`, () => {
     const src = layoutOf(app.dir);
     assert.match(src, /alternates:\s*\{\s*canonical\s*\}/, 'sets alternates.canonical in generateMetadata');
diff --git a/website/app/layout.ts b/website/app/layout.ts
index 5231941c2..56793df7a 100644
--- a/website/app/layout.ts
+++ b/website/app/layout.ts
@@ -64,6 +64,29 @@ export function generateMetadata(ctx: { url: string }) {
     cacheControl: 'public, max-age=60, s-maxage=600, stale-while-revalidate=86400',
     title: TITLE,
     description: DESCRIPTION,
+    // Favicons, ordered raster first on purpose. Google's favicon crawler takes
+    // the first usable icon and wants a SQUARE raster whose side is a multiple
+    // of 48px. This once declared sizes="32x32" on an asset that is really
+    // 512x512: the claim was both wrong and under Google's 48px floor, which is
+    // why webjs.dev showed no icon in search results. 192 is used because it is
+    // a clean multiple of 48 (512 is not, 512 % 48 = 32).
+    //
+    // Declared here rather than hand-written into the shell below, which is the
+    // way the framework documents and the way every other app in the repo does
+    // it. A hand-written tag only works because this is the ROOT layout, the
+    // one layout allowed to write a shell at all (invariant 8), so it was a
+    // pattern no other layout could copy.
+    //
+    // /favicon.ico is absent on purpose: it is served from public/favicon.ico
+    // at the origin root and stays the fallback for crawlers that read no
+    // markup, so linking it would add a tag nothing reads.
+    icons: {
+      icon: [
+        { url: '/public/favicon-192.png', type: 'image/png', sizes: '192x192' },
+        { url: '/public/favicon.svg', type: 'image/svg+xml', sizes: 'any' },
+      ],
+      apple: { url: '/public/apple-touch-icon.png', sizes: '180x180' },
+    },
     openGraph: {
       type: 'website',
       title: TITLE,
@@ -85,17 +108,8 @@ const panelLink = 'text-fg-muted no-underline font-medium text-sm px-3 py-2.5 ro
 export default function RootLayout({ children }: LayoutProps) {
   const nonce = cspNonce();
   return html`
-    <!-- Favicons, ordered raster first on purpose. Google's favicon crawler takes
-         the first usable icon and wants a SQUARE raster whose side is a multiple
-         of 48px. This previously declared sizes="32x32" on an asset that is
-         really 512x512: the claim was both wrong and under Google's 48px floor,
-         which is why webjs.dev showed no icon in search results. 192 is used
-         because it is a clean multiple of 48 (512 is not, 512 % 48 = 32).
-         /favicon.ico is served from public/favicon.ico at the origin root and
-         stays as the fallback for crawlers that read no markup at all. -->
-    <link rel="icon" href="/public/favicon-192.png" type="image/png" sizes="192x192">
-    <link rel="icon" href="/public/favicon.svg" type="image/svg+xml" sizes="any">
-    <link rel="apple-touch-icon" sizes="180x180" href="/public/apple-touch-icon.png">
+    <!-- Favicons are declared in generateMetadata above (metadata.icons), not
+         written here. The framework splices them into <head>. -->
 
     <!-- Self-hosted fonts (declared via @font-face in input.css), preloaded so
          they fetch in parallel with the stylesheet instead of being discovered