@nuxtseo/design-system 0.0.0-stage → 0.1.0

package/nuxt.config.ts

@@ -0,0 +1,132 @@
+import { defineNuxtConfig } from 'nuxt/config'
+import { join } from 'pathe'
+import { UI_ICON_SLOTS } from './shared/icons/ui-slots'
+
+const currentDir = import.meta.dirname
+
+// Design system layer: design language extended by every app — UI primitives, tokens, fonts,
+// motion, chart helpers, formatters, design vocabularies (Status, severity), cross-cutting UI
+// affordances (eject, feedback widget contracts).
+//
+// Per ADR-0042 (pragmatic rule): MAY know domain shapes; MUST NOT import runtime services
+// (no useFetch, Drizzle, Caller, billing, auth, useRuntimeConfig). Storybook test: renders with
+// prop fixtures alone. Placement contract for components: ADR-0029. Components MUST NOT be
+// prefixed Pro/Admin/Tool/Docs/Learn — the layer name is the scope. Internal taxonomy:
+// components/{container,data,element}/.
+
+export default defineNuxtConfig({
+  imports: { autoImport: false },
+
+  nitro: {
+    imports: { autoImport: false },
+    alias: {
+      // `@nuxt/image@2.1.0` reaches `useRuntimeConfig` through
+      // `nitro/runtime-config` — the nitro v3 package — in
+      // `runtime/server/routes/_ipx.js` and `runtime/server/utils/image.js`. It
+      // declares no peer dependency for it, and this project runs Nuxt 4.5 on
+      // nitropack v2, where that specifier does not exist. Without this alias
+      // every app builds a server bundle importing a package that is not
+      // installed and boots to `Cannot find package 'nitro'`.
+      //
+      // A `patchedDependencies` entry cannot express this. `pnpm patch`
+      // extracts a PRISTINE copy that imports from `#imports`, so the diff comes
+      // out empty — the bad bytes live in pnpm's unpacked store layer and
+      // re-materialise on any install, three times in one session, machine-wide
+      // across every checkout sharing the store. An alias is immune to that
+      // because it never depends on what is on disk.
+      //
+      // Remove when the app moves to nitro v3, or when @nuxt/image ships the v2
+      // compatibility path its sibling @nuxt/scripts@2.0.0-beta.2 already
+      // carries (`resolveNitroImport` probing `nitro/app`, `nitro/cache`,
+      // `nitro/h3`, `nitro/runtime-config`, falling back to `nitropack/runtime`).
+      'nitro/runtime-config': 'nitropack/runtime',
+    },
+  },
+
+  // Nuxt UI collects its app-config slots into the icon client bundle during
+  // module setup. Declare the semantic mapping here as well as in app.config
+  // so its default Lucide slots never become a second implicit allowlist.
+  appConfig: {
+    ui: { icons: UI_ICON_SLOTS },
+  },
+
+  modules: [
+    // Before `@nuxt/ui`: it writes the icon aliases and client bundle that
+    // @nuxt/icon reads. `designSystem` options live in build/design-system.ts.
+    join(currentDir, './build/design-system'),
+    '@comark/nuxt',
+    '@nuxt/fonts',
+    '@nuxt/image',
+    '@nuxt/scripts',
+    'motion-v/nuxt',
+    'reka-ui/nuxt',
+    '@nuxt/ui',
+  ],
+
+  css: [
+    join(currentDir, './css/global.css'),
+  ],
+
+  components: {
+    dirs: [
+      {
+        path: join(currentDir, './app/components'),
+        pathPrefix: false,
+        // Higher priority so design-system primitives win shadow conflicts against root
+        // app/components/* of the same basename (e.g. content/Alert.vue, owned by the
+        // content team — left in place; design-system's Alert is the canonical one).
+        priority: 10,
+      },
+    ],
+  },
+
+  // Canonical type stack for every surface that extends this layer (root app
+  // + apps/brand-kit brand-kit). Keep in sync via this single block —
+  // don't redeclare in root or app configs.
+  fonts: {
+    // Both families are global. CSS variable discovery cannot add another
+    // face, so avoid parsing every component style during each Vite build.
+    processCSSVariables: false,
+    families: [
+      // Keep build inputs in this layer. Provider downloads make every app
+      // build depend on Google Fonts availability after compilation finishes.
+      // Hubot Sans keeps variable weight and width axes for the design tokens.
+      {
+        name: 'Hubot Sans',
+        src: '/fonts/hubot-sans-var-latin.woff2',
+        weight: '200 900',
+        stretch: '75% 125%',
+        style: 'normal',
+        global: true,
+      },
+      {
+        name: 'Fira Code',
+        src: '/fonts/fira-code-var-latin.woff2',
+        weight: '400 500',
+        style: 'normal',
+        global: true,
+      },
+    ],
+  },
+
+  icon: {
+    // build/design-system.ts adds the role aliases and the chosen set's client
+    // bundle. Ship only that set's resolved role icons. Explicit raw ids outside
+    // that curated bundle resolve through Iconify in the browser. An app that
+    // installs `build/icon-server-bundle.ts` renders them on the server too.
+    provider: 'iconify',
+    serverBundle: false,
+    clientBundle: {
+      scan: false,
+    },
+  },
+
+  ui: {
+    experimental: { componentDetection: true },
+    content: true,
+    theme: {
+      colors: ['primary', 'secondary', 'tertiary', 'info', 'success', 'warning', 'error', 'pro'],
+    },
+  },
+
+})

