fix(ui): reduce cls to 0 on package page (#1304)

.lighthouserc.cjs

···
       chromePath: findChrome(),
       puppeteerScript: './lighthouse-setup.cjs',
       settings: {
-        onlyCategories: ['accessibility'],
+        onlyCategories: process.env.LH_PERF ? ['performance'] : ['accessibility'],
         skipAudits: ['valid-source-maps'],
       },
     },
     assert: {
-      assertions: {
-        'categories:accessibility': ['error', { minScore: 1 }],
-      },
+      assertions: process.env.LH_PERF
+        ? {
+            'cumulative-layout-shift': ['error', { maxNumericValue: 0 }],
+          }
+        : {
+            'categories:accessibility': ['error', { minScore: 1 }],
+          },
     },
     upload: {
       target: 'temporary-public-storage',

CONTRIBUTING.md

···
   - [Unit tests](#unit-tests)
   - [Component accessibility tests](#component-accessibility-tests)
   - [Lighthouse accessibility tests](#lighthouse-accessibility-tests)
+  - [Lighthouse performance tests](#lighthouse-performance-tests)
   - [End to end tests](#end-to-end-tests)
   - [Test fixtures (mocking external APIs)](#test-fixtures-mocking-external-apis)
 - [Submitting changes](#submitting-changes)
···
 pnpm test:nuxt        # Nuxt component tests
 pnpm test:browser     # Playwright E2E tests
 pnpm test:a11y        # Lighthouse accessibility audits
+pnpm test:perf        # Lighthouse performance audits (CLS)
 ```
 
 ### Project structure
···
 
 # Or run a single color mode manually
 pnpm build:test
-LIGHTHOUSE_COLOR_MODE=dark ./scripts/lighthouse-a11y.sh
+LIGHTHOUSE_COLOR_MODE=dark ./scripts/lighthouse.sh
 ```
 
 This requires Chrome or Chromium to be installed. The script will auto-detect common installation paths. Results are printed to the terminal and saved in `.lighthouseci/`.
 
 #### Configuration
 
-| File                         | Purpose                                                   |
-| ---------------------------- | --------------------------------------------------------- |
-| `.lighthouserc.cjs`          | Lighthouse CI config (URLs, assertions, Chrome path)      |
-| `lighthouse-setup.cjs`       | Puppeteer script for color mode + client-side API mocking |
-| `scripts/lighthouse-a11y.sh` | Shell wrapper that runs the audit for a given color mode  |
+| File                    | Purpose                                                   |
+| ----------------------- | --------------------------------------------------------- |
+| `.lighthouserc.cjs`     | Lighthouse CI config (URLs, assertions, Chrome path)      |
+| `lighthouse-setup.cjs`  | Puppeteer script for color mode + client-side API mocking |
+| `scripts/lighthouse.sh` | Shell wrapper that runs the audit for a given color mode  |
+
+### Lighthouse performance tests
+
+The project also runs Lighthouse performance audits to enforce zero Cumulative Layout Shift (CLS). These run separately from the accessibility audits and test the same set of URLs.
+
+#### How it works
+
+The same `.lighthouserc.cjs` config is shared between accessibility and performance audits. When the `LH_PERF` environment variable is set, the config switches from the `accessibility` category to the `performance` category and asserts that CLS is exactly 0.
+
+#### Running locally
+
+```bash
+# Build + run performance audit
+pnpm test:perf
+
+# Or against an existing test build
+pnpm test:perf:prebuilt
+```
+
+Unlike the accessibility audits, performance audits do not run in separate light/dark modes.
 
 ### End to end tests
 

app/components/Package/WeeklyDownloadStats.vue

···
         >
           <span class="sr-only">{{ $t('package.downloads.analyze') }}</span>
         </ButtonBase>
+        <span v-else-if="isLoadingWeeklyDownloads" class="min-w-6 min-h-6 -m-1 p-1" />
       </template>
 
       <div class="w-full overflow-hidden">
···
               </template>
             </VueUiSparkline>
             <template #fallback>
-              <!-- Skeleton matching sparkline layout: title row + chart with data label -->
-              <div class="min-h-[75.195px]">
-                <!-- Title row: date range (24px height) -->
+              <!-- Skeleton matching VueUiSparkline layout (title 24px + SVG aspect 500:80) -->
+              <div class="max-w-xs">
+                <!-- Title row: fontSize * 2 = 24px -->
                 <div class="h-6 flex items-center ps-3">
                   <SkeletonInline class="h-3 w-36" />
                 </div>
-                <!-- Chart area: data label left, sparkline right -->
+                <!-- Chart area: matches SVG viewBox 500:80 -->
                 <div class="aspect-[500/80] flex items-center">
-                  <!-- Data label (covers ~42% width) -->
+                  <!-- Data label (covers ~42% width, matching dataLabel.offsetX) -->
                   <div class="w-[42%] flex items-center ps-0.5">
                     <SkeletonInline class="h-7 w-24" />
                   </div>
-                  <!-- Sparkline area (~58% width) -->
-                  <div class="flex-1 flex items-end gap-0.5 h-4/5 pe-3">
-                    <SkeletonInline
-                      v-for="i in 16"
-                      :key="i"
-                      class="flex-1 rounded-sm"
-                      :style="{ height: `${25 + ((i * 7) % 50)}%` }"
-                    />
+                  <!-- Sparkline line placeholder -->
+                  <div class="flex-1 flex items-end pe-3">
+                    <SkeletonInline class="h-px w-full" />
                   </div>
                 </div>
               </div>

app/pages/about.vue

···
 const router = useRouter()
 const canGoBack = useCanGoBack()
 
-interface GitHubContributor {
-  login: string
-  id: number
-  avatar_url: string
-  html_url: string
-  contributions: number
-}
-
 useSeoMeta({
   title: () => `${$t('about.title')} - npmx`,
   ogTitle: () => `${$t('about.title')} - npmx`,
···
   vlt: 'https://www.vlt.sh/',
 }
 
-const { data: contributors, status: contributorsStatus } = useFetch<GitHubContributor[]>(
-  '/api/contributors',
-  {
-    lazy: true,
-  },
-)
+const { data: contributors, status: contributorsStatus } = useLazyFetch('/api/contributors')
 </script>
 
 <template>

app/pages/package/[[org]]/[name].vue

···
 import { useModal } from '~/composables/useModal'
 import { useAtproto } from '~/composables/atproto/useAtproto'
 import { togglePackageLike } from '~/utils/atproto/likes'
-import { LinkBase } from '#components'
 
 defineOgImageComponent('Package', {
   name: () => packageName.value,
···
   )
 }
 
-const provenanceBadgeMounted = shallowRef(false)
-onMounted(() => {
-  provenanceBadgeMounted.value = true
-})
+const isMounted = useMounted()
 
 // Keep latestVersion for comparison (to show "(latest)" badge)
 const latestVersion = computed(() => {
···
   },
 )
 const isLoadingLikeData = computed(
-  () => likeStatus.value !== 'error' && likeStatus.value !== 'success',
+  () => likeStatus.value === 'pending' || likeStatus.value === 'idle',
 )
 
 const isLikeActionPending = shallowRef(false)
···
             >
             <span dir="ltr" v-else>v{{ resolvedVersion }}</span>
 
-            <template v-if="hasProvenance(displayVersion) && provenanceBadgeMounted">
+            <template v-if="hasProvenance(displayVersion)">
               <TooltipApp
                 :text="
                   provenanceData && provenanceStatus !== 'pending'
···
           </ButtonGroup>
 
           <!-- Package metrics -->
-          <div class="basis-full flex gap-2 sm:gap-3 flex-wrap">
-            <ClientOnly>
-              <PackageMetricsBadges
-                v-if="resolvedVersion"
-                :package-name="pkg.name"
-                :version="resolvedVersion"
-                :is-binary="isBinaryOnly"
-                class="self-baseline"
-              />
+          <div class="basis-full flex gap-2 sm:gap-3 flex-wrap items-stretch">
+            <PackageMetricsBadges
+              v-if="resolvedVersion"
+              :package-name="pkg.name"
+              :version="resolvedVersion"
+              :is-binary="isBinaryOnly"
+              class="self-baseline"
+            />
 
-              <!-- Package likes -->
-              <TooltipApp
-                :text="
-                  isLoadingLikeData
-                    ? $t('common.loading')
-                    : likesData?.userHasLiked
-                      ? $t('package.likes.unlike')
-                      : $t('package.likes.like')
+            <!-- Package likes -->
+            <TooltipApp
+              :text="
+                isLoadingLikeData
+                  ? $t('common.loading')
+                  : likesData?.userHasLiked
+                    ? $t('package.likes.unlike')
+                    : $t('package.likes.like')
+              "
+              position="bottom"
+              class="items-center"
+            >
+              <ButtonBase
+                @click="likeAction"
+                size="small"
+                :title="
+                  likesData?.userHasLiked ? $t('package.likes.unlike') : $t('package.likes.like')
                 "
-                position="bottom"
-                class="items-center"
+                :aria-label="
+                  likesData?.userHasLiked ? $t('package.likes.unlike') : $t('package.likes.like')
+                "
+                :aria-pressed="likesData?.userHasLiked"
+                :classicon="
+                  likesData?.userHasLiked
+                    ? 'i-lucide-heart-minus text-red-500'
+                    : 'i-lucide-heart-plus'
+                "
               >
                 <span
                   v-if="isLoadingLikeData"
-                  class="i-carbon-circle-dash w-3 h-3 motion-safe:animate-spin"
+                  class="i-carbon-circle-dash w-3 h-3 motion-safe:animate-spin my-0.5"
                   aria-hidden="true"
                 />
-                <ButtonBase
-                  v-else
-                  @click="likeAction"
-                  size="small"
-                  :title="
-                    likesData?.userHasLiked ? $t('package.likes.unlike') : $t('package.likes.like')
-                  "
-                  :aria-label="
-                    likesData?.userHasLiked ? $t('package.likes.unlike') : $t('package.likes.like')
-                  "
-                  :aria-pressed="likesData?.userHasLiked"
-                  :classicon="
-                    likesData?.userHasLiked
-                      ? 'i-lucide-heart-minus text-red-500'
-                      : 'i-lucide-heart-plus'
-                  "
-                >
+                <span v-else>
                   {{ compactNumberFormatter.format(likesData?.totalLikes ?? 0) }}
-                </ButtonBase>
-              </TooltipApp>
-              <template #fallback>
-                <div class="flex items-center gap-1.5 list-none m-0 p-0 self-baseline">
-                  <SkeletonBlock class="w-16 h-5.5 rounded" />
-                  <SkeletonBlock class="w-13 h-5.5 rounded" />
-                  <SkeletonBlock class="w-13 h-5.5 rounded" />
-                  <SkeletonBlock class="w-13 h-5.5 rounded bg-bg-subtle" />
-                </div>
-              </template>
-            </ClientOnly>
+                </span>
+              </ButtonBase>
+            </TooltipApp>
           </div>
         </div>
       </header>
···
       <section :class="$style.areaDetails">
         <div class="mb-4">
           <!-- Description container with min-height to prevent CLS -->
-          <div class="max-w-2xl min-h-[4.5rem]">
+          <div class="max-w-2xl">
             <p v-if="pkgDescription" class="text-fg-muted text-base m-0">
               <span v-html="pkgDescription" />
             </p>
···
                 {{ compactNumberFormatter.format(forks) }}
               </LinkBase>
             </li>
+            <li class="basis-full sm:hidden" />
             <li v-if="homepageUrl">
               <LinkBase :to="homepageUrl" classicon="i-carbon:link">
                 {{ $t('package.links.homepage') }}
···
           </div>
 
           <!-- Vulnerabilities count -->
-          <ClientOnly>
-            <div class="space-y-1 sm:col-span-2">
-              <dt class="text-xs text-fg-subtle uppercase tracking-wider">
-                {{ $t('package.stats.vulns') }}
-              </dt>
-              <dd class="font-mono text-sm text-fg">
+          <div class="space-y-1 sm:col-span-2">
+            <dt class="text-xs text-fg-subtle uppercase tracking-wider">
+              {{ $t('package.stats.vulns') }}
+            </dt>
+            <dd class="font-mono text-sm text-fg">
+              <span
+                v-if="vulnTreeStatus === 'pending' || vulnTreeStatus === 'idle'"
+                class="inline-flex items-center gap-1 text-fg-subtle"
+              >
                 <span
-                  v-if="vulnTreeStatus === 'pending' || vulnTreeStatus === 'idle'"
-                  class="inline-flex items-center gap-1 text-fg-subtle"
-                >
-                  <span
-                    class="i-carbon:circle-dash w-3 h-3 motion-safe:animate-spin"
-                    aria-hidden="true"
-                  />
+                  class="i-carbon:circle-dash w-3 h-3 motion-safe:animate-spin"
+                  aria-hidden="true"
+                />
+              </span>
+              <span v-else-if="vulnTreeStatus === 'success'">
+                <span v-if="hasVulnerabilities" class="text-amber-500">
+                  {{ numberFormatter.format(vulnCount) }}
                 </span>
-                <span v-else-if="vulnTreeStatus === 'success'">
-                  <span v-if="hasVulnerabilities" class="text-amber-500">
-                    {{ numberFormatter.format(vulnCount) }}
-                  </span>
-                  <span v-else class="inline-flex items-center gap-1 text-fg-muted">
-                    <span class="i-carbon:checkmark w-3 h-3" aria-hidden="true" />
-                    {{ numberFormatter.format(0) }}
-                  </span>
+                <span v-else class="inline-flex items-center gap-1 text-fg-muted">
+                  <span class="i-carbon:checkmark w-3 h-3" aria-hidden="true" />
+                  {{ numberFormatter.format(0) }}
                 </span>
-                <span v-else class="text-fg-subtle">-</span>
-              </dd>
-            </div>
-            <template #fallback>
-              <div class="space-y-1 sm:col-span-2">
-                <dt class="text-xs text-fg-subtle uppercase tracking-wider">
-                  {{ $t('package.stats.vulns') }}
-                </dt>
-                <dd class="font-mono text-sm text-fg-subtle">-</dd>
-              </div>
-            </template>
-          </ClientOnly>
+              </span>
+              <span v-else class="text-fg-subtle">-</span>
+            </dd>
+          </div>
 
           <div
             v-if="resolvedVersion && pkg.time?.[resolvedVersion]"
···
               {{ $t('package.readme.title') }}
             </LinkBase>
           </h2>
-          <ClientOnly>
-            <div class="flex gap-2">
-              <!-- Copy readme as Markdown button -->
-              <TooltipApp
-                v-if="readmeData?.md"
-                :text="$t('package.readme.copy_as_markdown')"
-                position="bottom"
+          <div class="flex gap-2">
+            <!-- Copy readme as Markdown button -->
+            <TooltipApp
+              v-if="readmeData?.md"
+              :text="$t('package.readme.copy_as_markdown')"
+              position="bottom"
+            >
+              <ButtonBase
+                @click="copyReadme()"
+                :aria-pressed="copiedReadme"
+                :aria-label="
+                  copiedReadme ? $t('common.copied') : $t('package.readme.copy_as_markdown')
+                "
+                :classicon="copiedReadme ? 'i-carbon:checkmark' : 'i-simple-icons:markdown'"
               >
-                <ButtonBase
-                  @click="copyReadme()"
-                  :aria-pressed="copiedReadme"
-                  :aria-label="
-                    copiedReadme ? $t('common.copied') : $t('package.readme.copy_as_markdown')
-                  "
-                  :classicon="copiedReadme ? 'i-carbon:checkmark' : 'i-simple-icons:markdown'"
-                >
-                  {{ copiedReadme ? $t('common.copied') : $t('common.copy') }}
-                </ButtonBase>
-              </TooltipApp>
-              <ReadmeTocDropdown
-                v-if="readmeData?.toc && readmeData.toc.length > 1"
-                :toc="readmeData.toc"
-                :active-id="activeTocId"
-              />
-            </div>
-          </ClientOnly>
+                {{ copiedReadme ? $t('common.copied') : $t('common.copy') }}
+              </ButtonBase>
+            </TooltipApp>
+            <ReadmeTocDropdown
+              v-if="readmeData?.toc && readmeData.toc.length > 1"
+              :toc="readmeData.toc"
+              :active-id="activeTocId"
+            />
+          </div>
         </div>
 
         <!-- eslint-disable vue/no-v-html -- HTML is sanitized server-side -->
···
         </p>
 
         <section
-          v-if="hasProvenance(displayVersion) && provenanceBadgeMounted"
+          v-if="hasProvenance(displayVersion) && isMounted"
           id="provenance"
           class="scroll-mt-20"
         >
···
           <!-- Team access controls (for scoped packages when connected) -->
           <ClientOnly>
             <PackageAccessControls :package-name="pkg.name" />
+            <template #fallback>
+              <!-- Show skeleton loaders when SSR or access controls are loading -->
+            </template>
           </ClientOnly>
 
           <!-- Agent Skills -->
···
               :package-name="pkg.name"
               :version="resolvedVersion || undefined"
             />
+            <template #fallback>
+              <!-- Show skeleton loaders when SSR or access controls are loading -->
+            </template>
           </ClientOnly>
 
           <!-- Download stats -->

package.json

···
     "generate:lexicons": "lex build --lexicons lexicons --out shared/types/lexicons --clear",
     "test": "vite test",
     "test:a11y": "pnpm build:test && LIGHTHOUSE_COLOR_MODE=dark pnpm test:a11y:prebuilt && LIGHTHOUSE_COLOR_MODE=light pnpm test:a11y:prebuilt",
-    "test:a11y:prebuilt": "./scripts/lighthouse-a11y.sh",
+    "test:a11y:prebuilt": "./scripts/lighthouse.sh",
+    "test:perf": "pnpm build:test && pnpm test:perf:prebuilt",
+    "test:perf:prebuilt": "LH_PERF=1 ./scripts/lighthouse.sh",
     "test:browser": "pnpm build:test && pnpm test:browser:prebuilt",
     "test:browser:prebuilt": "playwright test",
     "test:browser:ui": "pnpm build:test && pnpm test:browser:prebuilt --ui",

scripts/lighthouse-a11y.sh

···
-#!/bin/bash
-# Run Lighthouse accessibility tests in both light and dark mode
-#
-# This script runs lhci autorun twice, once for each color mode.
-# The LIGHTHOUSE_COLOR_MODE env var is read by lighthouse-setup.cjs
-# to set the appropriate theme before each audit.
-
-set -e
-
-case "${LIGHTHOUSE_COLOR_MODE}" in
-  dark)
-    echo "🌙 Running Lighthouse accessibility audit (dark mode)..."
-    pnpx @lhci/cli autorun --upload.githubStatusContextSuffix="/dark"
-    ;;
-  light)
-    echo "☀️ Running Lighthouse accessibility audit (light mode)..."
-    pnpx @lhci/cli autorun --upload.githubStatusContextSuffix="/light"
-    ;;
-  *)
-    echo "⚠️ Missing or invalid LIGHTHOUSE_COLOR_MODE. Use 'dark' or 'light'."
-    exit 1
-    ;;
-esac
-
-echo ""
-echo "✅ Accessibility audit completed"

scripts/lighthouse.sh

···
+#!/bin/bash
+# Run Lighthouse CI audits.
+#
+# Modes:
+#   - Accessibility (default): requires LIGHTHOUSE_COLOR_MODE (dark/light)
+#   - Performance: set LH_PERF=1 (no color mode needed)
+#
+# The LIGHTHOUSE_COLOR_MODE env var is read by lighthouse-setup.cjs
+# to set the appropriate theme before each audit.
+
+set -e
+
+if [ -n "${LH_PERF}" ]; then
+  echo "⚡ Running Lighthouse performance audit (CLS)..."
+  pnpx @lhci/cli autorun --upload.githubStatusContextSuffix="/perf"
+  echo ""
+  echo "✅ Performance audit completed"
+  exit 0
+fi
+
+case "${LIGHTHOUSE_COLOR_MODE}" in
+  dark)
+    echo "🌙 Running Lighthouse accessibility audit (dark mode)..."
+    pnpx @lhci/cli autorun --upload.githubStatusContextSuffix="/dark"
+    ;;
+  light)
+    echo "☀️ Running Lighthouse accessibility audit (light mode)..."
+    pnpx @lhci/cli autorun --upload.githubStatusContextSuffix="/light"
+    ;;
+  *)
+    echo "⚠️ Missing or invalid LIGHTHOUSE_COLOR_MODE. Use 'dark' or 'light'."
+    exit 1
+    ;;
+esac
+
+echo ""
+echo "✅ Accessibility audit completed"