@nuxtseo/design-system 0.0.0-stage → 0.1.0

package/app/components/element/UiDitherAvatar.vue

@@ -0,0 +1,177 @@
+<script setup lang="ts">
+import { computed, useId } from 'vue'
+
+const { seed, size = 32, label, colors } = defineProps<{
+  seed: string
+  size?: number
+  label?: string
+  /**
+   * Hex palette the avatar draws from. Defaults to the Nuxt SEO palette; a site
+   * with its own brand passes its own. Six-digit hex only: the face colour is
+   * picked for contrast from it.
+   */
+  colors?: readonly string[]
+}>()
+
+/*
+ * Beam generator adapted from Boring Avatars:
+ * https://github.com/boringdesigners/boring-avatars
+ *
+ * MIT License
+ *
+ * Copyright (c) 2021 boringdesigners
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+const SIZE = 36
+const AVATAR_COLORS = ['#8B5CF6', '#00DC82', '#F59E0B', '#EC4899', '#3B82F6'] as const
+
+function hashCode(name: string): number {
+  let hash = 0
+  for (let index = 0; index < name.length; index++) {
+    const character = name.charCodeAt(index)
+    hash = ((hash << 5) - hash) + character
+    hash &= hash
+  }
+  return Math.abs(hash)
+}
+
+function getDigit(number: number, position: number): number {
+  return Math.floor((number / 10 ** position) % 10)
+}
+
+function getBoolean(number: number, position: number): boolean {
+  return getDigit(number, position) % 2 === 0
+}
+
+function getUnit(number: number, range: number, position?: number): number {
+  const value = number % range
+  return position && getDigit(number, position) % 2 === 0 ? -value : value
+}
+
+function getRandomColor(number: number, colors: readonly string[]): string {
+  return colors[number % colors.length]!
+}
+
+function getContrast(hexColor: string): string {
+  const color = hexColor.startsWith('#') ? hexColor.slice(1) : hexColor
+  const red = Number.parseInt(color.slice(0, 2), 16)
+  const green = Number.parseInt(color.slice(2, 4), 16)
+  const blue = Number.parseInt(color.slice(4, 6), 16)
+  const yiq = (red * 299 + green * 587 + blue * 114) / 1000
+  return yiq >= 128 ? '#000000' : '#FFFFFF'
+}
+
+function generateBeamData(name: string, colors: readonly string[]) {
+  const number = hashCode(name)
+  const wrapperColor = getRandomColor(number, colors)
+  const preTranslateX = getUnit(number, 10, 1)
+  const wrapperTranslateX = preTranslateX < 5 ? preTranslateX + SIZE / 9 : preTranslateX
+  const preTranslateY = getUnit(number, 10, 2)
+  const wrapperTranslateY = preTranslateY < 5 ? preTranslateY + SIZE / 9 : preTranslateY
+
+  return {
+    wrapperColor,
+    faceColor: getContrast(wrapperColor),
+    backgroundColor: getRandomColor(number + 13, colors),
+    wrapperTranslateX,
+    wrapperTranslateY,
+    wrapperRotate: getUnit(number, 360),
+    wrapperScale: 1 + getUnit(number, SIZE / 12) / 10,
+    isMouthOpen: getBoolean(number, 2),
+    isCircle: getBoolean(number, 1),
+    eyeSpread: getUnit(number, 5),
+    mouthSpread: getUnit(number, 3),
+    faceRotate: getUnit(number, 10, 3),
+    faceTranslateX: wrapperTranslateX > SIZE / 6 ? wrapperTranslateX / 2 : getUnit(number, 8, 1),
+    faceTranslateY: wrapperTranslateY > SIZE / 6 ? wrapperTranslateY / 2 : getUnit(number, 7, 2),
+  }
+}
+
+const data = computed(() => generateBeamData(seed, colors?.length ? colors : AVATAR_COLORS))
+const id = useId().replace(/[^a-z0-9]/gi, '')
+const maskId = `avatar-mask-${id}`
+const ditherId = `avatar-dither-${id}`
+const wrapperTransform = computed(() => [
+  `translate(${data.value.wrapperTranslateX} ${data.value.wrapperTranslateY})`,
+  `rotate(${data.value.wrapperRotate} ${SIZE / 2} ${SIZE / 2})`,
+  `scale(${data.value.wrapperScale})`,
+].join(' '))
+const faceTransform = computed(() => [
+  `translate(${data.value.faceTranslateX} ${data.value.faceTranslateY})`,
+  `rotate(${data.value.faceRotate} ${SIZE / 2} ${SIZE / 2})`,
+].join(' '))
+</script>
+
+<template>
+  <span
+    class="ui-dither-avatar inline-flex shrink-0 overflow-hidden rounded-full"
+    :style="{ width: `${size}px`, height: `${size}px` }"
+    :role="label ? 'img' : undefined"
+    :aria-label="label"
+    :aria-hidden="label ? undefined : 'true'"
+  >
+    <svg viewBox="0 0 36 36" fill="none" class="size-full" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false">
+      <defs>
+        <mask :id="maskId" maskUnits="userSpaceOnUse" x="0" y="0" width="36" height="36">
+          <rect width="36" height="36" rx="72" fill="white" />
+        </mask>
+        <pattern :id="ditherId" width="4" height="4" patternUnits="userSpaceOnUse">
+          <circle cx="0.8" cy="0.8" r="0.55" :fill="data.faceColor" opacity="0.2" />
+          <circle cx="2.8" cy="2.8" r="0.4" :fill="data.faceColor" opacity="0.12" />
+        </pattern>
+      </defs>
+
+      <g :mask="`url(#${maskId})`">
+        <rect width="36" height="36" :fill="data.backgroundColor" />
+        <rect
+          width="36"
+          height="36"
+          :transform="wrapperTransform"
+          :fill="data.wrapperColor"
+          :rx="data.isCircle ? 36 : 6"
+        />
+        <g :transform="faceTransform">
+          <path
+            v-if="data.isMouthOpen"
+            :d="`M15 ${19 + data.mouthSpread}c2 1 4 1 6 0`"
+            :stroke="data.faceColor"
+            fill="none"
+            stroke-linecap="round"
+          />
+          <path
+            v-else
+            :d="`M13,${19 + data.mouthSpread} a1,0.75 0 0,0 10,0`"
+            :fill="data.faceColor"
+          />
+          <rect :x="14 - data.eyeSpread" y="14" width="1.5" height="2" rx="1" :fill="data.faceColor" />
+          <rect :x="20 + data.eyeSpread" y="14" width="1.5" height="2" rx="1" :fill="data.faceColor" />
+        </g>
+        <rect width="36" height="36" :fill="`url(#${ditherId})`" />
+      </g>
+    </svg>
+  </span>
+</template>
+
+<style scoped>
+.ui-dither-avatar {
+  background: var(--ui-bg-elevated);
+}
+</style>

package/app/components/element/UiDotLabel.vue

@@ -0,0 +1,19 @@
+<script setup lang="ts">
+const { dotClass, dotSize = '1.5', label } = defineProps<{
+  /** Tailwind bg class for the dot, e.g. 'bg-blue-500' or vizDotColor key result */
+  dotClass: string
+  /** Dot size token: '1.5' (default, inline/legend), '2' (medium), '2.5' (hero) */
+  dotSize?: '1.5' | '2' | '2.5'
+  /** Optional text label rendered after the dot */
+  label?: string
+}>()
+</script>
+
+<template>
+  <span class="inline-flex items-center gap-1.5">
+    <span class="rounded-full shrink-0" :class="[dotClass, `size-${dotSize}`]" aria-hidden="true" />
+    <slot>
+      <span v-if="label">{{ label }}</span>
+    </slot>
+  </span>
+</template>