package/package.json

@@ -1,6 +1,89 @@
 {
   "name": "@nuxtseo/design-system",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "type": "module",
+  "version": "0.1.0",
+  "description": "Nuxt SEO design system layer: UI primitives, tokens, fonts, motion, and chart helpers. Extend it from a Nuxt app.",
+  "license": "MIT",
+  "homepage": "https://nuxtseo.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/harlan-zw/nuxtseo.com.git",
+    "directory": "layers/design-system"
+  },
+  "keywords": [
+    "nuxt",
+    "nuxt-layer",
+    "design-system",
+    "nuxt-ui"
+  ],
+  "exports": {
+    ".": "./nuxt.config.ts",
+    "./*": "./*",
+    "./app/*": "./app/*.ts",
+    "./app/*.vue": "./app/*.vue",
+    "./components/*": "./app/components/*.ts",
+    "./components/*.vue": "./app/components/*.vue",
+    "./composables/*": "./app/composables/*.ts",
+    "./package.json": "./package.json",
+    "./server/*": "./server/*.ts",
+    "./shared/*": "./shared/*.ts"
+  },
+  "main": "./nuxt.config.ts",
+  "files": [
+    "app",
+    "build",
+    "css",
+    "nuxt.config.ts",
+    "public",
+    "server",
+    "shared",
+    "types"
+  ],
+  "peerDependencies": {
+    "nuxt": "^4.6.0",
+    "typescript": ">=5.8.0 <7",
+    "vue": "^3.5.0"
+  },
+  "dependencies": {
+    "@comark/nuxt": "0.7.0",
+    "@iconify-json/hugeicons": "^1.2.34",
+    "@iconify-json/logos": "^1.2.14",
+    "@iconify-json/lucide": "^1.2.130",
+    "@iconify-json/simple-icons": "^1.2.95",
+    "@iconify-json/svg-spinners": "^1.2.4",
+    "@iconify/vue": "^5.0.1",
+    "@nuxt/fonts": "^1.0.1",
+    "@nuxt/icon": "^2.5.1",
+    "@nuxt/image": "^2.1.0",
+    "@nuxt/scripts": "2.0.0-beta.14",
+    "@nuxt/ui": "^4.11.1",
+    "@tanstack/table-core": "^9.2.4",
+    "@tanstack/vue-table": "^9.2.4",
+    "@unovis/ts": "^1.6.7",
+    "@unovis/vue": "^1.6.7",
+    "@vueuse/core": "^14.4.0",
+    "motion-v": "2.4.2",
+    "nuxtseo-shared": "^6.0.2",
+    "pathe": "^2.0.3",
+    "rangi": "^2.2.0",
+    "reka-ui": "^2.10.4",
+    "tailwindcss": "^4.3.3",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "ai": "^7.0.122",
+    "nuxt": "4.6.1",
+    "sharp": "^0.35.4",
+    "site-typecheck": "0.0.0",
+    "vue": "^3.5.43"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "nuxt:prepare": "nuxt prepare",
+    "typecheck": "nuxt prepare && site-typecheck -b --noEmit --force",
+    "brand:assets": "node --experimental-strip-types scripts/brand-assets.ts",
+    "typecheck:legacy": "nuxt typecheck"
+  }
 }

