From 74c005063aff63c55d95e3e4db2ad0e8a9562d31 Mon Sep 17 00:00:00 2001
From: Harlan Wilton <harlan@harlanzw.com>
Date: Thu, 1 Oct 2026 13:38:05 +1000
Subject: [PATCH 1/4] perf(home): idle the noise field and rail when they cost
 frames

The hero ran a full-bleed WebGL shader at 60 fps and the rail scrolled at 30 fps for as long as the page stayed open. On a CPU renderer every frame became a long task, so NuxtSEO measured 12 to 17 s of TBT on mobile home and the page never reached idle. Both now start after hydration; the field draws one static frame on software WebGL and drops to 15 fps once its intro ends.
---
 app/components/NoiseField.client.vue | 106 ++++++++++++++++++++-------
 app/components/SkillSourceList.vue   |  36 ++++++---
 app/utils/webgl-context.ts           |  21 ++++++
 test/unit/webgl-context.test.ts      |  24 +++++-
 4 files changed, 149 insertions(+), 38 deletions(-)

diff --git a/app/components/NoiseField.client.vue b/app/components/NoiseField.client.vue
index 35de85b1..6ff531ea 100644
--- a/app/components/NoiseField.client.vue
+++ b/app/components/NoiseField.client.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import { useDocumentVisibility, useElementSize, useMouseInElement, useRafFn } from '@vueuse/core'
-import { isUsableWebGL2Context } from '../utils/webgl-context'
+import { isSoftwareRenderer, isUsableWebGL2Context, webglRendererName } from '../utils/webgl-context'
 
 const props = withDefaults(defineProps<{
   opacity?: number
@@ -212,24 +212,61 @@ const uniforms = {
 let startTime = 0
 let intersectionObserver: IntersectionObserver | null = null
 
-function initGL() {
+// The rings have faded by now and only the ambient shimmer moves. Its jitter
+// steps at 4 Hz, so a capped frame rate keeps it smooth for a fraction of the
+// GPU and main thread work. The cursor glow still runs at the display rate.
+const INTRO_SECONDS = 8
+const AMBIENT_FPS = 15
+
+const CONTEXT_ATTRIBUTES: WebGLContextAttributes = {
+  alpha: true,
+  premultipliedAlpha: false,
+  antialias: false,
+  powerPreference: 'low-power',
+}
+
+/**
+ * A browser without GPU acceleration (no GPU, a blocklisted driver, most
+ * headless browsers) runs WebGL on the CPU, and each frame of a full-bleed
+ * shader becomes a long task on the main thread. Some browsers refuse that
+ * context under `failIfMajorPerformanceCaveat`; Chrome hands out SwiftShader
+ * anyway, so the renderer name decides too. Either way the field draws one
+ * static frame.
+ */
+type FieldContext
+  = | { _tag: 'accelerated', gl: WebGL2RenderingContext }
+    | { _tag: 'software', gl: WebGL2RenderingContext }
+
+function createContext(canvas: HTMLCanvasElement): FieldContext | null {
+  const accelerated = canvas.getContext('webgl2', { ...CONTEXT_ATTRIBUTES, failIfMajorPerformanceCaveat: true })
+  if (isUsableWebGL2Context(accelerated))
+    return { _tag: isSoftwareRenderer(webglRendererName(accelerated)) ? 'software' : 'accelerated', gl: accelerated }
+  const software = canvas.getContext('webgl2', CONTEXT_ATTRIBUTES)
+  return isUsableWebGL2Context(software) ? { _tag: 'software', gl: software } : null
+}
+
+const isStatic = ref(false)
+const introDone = ref(false)
+// Software rendering pays per pixel on the CPU, so it draws at 1x.
+let maxDpr = 2
+
+function canvasDpr(): number {
+  return Math.min(window.devicePixelRatio || 1, maxDpr)
+}
+
+function initGL(): FieldContext['_tag'] | null {
   const canvas = canvasRef.value
   if (!canvas)
-    return false
-
-  const context = canvas.getContext('webgl2', {
-    alpha: true,
-    premultipliedAlpha: false,
-    antialias: false,
-    powerPreference: 'low-power',
-  })
-  if (!isUsableWebGL2Context(context))
-    return false
-  gl = context
+    return null
+
+  const context = createContext(canvas)
+  if (!context)
+    return null
+  gl = context.gl
 
   program = createProgram(gl, VERT, FRAG)
   if (!program)
-    return false
+    return null
 
   vao = gl.createVertexArray()
 
@@ -243,14 +280,14 @@ function initGL() {
   gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA)
   gl.clearColor(0, 0, 0, 0)
 
-  return true
+  return context._tag
 }
 
 function resizeCanvas() {
   const canvas = canvasRef.value
   if (!canvas || !gl)
     return
-  const dpr = window.devicePixelRatio || 1
+  const dpr = canvasDpr()
   const w = Math.round(width.value * dpr)
   const h = Math.round(height.value * dpr)
   if (canvas.width !== w || canvas.height !== h) {
@@ -266,8 +303,10 @@ function drawFrame() {
 
   resizeCanvas()
 
-  const dpr = window.devicePixelRatio || 1
-  const t = prefersReducedMotion.value ? 3.0 : (Date.now() - startTime) / 1000
+  const dpr = canvasDpr()
+  const t = isStatic.value ? 3.0 : (Date.now() - startTime) / 1000
+  if (t > INTRO_SECONDS)
+    introDone.value = true
 
   gl.clear(gl.COLOR_BUFFER_BIT)
   gl.useProgram(program)
@@ -280,7 +319,7 @@ function drawFrame() {
   gl.uniform1f(uniforms.u_dpr, dpr)
   gl.uniform1f(uniforms.u_dark, isDark.value ? 1.0 : 0.0)
 
-  if (isOutside.value || prefersReducedMotion.value) {
+  if (isOutside.value || isStatic.value) {
     gl.uniform2f(uniforms.u_mouse, -1, -1)
   }
   else {
@@ -296,17 +335,33 @@ const { pause, resume } = useRafFn(() => {
   if (visibility.value === 'hidden' || !isVisible.value)
     return
   drawFrame()
-}, { immediate: false })
+}, {
+  immediate: false,
+  fpsLimit: () => introDone.value && isOutside.value ? AMBIENT_FPS : null,
+})
+
+// A static frame has no loop, so it redraws when its box or theme changes.
+watch([width, height, isDark], () => {
+  if (isStatic.value)
+    drawFrame()
+})
+
+let disposed = false
 
-// Wait for canvas ref (client component timing)
-watch(canvasRef, (canvas) => {
-  if (!canvas || gl)
+// The field is decoration. It starts once the page has hydrated and the main
+// thread is idle, so it never competes with the first paint or hydration.
+onNuxtReady(() => {
+  if (disposed || gl)
     return
 
-  if (!initGL())
+  const mode = initGL()
+  if (!mode)
     return
 
-  if (prefersReducedMotion.value) {
+  if (mode === 'software')
+    maxDpr = 1
+  if (mode === 'software' || prefersReducedMotion.value) {
+    isStatic.value = true
     drawFrame()
     return
   }
@@ -323,6 +378,7 @@ watch(canvasRef, (canvas) => {
 })
 
 onBeforeUnmount(() => {
+  disposed = true
   pause()
   intersectionObserver?.disconnect()
   if (gl) {
diff --git a/app/components/SkillSourceList.vue b/app/components/SkillSourceList.vue
index 6b3c8d09..a256259b 100644
--- a/app/components/SkillSourceList.vue
+++ b/app/components/SkillSourceList.vue
@@ -3,6 +3,7 @@ import type { SkillSourceItem } from '../types/skill-source'
 import {
   useActiveElement,
   useElementHover,
+  useElementVisibility,
   useFocusWithin,
   usePreferredReducedMotion,
   useRafFn,
@@ -64,19 +65,28 @@ watch(hasFocusedItem, (focused) => {
   pendingItems.value = null
 })
 
-useRafFn(({ delta }) => {
+const isOnScreen = useElementVisibility(viewport)
+// The scroll writes layout on every frame, so it waits until the page has
+// hydrated and idles, and stops whenever nobody can see it.
+const pageReady = ref(false)
+onNuxtReady(() => {
+  pageReady.value = true
+})
+const scrolling = computed(() =>
+  variant === 'stream'
+  && autoScroll
+  && pageReady.value
+  && isOnScreen.value
+  && !isHovered.value
+  && !hasFocusedItem.value
+  && !manuallyPaused.value
+  && reducedMotion.value !== 'reduce',
+)
+
+const { pause, resume } = useRafFn(({ delta }) => {
   const element = viewport.value
-  if (
-    !element
-    || variant !== 'stream'
-    || !autoScroll
-    || isHovered.value
-    || hasFocusedItem.value
-    || manuallyPaused.value
-    || reducedMotion.value === 'reduce'
-  ) {
+  if (!element)
     return
-  }
 
   const maxScroll = element.scrollHeight - element.clientHeight
   if (maxScroll <= 0)
@@ -89,7 +99,9 @@ useRafFn(({ delta }) => {
 
   const distance = Math.min(delta, 64) * 0.018 * scrollDirection.value
   element.scrollTop = Math.min(maxScroll, Math.max(0, element.scrollTop + distance))
-}, { fpsLimit: 30, immediate: autoScroll })
+}, { fpsLimit: 30, immediate: false })
+
+watch(scrolling, run => run ? resume() : pause(), { immediate: true })
 
 function itemKey(item: SkillSourceItem): string {
   return `${item.owner}/${item.repo}/${item.name}`
diff --git a/app/utils/webgl-context.ts b/app/utils/webgl-context.ts
index eed29a07..8663bffd 100644
--- a/app/utils/webgl-context.ts
+++ b/app/utils/webgl-context.ts
@@ -47,3 +47,24 @@ export function isUsableWebGL2Context(value: unknown): value is WebGL2RenderingC
   return requiredWebGL2Methods.every(name => typeof candidate[name] === 'function')
     && requiredWebGL2Constants.every(name => typeof candidate[name] === 'number')
 }
+
+/**
+ * Renderers that run WebGL on the CPU: Chrome's SwiftShader fallback, Mesa's
+ * llvmpipe and softpipe, and Windows without a GPU driver. On these, every
+ * frame of a full-bleed shader is main-thread work.
+ */
+const SOFTWARE_RENDERER = /swiftshader|llvmpipe|softpipe|basic render driver/i
+
+export function isSoftwareRenderer(renderer: string): boolean {
+  return SOFTWARE_RENDERER.test(renderer)
+}
+
+/**
+ * The GPU name when the browser exposes it. Firefox and Safari may mask it;
+ * a masked name reads as a GPU, and `failIfMajorPerformanceCaveat` covers them.
+ */
+export function webglRendererName(gl: WebGL2RenderingContext): string {
+  const debugInfo = gl.getExtension('WEBGL_debug_renderer_info')
+  const name: unknown = gl.getParameter(debugInfo ? debugInfo.UNMASKED_RENDERER_WEBGL : gl.RENDERER)
+  return typeof name === 'string' ? name : ''
+}
diff --git a/test/unit/webgl-context.test.ts b/test/unit/webgl-context.test.ts
index 712d77f5..021e43f2 100644
--- a/test/unit/webgl-context.test.ts
+++ b/test/unit/webgl-context.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from 'vitest'
-import { isUsableWebGL2Context } from '../../app/utils/webgl-context'
+import { isSoftwareRenderer, isUsableWebGL2Context } from '../../app/utils/webgl-context'
 
 const requiredMethodNames = [
   'attachShader',
@@ -57,3 +57,25 @@ describe('isUsableWebGL2Context', () => {
     expect(isUsableWebGL2Context(contextStub())).toBe(true)
   })
 })
+
+describe('isSoftwareRenderer', () => {
+  it.each([
+    'ANGLE (Google, Vulkan 1.3.0 (SwiftShader Device (Subzero) (0x0000C0DE)), SwiftShader driver)',
+    'llvmpipe (LLVM 15.0.7, 256 bits)',
+    'ANGLE (Microsoft, Microsoft Basic Render Driver Direct3D11 vs_5_0 ps_5_0, D3D11)',
+  ])('names %s a CPU renderer', (renderer) => {
+    expect(isSoftwareRenderer(renderer)).toBe(true)
+  })
+
+  it.each([
+    'ANGLE (NVIDIA, NVIDIA GeForce RTX 3080 Direct3D11 vs_5_0 ps_5_0, D3D11)',
+    // Mesa's hardware driver names its LLVM shader compiler too.
+    'ANGLE (AMD, AMD Radeon RX 9070 XT (radeonsi gfx1201 LLVM 20.1.2), OpenGL 4.6)',
+    'Apple GPU',
+    'Adreno (TM) 640',
+    'Mali-G78',
+    'WebKit WebGL',
+  ])('names %s a GPU renderer', (renderer) => {
+    expect(isSoftwareRenderer(renderer)).toBe(false)
+  })
+})

From 61c31af5baed371f8337fbf9aa8c3b0d8e323b07 Mon Sep 17 00:00:00 2001
From: Harlan Wilton <harlan@harlanzw.com>
Date: Thu, 1 Oct 2026 13:38:11 +1000
Subject: [PATCH 2/4] perf(home): serve the homepage from the edge cache

Every home view rendered in the Worker and waited on four feeds, 300 to 480 ms to first byte. The trending board already proves the edgeCache rule in production, and the homepage has the same shape: rendered signed out, no cookie read, same feeds. The post-deploy proof now checks / with the boards.
---
 nuxt.config.ts                     |  4 ++++
 scripts/check-edge-cache.ts        |  2 +-
 scripts/lib/edge-cache-check.ts    |  2 +-
 test/unit/edge-cache-check.test.ts | 10 ++++++++++
 4 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/nuxt.config.ts b/nuxt.config.ts
index 914be02f..d20c6d9c 100644
--- a/nuxt.config.ts
+++ b/nuxt.config.ts
@@ -511,6 +511,10 @@ export default defineNuxtConfig({
     // inside the 36000s nuxt-skew-protection keeps old chunks for.
     // `scripts/check-edge-cache.ts` proves it after each deploy.
     '/skills/trending': edgeCache({ maxAge: 60, staleWhileRevalidate: 3600 }),
+    // The homepage is the same shape as the board: rendered signed out, no
+    // cookie read, and fed by the same feeds, so the same lifetimes hold. A
+    // render measured 300 to 480 ms to first byte from Sydney on 2026-10-01.
+    '/': edgeCache({ maxAge: 60, staleWhileRevalidate: 3600 }),
     // Raw markdown and the typeahead index deliberately keep browser caching
     // too: both are large, identical for everyone, and only change when the
     // registry does.
diff --git a/scripts/check-edge-cache.ts b/scripts/check-edge-cache.ts
index 05d3b4f7..c1fce62b 100644
--- a/scripts/check-edge-cache.ts
+++ b/scripts/check-edge-cache.ts
@@ -1,7 +1,7 @@
 import { checkEdgeCache } from './lib/edge-cache-check'
 
 /**
- * Prove the trending pages are cached at the edge and safe to cache.
+ * Prove the homepage and the trending pages are cached at the edge and safe to cache.
  *
  *   pnpm production:edge-cache
  *   EDGE_CACHE_BASE_URL=https://skilld.dev pnpm production:edge-cache
diff --git a/scripts/lib/edge-cache-check.ts b/scripts/lib/edge-cache-check.ts
index e4cd20ef..65e87390 100644
--- a/scripts/lib/edge-cache-check.ts
+++ b/scripts/lib/edge-cache-check.ts
@@ -22,7 +22,7 @@ import { varyKeysEdgeCache } from '../../shared/content-negotiation'
 import { DEFAULT_TRENDING_RANGE } from '../../shared/trending-range'
 
 /** The pages `nuxt.config.ts` gives an `edgeCache` rule. Each query is its own cache key. */
-export const EDGE_CACHED_PATHS = ['/skills/trending', '/skills/trending?range=month', '/skills/trending?range=all']
+export const EDGE_CACHED_PATHS = ['/', '/skills/trending', '/skills/trending?range=month', '/skills/trending?range=all']
 
 const BROWSER_HEADERS = {
   'accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8',
diff --git a/test/unit/edge-cache-check.test.ts b/test/unit/edge-cache-check.test.ts
index ae254298..3fdbeb07 100644
--- a/test/unit/edge-cache-check.test.ts
+++ b/test/unit/edge-cache-check.test.ts
@@ -88,6 +88,16 @@ describe('checkEdgeCache', () => {
     })
   })
 
+  it('expects the homepage to send Markdown readers to /index.md', async () => {
+    const homeEdge = (location: string) => edge({ markdown: () => ({ status: 307, headers: { location }, body: '' }) })
+
+    expect(await run(homeEdge('/index.md'), ['/'])).toMatchObject({ _tag: 'passed' })
+    expect(await run(homeEdge('/.md'), ['/'])).toMatchObject({
+      _tag: 'failed',
+      failures: [{ _tag: 'markdown-location', path: '/', actual: '/.md' }],
+    })
+  })
+
   it('fails when two boards render one page, as a cache key that ignores the query string would', async () => {
     const paths = ['/skills/trending', '/skills/trending?range=month', '/skills/trending?range=all']
     const result = await run(edge({

From 6ce14df28b9b774e328662ad3acfdbd139c0e022 Mon Sep 17 00:00:00 2001
From: Harlan Wilton <harlan@harlanzw.com>
Date: Thu, 1 Oct 2026 13:38:11 +1000
Subject: [PATCH 3/4] perf(css): emit Nuxt UI styles only for components in use

Nuxt UI wrote a theme for every component it ships, so the render-blocking entry stylesheet carried variant classes for components this app never renders. Detection drops 737 unused classes: 305 KB to 225 KB raw, 42 KB to 32 KB gzip on every page.
---
 nuxt.config.ts | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/nuxt.config.ts b/nuxt.config.ts
index d20c6d9c..430dd41f 100644
--- a/nuxt.config.ts
+++ b/nuxt.config.ts
@@ -700,6 +700,14 @@ export default defineNuxtConfig({
     },
   },
 
+  ui: {
+    // Nuxt UI otherwise writes a theme file for every component it ships, and
+    // Tailwind emits their variant classes into the render-blocking entry
+    // stylesheet. Detection keeps the components this app renders. Every
+    // component here is named statically, so nothing needs listing.
+    experimental: { componentDetection: true },
+  },
+
   fonts: {
     defaults: {
       subsets: ['latin'],

From c15c69afbc4beccf6fe16191ffdb9a23fcc751b6 Mon Sep 17 00:00:00 2001
From: Harlan Wilton <harlan@harlanzw.com>
Date: Thu, 1 Oct 2026 13:40:39 +1000
Subject: [PATCH 4/4] docs(design): record the noise field's frame budget

The spec asked for display-rate frames from mount. The field now waits for an idle main thread, caps the ambient shimmer at 15 fps, and draws one static frame on a CPU renderer, so the spec says so.
---
 DESIGN.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/DESIGN.md b/DESIGN.md
index fee5c86f..c8703885 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -325,7 +325,7 @@ The noise field renders thousands of dots with per-frame brightness calculations
 | **Base opacity** | 0.35 (hero), 0.5 (loading states) | Visible but subordinate to content |
 | **Bloom** | Gaussian glow (sigma 6px) on all visible dots, intensity scales with brightness | Soft halos create overlapping luminous field |
 | **Color** | HSL with hue from `djb2(route.path) % 360 / 360`, saturation 0.35 + brightness x 0.15, lightness 0.4 + brightness x 0.3 | Slightly warmer and brighter than original CLI spec for screen visibility |
-| **Frame rate** | Capped at display refresh via `requestAnimationFrame` | No `setInterval`; GPU-synced |
+| **Frame rate** | Display refresh via `requestAnimationFrame` for the 8s intro and while the cursor is over the field; 15 fps for the ambient shimmer after that | No `setInterval`; GPU-synced. The shimmer steps at 4 Hz, so 15 fps reads the same |
 | **Canvas sizing** | `devicePixelRatio`-aware, resize via `ResizeObserver` | Crisp on retina, no layout thrash |
 
 ### Interactivity
@@ -338,8 +338,9 @@ The noise field renders thousands of dots with per-frame brightness calculations
 
 - **GPU memory**: one framebuffer (bloom pass) + dot instance buffer. Under 2MB total
 - **CPU per frame**: uniform update only (~0.01ms). All computation in shaders
-- **Startup**: shader compilation happens once on mount; first frame within 16ms on modern GPUs
+- **Startup**: the field starts after hydration, once the main thread is idle (`onNuxtReady`). It is decoration and never competes with first paint. Shader compilation happens once
 - **Fallback**: if `WebGL2` is unavailable (rare), render a static SVG dot pattern at ambient shimmer brightness. No animation, no glow. Still warm, still branded
+- **Software renderer**: if WebGL runs on the CPU (SwiftShader, llvmpipe, no GPU driver), every frame is main-thread work. Draw one static frame at ambient shimmer state, at 1x, like reduced motion
 - **Visibility**: pause the animation loop when the canvas is offscreen (`IntersectionObserver`) or the tab is hidden (`document.visibilityState`). Zero GPU cost when not visible
 
 ### Reduced motion