package/app/components/element/UiEjectMenu.vue

@@ -0,0 +1,181 @@
+<script setup lang="ts">
+import type { DropdownMenuItem } from '@nuxt/ui'
+import type { RouteLocationRaw } from 'vue-router'
+import type { EjectAction, EjectChat, EjectLink, EjectMcp } from './eject-menu'
+import type { EjectTrackAction } from './eject-tracker'
+import { useClipboard } from '@vueuse/core'
+import { useRoute, useState } from 'nuxt/app'
+import { computed } from 'vue'
+import { UDropdownMenu, UiButton } from '#components'
+import { useToast } from '#imports'
+import { buildChatDeepLinkQuery, serializeCliCommand, serializeMcpCall } from './eject-menu'
+import { useEjectTracker } from './eject-tracker'
+
+const {
+  mcp,
+  chat,
+  schema,
+  actions,
+  track,
+  size = 'xs',
+  align = 'end',
+} = defineProps<{
+  /**
+   * The eject payload. Always the structured shape: the menu derives the CLI
+   * command from `tool` + `site` through `serializeCliCommand`, so a
+   * pre-serialised string would silently cost the row its CLI item. There is
+   * deliberately no `cli` prop — every copied command comes from the one
+   * serialiser, which is what keeps `--site` on all of them.
+   */
+  mcp?: EjectMcp
+  chat?: EjectChat
+  schema?: EjectLink
+  actions?: EjectAction[]
+  /** Optional call-site enrichment for eject telemetry (the menu fills action + surface). */
+  track?: { kind?: string, variant?: string }
+  size?: 'xs' | 'sm' | 'md'
+  align?: 'start' | 'center' | 'end'
+}>()
+
+const emit = defineEmits<{
+  select: [action: EjectTrackAction]
+}>()
+
+const toast = useToast()
+const { copy } = useClipboard({ legacy: true })
+
+// Auto-report every code-eject through the design-system telemetry seam.
+// pro-features provides the sink (→ trackPromptEject); absent a provider this
+// no-ops, so the menu stays usable outside the pro app.
+const trackEject = useEjectTracker()
+function fire(action: EjectTrackAction) {
+  trackEject({ action, kind: track?.kind, variant: track?.variant })
+  emit('select', action)
+}
+
+// Per-user AI opt-out (written by useAiSettings via the dashboard layouts). When
+// off, drop the LLM-bound eject items (MCP call + AI chat); cURL/CLI/schema stay.
+const aiEnabled = useState<boolean>('pro:ai-enabled', () => true)
+// Site layouts set this from the same monitoring policy used by navigation and
+// server work fences. Non-site surfaces retain the compatibility default.
+const siteAiAvailable = useState<boolean>('pro:ai-site-available', () => true)
+
+async function copyAs(label: string, payload: string) {
+  await copy(payload)
+  toast.add({
+    title: `${label} copied`,
+    icon: 'check',
+    color: 'success',
+    duration: 2000,
+  })
+}
+
+// URL contract is owned by layers/chat/app/internal/schemas/chat-deep-link.ts;
+// the query itself is built by buildChatDeepLinkQuery so the surface's own query
+// state (tabs, filters, sort) survives the eject.
+const route = useRoute()
+
+// Author-time guard for the entity mistake the ChatEntityRef template type
+// can't catch: a raw URL, whose "https" prefix satisfies `${string}:${string}`
+// but is no registered hydrate scheme — the eject would silently lose its
+// grounding. Wrap with chatEntity.page(url) instead.
+if (import.meta.dev && chat?.entity) {
+  const scheme = chat.entity.slice(0, chat.entity.indexOf(':'))
+  if (!/^[a-z][a-z-]*$/.test(scheme) || scheme === 'http' || scheme === 'https')
+    console.warn(`[UiEjectMenu] chat.entity "${chat.entity}" has no registered hydrate scheme — build it via chatEntity.* (eject-menu.ts) or hydration silently skips.`)
+}
+
+function buildChatTarget(c: EjectChat): RouteLocationRaw {
+  // No explicit target: navigate to the current route with the deep-link keys
+  // merged over its existing query, which the in-place slide-over picks up and
+  // self-opens on.
+  if (!c.to)
+    return { query: buildChatDeepLinkQuery(route.query, c) }
+  if (typeof c.to === 'string')
+    return { path: c.to, query: buildChatDeepLinkQuery({}, c) }
+  return { ...c.to, query: buildChatDeepLinkQuery(c.to.query ?? {}, c) }
+}
+
+// ADR-0124: the CLI leads the eject set. It is NOT gated on `aiEnabled` —
+// a terminal command is not an LLM call, the same reason cURL/schema stay.
+const cliCommand = computed<string | null>(() => mcp ? serializeCliCommand(mcp) : null)
+
+const ejectItems = computed<DropdownMenuItem[]>(() => {
+  const out: DropdownMenuItem[] = []
+  if (cliCommand.value) {
+    const command = cliCommand.value
+    out.push({
+      label: 'Copy as CLI command',
+      icon: 'terminal',
+      onSelect: () => {
+        fire('copy-cli')
+        copyAs('CLI command', command)
+      },
+    })
+  }
+  if (mcp && aiEnabled.value) {
+    const payload = serializeMcpCall(mcp)
+    out.push({
+      label: 'Copy as MCP call',
+      icon: 'plug',
+      onSelect: () => {
+        fire('copy-mcp')
+        copyAs('MCP call', payload)
+      },
+    })
+  }
+  if (chat && aiEnabled.value && siteAiAvailable.value) {
+    out.push({
+      label: 'Open in AI Chat',
+      icon: 'bot',
+      to: buildChatTarget(chat),
+      onSelect: () => fire('open-chat'),
+    })
+  }
+  if (schema) {
+    out.push({
+      label: schema.label ?? 'View API schema',
+      icon: 'braces',
+      to: schema.to,
+      onSelect: () => fire('view-schema'),
+    })
+  }
+  return out
+})
+
+const actionItems = computed<DropdownMenuItem[]>(() =>
+  (actions ?? []).map(a => ({ label: a.label, icon: a.icon, disabled: a.disabled, onSelect: a.onSelect })),
+)
+
+// Actions lead, eject-to-code follows; grouped (nested arrays) so @nuxt/ui draws
+// a separator between them. Either group alone renders flat.
+const items = computed<DropdownMenuItem[] | DropdownMenuItem[][]>(() => {
+  if (actionItems.value.length && ejectItems.value.length)
+    return [actionItems.value, ejectItems.value]
+  return actionItems.value.length ? actionItems.value : ejectItems.value
+})
+
+// Render whenever there are items. We deliberately DON'T gate on clipboard
+// `isSupported`: it's false during SSR and true on the client, so gating here
+// makes the menu (and every reka dropdown id after it) diverge across hydration.
+// `useClipboard({ legacy: true })` falls back to execCommand, so copy still works
+// where the async Clipboard API is unavailable.
+const hasAny = computed(() => actionItems.value.length > 0 || ejectItems.value.length > 0)
+</script>
+
+<template>
+  <UDropdownMenu
+    v-if="hasAny"
+    :items="items"
+    :content="{ align, sideOffset: 6 }"
+    :ui="{ content: 'ui-popover-content' }"
+  >
+    <UiButton
+      purpose="quiet"
+      :size="size"
+      icon="more-horizontal"
+      aria-label="Eject this view to code"
+      class="min-h-11 min-w-11 sm:min-h-0 sm:min-w-0"
+    />
+  </UDropdownMenu>
+</template>