package/public/fonts/README.md

@@ -0,0 +1,31 @@
+# Build fonts
+
+The design system owns these font files. Nuxt copies them into every app that
+extends this layer. Builds never download fonts from an external provider.
+
+The Hubot Sans file is a latin/latin-ext subset of the official v1.0.1 release
+face (`HubotSans[slnt,wdth,wght].woff2`). It keeps the weight axis (200 to 900)
+and the width axis (75% to 125%) for the design tokens. The slant axis is
+pinned to 0 and dropped, and glyphs outside latin and latin-ext are removed,
+so the transfer payload stays under 100KB
+(`tests/design-system-hubot-font-subset.feature.test.ts` holds this contract).
+
+To regenerate it, run a HarfBuzz subset over the release face with
+`variationAxes: { wght: { min: 200, max: 900 }, wdth: { min: 75, max: 125 }, slnt: 0 }`
+and the Google Fonts latin plus latin-ext unicode ranges.
+
+The subset is a Modified Version under the OFL, so it must not present the
+Reserved Font Name "Hubot". Override name records 1, 4, and 6 (plus 16 when
+present) to a family name without "Hubot", for example "Nuxt SEO Sans" with
+PostScript name "NuxtSEOSans-ExtraLight". Keep the copyright record verbatim;
+it carries the reservation notice. The subset test holds this contract.
+
+The Fira Code file contains the Latin subset. Nuxt exposes weights 400 through
+500 and the normal style.
+
+The alert email shell also uses Hubot Sans from the stable URL
+`https://nuxtseo.com/fonts/hubot-sans-var-latin.woff2`.
+
+Both fonts use the SIL Open Font License 1.1. Keep each font with its matching
+license file. Hubot Sans release source:
+`https://github.com/github/hubot-sans/releases/tag/v1.0.1`.

package/public/fonts/fira-code-OFL.txt

