chore(📚): minor docs improvements

Author: wcandillon

apps/docs/app/(home)/page.tsx

@@ -5,6 +5,7 @@ import Link from "next/link";
 import { useEffect, useState } from "react";
 
 import { SHADERS } from "@/components/hero/registry";
+import { HERO_BACKGROUND } from "@/components/hero/types";
 import { homeLinks } from "@/lib/layout.shared";
 
 const HeroShader = dynamic(
@@ -26,7 +27,12 @@ export default function HomePage() {
   const dark = entry.appearance !== "light";
 
   return (
-    <main className="relative min-h-0 flex-1 w-full overflow-hidden">
+    <main
+      className="relative min-h-0 flex-1 w-full overflow-hidden"
+      // The shader's background, not the theme's: keeps the hero from flashing
+      // (e.g. white in light mode) before the client-only canvas loads.
+      style={{ background: HERO_BACKGROUND[dark ? "dark" : "light"] }}
+    >
       <HeroShader entry={entry} className="absolute inset-0 h-full w-full" />
 
       <div className="pointer-events-none absolute inset-0 z-10 flex flex-col items-center justify-center px-6 text-center">

apps/docs/src/components/HeroShader.tsx

@@ -5,14 +5,28 @@ import { useTheme } from "next-themes";
 
 import { HeroCredit } from "./hero/HeroCredit";
 import { HERO_UNIFORM_SIZE } from "./hero/prelude";
-import { createPass, type Pass } from "./hero/runner";
-import type { HeroContext, ShaderEntry } from "./hero/types";
+import {
+  createFadeOverlay,
+  createPass,
+  type FadeOverlay,
+  type Pass,
+} from "./hero/runner";
+import { HERO_BACKGROUND, type HeroContext, type ShaderEntry } from "./hero/types";
 
 interface HeroShaderProps {
   entry: ShaderEntry;
   className?: string;
 }
 
+// Seconds over which the shader fades in from the background color.
+const FADE_IN_SECONDS = 1;
+
+const hexToRgb = (hex: string): [number, number, number] => [
+  parseInt(hex.slice(1, 3), 16) / 255,
+  parseInt(hex.slice(3, 5), 16) / 255,
+  parseInt(hex.slice(5, 7), 16) / 255,
+];
+
 export function HeroShader({ entry, className }: HeroShaderProps) {
   const canvasRef = useRef<HTMLCanvasElement>(null);
   const { resolvedTheme } = useTheme();
@@ -65,6 +79,7 @@ export function HeroShader({ entry, className }: HeroShaderProps) {
     let device: GPUDevice | null = null;
     let uniformBuffer: GPUBuffer | null = null;
     let pass: Pass | null = null;
+    let fade: FadeOverlay | null = null;
 
     (async () => {
       const adapter = await navigator.gpu.requestAdapter();
@@ -119,6 +134,11 @@ export function HeroShader({ entry, className }: HeroShaderProps) {
       pass = createPass(ctx, entry.shader, uniformBuffer, { isMobile });
       pass.resize(canvas.width, canvas.height);
 
+      fade = createFadeOverlay(
+        ctx,
+        hexToRgb(HERO_BACKGROUND[entry.appearance !== "light" ? "dark" : "light"]),
+      );
+
       const shaderStart = performance.now();
       let frame = 0;
       const uniforms = new Float32Array(HERO_UNIFORM_SIZE / 4);
@@ -150,7 +170,13 @@ export function HeroShader({ entry, className }: HeroShaderProps) {
         pass?.update(frame, time);
 
         const encoder = device.createCommandEncoder();
-        pass?.encode(encoder, context.getCurrentTexture().createView());
+        const target = context.getCurrentTexture().createView();
+        pass?.encode(encoder, target);
+        // Fade in from the background color over the first second.
+        const fadeAlpha = 1 - Math.min(1, time / FADE_IN_SECONDS);
+        if (fadeAlpha > 0) {
+          fade?.encode(encoder, target, fadeAlpha);
+        }
         device.queue.submit([encoder.finish()]);
 
         frame += 1;
@@ -168,6 +194,7 @@ export function HeroShader({ entry, className }: HeroShaderProps) {
       disposed = true;
       cancelAnimationFrame(animationId);
       pass?.destroy();
+      fade?.destroy();
       uniformBuffer?.destroy();
       device?.destroy();
     };
@@ -199,7 +226,7 @@ export function HeroShader({ entry, className }: HeroShaderProps) {
       <canvas
         ref={canvasRef}
         className="block h-full w-full"
-        style={{ background: dark ? "#050508" : "#f6f6fa" }}
+        style={{ background: HERO_BACKGROUND[dark ? "dark" : "light"] }}
       />
       <HeroCredit entry={entry} dark={dark} />
     </div>

apps/docs/src/components/hero/prelude.ts

@@ -47,6 +47,28 @@ export const COMPUTE_SCREEN_BINDING = /* wgsl */ `
 
 export const SCREEN_FORMAT: GPUTextureFormat = "rgba16float";
 
+// Fade-in overlay: a fullscreen quad in the hero background color, alpha-blended
+// over the finished frame. The runner drives the alpha from 1 to 0 over the
+// first second so the shader fades in from the background instead of popping.
+export const FADE_OVERLAY_SHADER = /* wgsl */ `
+@group(0) @binding(0) var<uniform> fadeColor: vec4f;
+
+@vertex
+fn vs_main(@builtin(vertex_index) vi: u32) -> @builtin(position) vec4f {
+  var pos = array(
+    vec2f(-1.0, -1.0),
+    vec2f(3.0, -1.0),
+    vec2f(-1.0, 3.0),
+  );
+  return vec4f(pos[vi], 0.0, 1.0);
+}
+
+@fragment
+fn fs_main() -> @location(0) vec4f {
+  return fadeColor;
+}
+`;
+
 // Blit pass: samples the compute output texture onto the swapchain. Uses a uv
 // varying from the vertex stage so it upscales correctly when the source texture
 // is smaller than the render target (compute shaders may render at a capped

apps/docs/src/components/hero/runner.ts

@@ -6,6 +6,7 @@ import { createComputeToysPass } from "./computetoys";
 import {
   BLIT_SHADER,
   COMPUTE_SCREEN_BINDING,
+  FADE_OVERLAY_SHADER,
   FULLSCREEN_VERTEX,
   SCREEN_FORMAT,
   UNIFORM_STRUCT,
@@ -29,6 +30,73 @@ export interface Pass {
   destroy: () => void;
 }
 
+// Fades the shader in from the hero background color: a fullscreen quad
+// alpha-blended over the finished frame. The caller drives `alpha` from 1 to 0
+// (over the first second) and stops encoding it once it reaches 0.
+export interface FadeOverlay {
+  encode: (encoder: GPUCommandEncoder, view: GPUTextureView, alpha: number) => void;
+  destroy: () => void;
+}
+
+export function createFadeOverlay(
+  ctx: HeroContext,
+  color: [number, number, number],
+): FadeOverlay {
+  const { device, format } = ctx;
+  const module = device.createShaderModule({ code: FADE_OVERLAY_SHADER });
+  const layout = device.createBindGroupLayout({
+    entries: [
+      {
+        binding: 0,
+        visibility: GPUShaderStage.FRAGMENT,
+        buffer: { type: "uniform" },
+      },
+    ],
+  });
+  const pipeline = device.createRenderPipeline({
+    layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+    vertex: { module, entryPoint: "vs_main" },
+    fragment: {
+      module,
+      entryPoint: "fs_main",
+      targets: [
+        {
+          format,
+          blend: {
+            color: { srcFactor: "src-alpha", dstFactor: "one-minus-src-alpha" },
+            alpha: { srcFactor: "one", dstFactor: "one-minus-src-alpha" },
+          },
+        },
+      ],
+    },
+    primitive: { topology: "triangle-list" },
+  });
+  const buffer = device.createBuffer({
+    size: 16,
+    usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+  });
+  const bind = device.createBindGroup({
+    layout,
+    entries: [{ binding: 0, resource: { buffer } }],
+  });
+  const data = new Float32Array([...color, 1]);
+
+  return {
+    encode: (encoder, view, alpha) => {
+      data[3] = alpha;
+      device.queue.writeBuffer(buffer, 0, data);
+      const pass = encoder.beginRenderPass({
+        colorAttachments: [{ view, loadOp: "load", storeOp: "store" }],
+      });
+      pass.setPipeline(pipeline);
+      pass.setBindGroup(0, bind);
+      pass.draw(3);
+      pass.end();
+    },
+    destroy: () => buffer.destroy(),
+  };
+}
+
 function createFragmentPass(
   ctx: HeroContext,
   shader: FragmentShader,

apps/docs/src/components/hero/types.ts

@@ -69,6 +69,16 @@ export interface ComputeToysShader {
   mobileConstOverrides?: Record<string, number>;
 }
 
+// Background color per shader appearance. Applied both to the canvas and to
+// the hero wrapper behind it, so the area already has the shader's background
+// (not the site theme's) while the client-only canvas chunk loads and the
+// first frame renders. Keeps light mode from flashing white before a dark
+// shader (and vice versa).
+export const HERO_BACKGROUND: Record<"dark" | "light", string> = {
+  dark: "#050508",
+  light: "#f6f6fa",
+};
+
 export interface ShaderEntry {
   id: string;
   title: string;