package/app/components/element/UiEjectOverlay.vue

@@ -0,0 +1,29 @@
+<script setup lang="ts">
+import type { EjectChat, EjectLink, EjectMcp } from './eject-menu'
+import { UiEjectMenu } from '#components'
+
+/**
+ * Hover-revealed eject affordance pinned to the top-right corner of a chart or
+ * card that has no header to host a `<UiEjectMenu>` (ProCardGsc, the CWV grid,
+ * funnels, …). Wrap the visual; the `⋯` overlays its corner, fading in on hover
+ * so it doesn't spend layout or attention until wanted.
+ *
+ * Touch devices (no hover) always show it — `[@media(hover:none)]` — and keyboard
+ * users get it via `focus-within`. The wrapper owns the positioning context, so
+ * the wrapped element must fill it (the default block flow does).
+ */
+defineProps<{
+  chat?: EjectChat
+  mcp?: EjectMcp
+  schema?: EjectLink
+}>()
+</script>
+
+<template>
+  <div class="group/eject relative">
+    <slot />
+    <div class="absolute top-2 right-2 z-10 opacity-0 transition-opacity group-hover/eject:opacity-100 focus-within:opacity-100 [@media(hover:none)]:opacity-100">
+      <UiEjectMenu :chat="chat" :mcp="mcp" :schema="schema" />
+    </div>
+  </div>
+</template>