@@ -0,0 +1,93 @@
+Copyright (c) 2014, The Fira Code Project Authors (https://github.com/tonsky/FiraCode)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://openfontlicense.org
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/public/fonts/hubot-sans-OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2021 The Hubot Sans Project Authors (https://github.com/github/hubot-sans), with Reserved Font Name "Hubot"
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://openfontlicense.org
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/server/api/favicon.get.ts

@@ -0,0 +1,122 @@
+import { createError, defineEventHandler, getQuery, getRequestHeader, setResponseHeader, setResponseStatus } from 'h3'
+import { resolveStoredFavicon } from '../utils/favicon-source'
+/**
+ * Same-origin favicon proxy. UiFavicon renders this instead of hitting Google's
+ * s2 endpoint directly so the image is (a) cacheable on our edge, (b) decoupled
+ * from leaking every user's site list to Google per render, and crucially
+ * (c) same-origin — which lets the client sample the favicon on a canvas without
+ * a cross-origin taint, the basis for UiFavicon's adaptive backing (see
+ * useFaviconBacking). We only ever fetch Google with the domain as a query
+ * param, never the supplied host directly, so there is no SSRF surface; the
+ * format guard just rejects junk input.
+ *
+ * TWO SOURCES, in order. A Site the Crawl has reached is served from our own
+ * store — the Crawl fetches the home page's icon links anyway, so the bytes are
+ * the ones the Site actually serves today. Everything else (a competitor domain,
+ * a Site added minutes ago, any domain a marketing page names) falls back to
+ * Google's `s2` copy, which is the only source we have for a domain we do not
+ * crawl.
+ *
+ * The fallback is where staleness lives and it is not ours to fix: measured
+ * 2026-09-23, Google's copy of gscdump.com's icon and the icon that Site serves
+ * are different files, and our 30-day edge copy matched Google's exactly. No
+ * cache purge moves it. Crawling the Site is the fix, which is what the store
+ * branch is.
+ */
+// 1×1 FULLY TRANSPARENT PNG. The previous constant claimed to be this and was
+// not: its single pixel decoded to `R=0 G=255 B=0 A=127`, so every mail client
+// scaled a half-opaque pure-green swatch to 16px and painted it beside the
+// hostname — under a warning headline, where it read as a health dot. Verify
+// with a decode, never by looking: at 1×1 the difference is invisible in source
+// and obvious in an inbox.
+// `?fallback=blank` callers get this with a 200 instead of
+// a 404 — an <img> that 404s paints a broken-image glyph in clients with no
+// scripted onerror to fall back with (mail, notably), and blank space beats a
+// broken icon there. UiFavicon also requests the blank response, then detects
+// its 1×1 size and swaps in the initials box without logging a failed request.
+const BLANK_PNG = Uint8Array.from(
+  atob('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAC0lEQVR4nGNgAAIAAAUAAXpeqz8AAAAASUVORK5CYII='),
+  c => c.charCodeAt(0),
+)
+
+export default defineEventHandler(async (event) => {
+  const query = getQuery(event)
+  const blankOnMiss = query.fallback === 'blank'
+  const contentHash = query.hash
+  const raw = String(query.domain ?? '')
+    .replace(/^sc-domain:/, '')
+    .replace(/^https?:\/\//, '')
+    .replace(/\/.*$/, '')
+    .trim()
+    .toLowerCase()
+
+  function miss() {
+    if (!blankOnMiss) {
+      setResponseStatus(event, 404)
+      return null
+    }
+    setResponseHeader(event, 'Content-Type', 'image/png')
+    setResponseHeader(event, 'Cache-Control', 'public, max-age=604800, s-maxage=2592000, immutable')
+    return BLANK_PNG
+  }
+
+  if (!raw || !/^[a-z0-9.-]+\.[a-z]{2,}$/.test(raw)) {
+    if (blankOnMiss)
+      return miss()
+    throw createError({ statusCode: 400, statusMessage: 'invalid domain' })
+  }
+  if (contentHash !== undefined && (typeof contentHash !== 'string' || !/^[a-f0-9]{64}$/.test(contentHash)))
+    throw createError({ statusCode: 400, statusMessage: 'invalid favicon hash' })
+
+  // Our own capture wins whenever we have one. A failed lookup is not an error
+  // worth surfacing: the Google fallback below is a complete answer, so a store
+  // that is down shows the icon everything showed before the store existed.
+  const stored = await resolveStoredFavicon(event, raw, contentHash).catch((silentCatchError: unknown) => {
+    console.warn('[silent-catch] layers/design-system/server/api/favicon.get.ts:stored-lookup', silentCatchError)
+    return null
+  })
+  if (stored) {
+    const etag = `"${stored.contentHash}"`
+    setResponseHeader(event, 'ETag', etag)
+    // NOT `immutable`. These bytes can change the day a Site rebrands, and the
+    // whole point of storing them is that the change reaches the reader. The
+    // ETag makes the revalidation a 304 rather than a re-download.
+    setResponseHeader(event, 'Cache-Control', contentHash
+      ? 'public, max-age=31536000, s-maxage=31536000, immutable'
+      : 'public, max-age=3600, s-maxage=86400, must-revalidate')
+    if (getRequestHeader(event, 'if-none-match') === etag) {
+      setResponseStatus(event, 304)
+      return null
+    }
+    setResponseHeader(event, 'Content-Type', stored.contentType)
+    return stored.bytes
+  }
+
+  // A dated request must answer from its captured bytes. Google's current
+  // copy would show the wrong mark as the "before" state.
+  if (contentHash) {
+    setResponseStatus(event, 404)
+    return null
+  }
+
+  const upstream = `https://www.google.com/s2/favicons?domain=${encodeURIComponent(raw)}&sz=128`
+
+  // A missing favicon is an expected outcome, not an infra failure: plenty of
+  // domains have none, and the upstream fetch can also fail on DNS/network. In
+  // every such case we want UiFavicon's <img> onerror to fall through to the
+  // initials box — so we set a non-2xx status and return empty rather than
+  // throwing, which would surface as an unhandled error in Sentry.
+  const res = await fetch(upstream).catch((silentCatchError: unknown) => {
+    console.warn('[silent-catch] layers/design-system/server/api/favicon.get.ts:30', silentCatchError)
+    return null
+  })
+  if (!res?.ok)
+    return miss()
+
+  setResponseHeader(event, 'Content-Type', res.headers.get('content-type') ?? 'image/png')
+  // Google's copy of a domain's icon changes on Google's schedule, which we
+  // cannot see or influence, so caching it hard costs nothing we could have
+  // served better. A Site we crawl never reaches this branch.
+  setResponseHeader(event, 'Cache-Control', 'public, max-age=604800, s-maxage=2592000, immutable')
+  return new Uint8Array(await res.arrayBuffer())
+})

package/server/utils/favicon-source.ts

@@ -0,0 +1,51 @@
+/**
+ * Where `/api/favicon` looks before it falls back to Google.
+ *
+ * The endpoint ships in the design system, so both the site worker and the pro
+ * worker build it, and only pro holds the Sites tables and the R2 bucket that
+ * the Crawl writes captured marks into. Rather than import pro from here (the
+ * dependency runs the other way), the pro worker registers a resolver at cold
+ * start and the endpoint asks for one. A worker that registers nothing keeps
+ * exactly the behaviour this endpoint had before the store existed.
+ *
+ * Same registration shape as the Timeline's `defineEntryKind`: a nitro plugin
+ * in the owning layer fills a registry the shared code reads.
+ */
+
+import type { H3Event } from 'h3'
+
+export interface StoredFavicon {
+  bytes: Uint8Array
+  contentType: string
+  /** SHA-256 of the bytes, served as the `ETag` so a re-fetch after a rebrand is one 304. */
+  contentHash: string
+}
+
+/**
+ * Takes the request event, not just the domain.
+ *
+ * The resolver reads D1, and this codebase's `useDb()` only attaches the
+ * session, the instruments and the 2-second first-query guard when it is given
+ * an event. A signature that could not carry one would have put an
+ * unguarded, uninstrumented read on a public endpoint that fires once per
+ * avatar on a portfolio page.
+ */
+export type FaviconSource = (event: H3Event, domain: string, contentHash?: string) => Promise<StoredFavicon | null>
+
+let registered: FaviconSource | null = null
+
+/** Called once per worker from the owning layer's nitro plugin. */
+export function registerFaviconSource(source: FaviconSource): void {
+  registered = source
+}
+
+/**
+ * The stored mark for a domain, or null when this worker has no store, the
+ * domain is not a Site we have crawled, or the lookup failed. Never throws: a
+ * store that is down must degrade to the Google fallback, not to a broken image.
+ */
+export async function resolveStoredFavicon(event: H3Event, domain: string, contentHash?: string): Promise<StoredFavicon | null> {
+  if (!registered)
+    return null
+  return registered(event, domain, contentHash)
+}