package/app/components/element/UiFavicon.vue

@@ -0,0 +1,235 @@
+<script setup lang="ts">
+import { computed, ref, useAttrs, useTemplateRef, watch } from 'vue'
+import { UiIcon } from '#components'
+import { useFaviconBacking } from '../../composables/useFaviconBacking'
+import { faviconFallbackInitial, faviconProxyPath, isBlankFaviconSize } from '../../utils/favicon-fallback'
+
+// Three conditional root branches below (loading / fallback / favicon) mean
+// Vue's automatic single-root attrs fallthrough is unreliable across SSR vs
+// client hydration — callers commonly pass `class="shrink-0 rounded ..."`
+// straight onto `<UiFavicon>`, and the SSR render silently dropped it while
+// the client vdom kept it, producing a "Hydration class mismatch" warning on
+// every favicon call site that passes a class (UiSkeleton uses the same fix
+// for the same reason). Forward `class` explicitly and identically on every
+// branch instead of relying on implicit fallthrough.
+defineOptions({ inheritAttrs: false })
+
+/**
+ * Site favicon with a deterministic initials fallback. Google s2 favicons fail,
+ * 404 to a generic globe, or are indistinguishable across related domains, so on
+ * load error (or a missing domain) we render a neutral box with the registrable
+ * name's first letter. Always pair with the site/group label in the caller — the
+ * favicon is identity reinforcement, never the sole identifier.
+ *
+ * Accepts a bare hostname, a full URL, or an `sc-domain:` GSC property; all are
+ * normalised to a hostname, so callers don't need to pre-strip.
+ *
+ * Served through `/api/favicon` (same-origin proxy) so the image can be sampled
+ * on a canvas for an adaptive contrast tile — see useFaviconBacking. Favicons
+ * whose ink would vanish against the current theme (e.g. a black glyph on the
+ * dark sidebar) get a `bg-inverted` tile in that theme only; everything else
+ * renders bare and keeps its brand colour.
+ */
+const { domain, size = 20, alt = '', loading = false, decorative = false, fallbackLabel = '', fallbackSurface = 'neutral', dither = false } = defineProps<{
+  domain: string
+  size?: number
+  alt?: string
+  /** Render a spinner in place of the favicon (e.g. while the site is being
+   *  validated/added). Keeps the same footprint so the row doesn't shift. */
+  loading?: boolean
+  /** The site name is already shown as adjacent text — mark the favicon
+   *  `aria-hidden` so screen readers don't announce the host twice. */
+  decorative?: boolean
+  /** Prefer this visible Site label when deriving the fallback initial. */
+  fallbackLabel?: string
+  /** Let a first-party identity wrapper supply the fallback surface. */
+  fallbackSurface?: 'neutral' | 'transparent'
+  /**
+   * Quiet monochrome mark for rows that shouldn't compete with a heavier
+   * sibling column (Overview's Next Actions / Recent Activity beside Sites).
+   * CSS-only: desaturates and softens the image and stipples it with a fine
+   * dot mask. The fallback initial keeps the same opacity but no mask — a
+   * single letter has nothing to lose by disappearing into dots.
+   */
+  dither?: boolean
+}>()
+
+const cleanDomain = computed(() =>
+  (domain ?? '')
+    .replace(/^sc-domain:/, '')
+    .replace(/^https?:\/\//, '')
+    .replace(/\/.*$/, '')
+    .trim(),
+)
+const src = computed(() => faviconProxyPath(cleanDomain.value))
+
+// Decorative favicons (the caller already shows the site name as text) go
+// `aria-hidden` so the host isn't announced twice; otherwise expose it as an image.
+const a11y = computed(() =>
+  decorative
+    ? { 'aria-hidden': 'true' as const }
+    : { 'role': 'img', 'aria-label': alt || cleanDomain.value || 'Unknown site' },
+)
+
+const failed = ref(false)
+const faviconImage = useTemplateRef<HTMLImageElement>('faviconImage')
+// SSR images can finish before hydration attaches load and error listeners.
+// Reconcile their actual DOM state after each source update: a blank image
+// falls back, and a loaded one is sampled for its backing, because its `load`
+// event never reaches `handleLoad`.
+watch([cleanDomain, faviconImage], () => {
+  const image = faviconImage.value
+  if (!image?.complete)
+    return
+  if (image.naturalWidth === 0 || isBlankFaviconSize(image.naturalWidth, image.naturalHeight))
+    failed.value = true
+  else
+    sample(image)
+}, { flush: 'post' })
+// Reset the error state if the domain changes (list rows reuse the node).
+watch(cleanDomain, () => { failed.value = false })
+
+const initial = computed(() => faviconFallbackInitial(fallbackLabel, cleanDomain.value))
+const showFallback = computed(() => failed.value || !cleanDomain.value)
+
+// We never touch the favicon — it always renders at full size and pops. The
+// contrast fix is purely a background placed *behind* it, which shows through the
+// favicon's transparent areas. `bg-inverted` is theme-aware (light on dark themes,
+// dark on light themes) and we only ever render the chip in the theme where the
+// favicon would vanish, so a single softened token covers both cases: the 80%
+// opacity keeps it a muted chip rather than a stark card while staying light/dark
+// enough for the glyph to read.
+const { backing, sample } = useFaviconBacking(() => cleanDomain.value)
+function handleLoad(event: Event) {
+  const image = event.currentTarget
+  if (!(image instanceof HTMLImageElement))
+    return
+  if (isBlankFaviconSize(image.naturalWidth, image.naturalHeight)) {
+    failed.value = true
+    return
+  }
+  sample(image)
+}
+const attrs = useAttrs()
+</script>
+
+<template>
+  <span
+    v-if="loading"
+    v-bind="attrs"
+    class="inline-flex items-center justify-center shrink-0 text-muted"
+    :style="{ width: `${size}px`, height: `${size}px` }"
+    role="img"
+    :aria-label="alt || cleanDomain || 'Loading'"
+  >
+    <UiIcon name="loading" class="animate-spin motion-reduce:animate-none" :style="{ width: `${size}px`, height: `${size}px` }" />
+  </span>
+  <span
+    v-else-if="showFallback"
+    v-bind="{ ...attrs, ...a11y }"
+    class="inline-flex items-center justify-center rounded border font-semibold shrink-0 leading-none select-none"
+    :class="[
+      fallbackSurface === 'transparent'
+        ? 'border-transparent bg-transparent'
+        : 'border-default bg-elevated text-muted',
+      dither ? 'ui-favicon-dither-fallback' : '',
+    ]"
+    :style="{ width: `${size}px`, height: `${size}px`, fontSize: `${Math.round(size * 0.5)}px` }"
+  >{{ initial }}</span>
+  <!--
+    Always the SAME element shape (span > img) regardless of `backing` — only
+    its classes react. `backing` flips from a client-only canvas sample
+    (`useFaviconBacking`) that can resolve via `onMounted`/`load` before a
+    later same-domain favicon elsewhere on the page finishes its OWN hydration
+    compare (Suspense-chunked hydration interleaves mount callbacks between
+    chunks). A `v-if`/`v-else` swap between a bare `<img>` and a wrapping
+    `<span>` turned that race into a STRUCTURAL SSR/client mismatch — extra
+    wrapper element, not just a class — which cascades into 6-7 "Hydration
+    node/children mismatch" warnings per row (every repeated favicon site
+    board / portfolio queue row renders). A class-only toggle can never
+    mismatch this way: attribute differences patch silently, node-count
+    differences don't happen because the node never comes or goes.
+  -->
+  <span
+    v-else
+    v-bind="attrs"
+    class="inline-grid place-items-center rounded shrink-0"
+    :class="[backing !== 'none' ? 'bg-inverted/80 ring-1 ring-default' : '', dither ? 'ui-favicon-dithered' : '']"
+    :style="{ width: `${size}px`, height: `${size}px` }"
+  >
+    <img
+      ref="faviconImage"
+      :src="src"
+      :alt="decorative ? '' : alt"
+      :aria-hidden="decorative ? 'true' : undefined"
+      :width="size"
+      :height="size"
+      loading="lazy"
+      decoding="async"
+      class="rounded"
+      :class="dither ? 'ui-favicon-dither' : ''"
+      @load="handleLoad"
+      @error="failed = true"
+    >
+  </span>
+</template>
+
+<style scoped>
+/*
+ * `dither` — a quiet mark for rows beside a heavier sibling column. Two
+ * layers, both transitionable: the image loses most of its saturation and
+ * some contrast, and a 2px stipple of the page background sits over it so a
+ * saturated brand mark reads as texture rather than a pop of colour. Colour
+ * is muted, never removed: at a glance the mark stays recognisable. Hovering
+ * the row (any `a`, `button`, or `.group` ancestor) fades both layers away,
+ * so the favicon comes back to full colour under the pointer.
+ */
+.ui-favicon-dithered {
+  position: relative;
+  isolation: isolate;
+}
+
+.ui-favicon-dithered::after {
+  content: '';
+  position: absolute;
+  inset: 0;
+  border-radius: inherit;
+  background-image: radial-gradient(circle, var(--ui-bg) 38%, transparent 44%);
+  background-size: 2px 2px;
+  opacity: .55;
+  pointer-events: none;
+  transition: opacity 180ms var(--ease-standard, ease);
+}
+
+.ui-favicon-dither {
+  filter: saturate(.35) contrast(.9) opacity(.85);
+  transition: filter 180ms var(--ease-standard, ease);
+}
+
+:is(a, button, .group):hover .ui-favicon-dithered::after {
+  opacity: 0;
+}
+
+:is(a, button, .group):hover .ui-favicon-dither {
+  filter: none;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .ui-favicon-dithered::after,
+  .ui-favicon-dither {
+    transition: none;
+  }
+}
+
+/* The fallback initial is text, not an image — dropping its opacity to match
+   is enough to read as "quiet"; stippling a single letter makes it illegible
+   instead, which the dither treatment must never do. */
+.ui-favicon-dither-fallback {
+  opacity: .7;
+  transition: opacity 180ms var(--ease-standard, ease);
+}
+
+:is(a, button, .group):hover .ui-favicon-dither-fallback {
+  opacity: 1;
+}
+</style>