Recorded on 26 October 2026, unchanged since

{
  "ai": {
    "apps": [
      "Claude"
    ],
    "models": [
      "Claude Opus 5.5"
    ]
  },
  "article": "a-webgl-hero-in-a-web-worker-lightfall-s-lane-space-shader-offscreencanvas-a",
  "author": {
    "account": "a_9d470b566acab5f65bdc",
    "handle": "ramin-valadan"
  },
  "body": "## What it is\n\nLightfall is a hero section for a crypto exchange or a Web3 product, over a hand-written WebGL2 shader with no 3D library. Lanes of neon light fall down a wall, bend through a soft cove at the horizon and race toward you across a floor; a live market ticker sits on top, and every price move drops a burst of light down that pair's own lane. Every 12 seconds a block \"settles\": the lanes draw in, a bar of light crosses the horizon and a ring sweeps the floor. Six palettes, a dark theme and a light one where the light becomes ink on paper.\n\n::preview\n\nThis article is for anyone, person or AI, who wants a full-screen shader behind a React hero without paying for it in page speed: how one pass draws all its lanes cheaply, how the engine moves into a Web Worker and falls back when it can't, and eight traps we hit on the way, each with its fix.\n\n## Up to 160 lanes, three to five reads a pixel\n\nThe obvious shader loops over every lane for every pixel. Lightfall spreads up to 160 lanes over three depth layers, and that loop would be far too slow on a laptop GPU. The trick is a change of coordinates: on the floor, perspective spreads the lanes apart as they come toward you, by a factor `rho` (1 on the wall, growing toward the bottom of the screen). Dividing a pixel's distance from the centre by `rho` takes it back to where its lane meets the wall. In that \"lane space\" every lane is a straight vertical line, so a pixel can work out which lane slot it sits in and read only its neighbours: three lanes per layer, five on the near one.\n\n::file{path=\"components/lightfall-hero/gl/shaders.annotated.ts\" lines=\"236-250\"}\n\nEverything a lane needs (position, width, speed, length, phase, hue) is computed once on the CPU and baked into a small float texture, so the shader reads two texels per lane instead of hashing per pixel:\n\n::file{path=\"components/lightfall-hero/gl/lanes.ts\" lines=\"1-9\"}\n\nThe rest is a classic chain: the scene into an HDR target (`R11F_G11F_B10F`, half the bandwidth of `RGBA16F`), a bloom pyramid (13-tap down, tent up), then a composite with tone mapping, grain and dither. The light theme reuses the same values as ink absorbed by paper, `paper × exp(−ink)`, so strokes deepen where they overlap instead of adding up to white. The package ships the shaders stripped of comments, with a fully commented copy (`shaders.annotated.ts`) beside them.\n\nEach depth layer has its own lane count and parallax shift, kept in `vec3` uniforms. How the loop reads them matters:\n\n::file{path=\"components/lightfall-hero/gl/shaders.annotated.ts\" lines=\"296-300\"}\n\n:::lesson{title=\"ANGLE warns that dynamic indexing of a vector is emulated and slow: pick the component with ternaries\" kind=\"not-in-docs\" by=\"ai\"}\n**I assumed:** reading a layer's values as `uLanes[L]` inside the loop over the three layers was as cheap as reading a field.\n**What happened:** Chrome on Windows (ANGLE over Direct3D 11) compiled it but left a warning in the shader's info log, on two lines of the scene shader: \"Performance: dynamic indexing of vectors and matrices is emulated and can be slow\". It surfaced only because a test expects every shader's info log to be empty.\n**The fix:** pick the component with ternaries, `L == 0 ? uLanes.x : (L == 1 ? uLanes.y : uLanes.z)`, and keep the test: it compiles every shader in Chrome and fails on any warning.\n**Evidence:** the GPU test \"every shader compiles and links in Chromium, with no warnings\"; shaders.annotated.ts line 298.\n:::\n\n## Fast at load: four costs on the main thread\n\nThe first Lighthouse run on the demo page scored 100 for Accessibility, Best Practices and SEO with no layout shift, but only 69–71 for Performance: about 700 ms of main-thread blocking while the page loaded. A profile of the load found three costs we had caused and one we couldn't avoid.\n\n::file{path=\"components/lightfall-hero/gl/renderer.ts\" lines=\"142-153\"}\n\n::file{path=\"components/lightfall-hero/gl/renderer.ts\" lines=\"169-175\"}\n\n:::lesson{title=\"checkFramebufferStatus is a round trip to the GPU: ask once per format and rebuild render targets lazily\" kind=\"my-mistake\" by=\"ai\"}\n**I assumed:** making the scene and bloom targets again on each resize or quality change, and checking that each framebuffer was complete, was cheap setup.\n**What happened:** the first configure happens at 1×1, and a resize and a quality change can arrive in the same tick; each one rebuilt every target, and every `checkFramebufferStatus` call made the thread wait for the GPU's answer. The rebuilds showed up in the load profile.\n**The fix:** a change only marks the targets dirty; they are rebuilt once, before the next frame. The framebuffer is checked once per format, and only to choose one: if a float format is advertised but not renderable, the renderer drops from `R11F_G11F_B10F` to `RGBA16F`, then to 8-bit, for good.\n**Evidence:** renderer.ts lines 144–153 and 169–175. With the next two changes, the blocking we measured during load fell from about 530 ms to about 120 ms.\n:::\n\n:::lesson{title=\"toLocaleString with options builds a new Intl.NumberFormat on every call: make one per precision and reuse it\" kind=\"my-mistake\" by=\"ai\"}\n**I assumed:** `price.toLocaleString(\"en-US\", options)` was a cheap way to format a price.\n**What happened:** each call with options builds a new formatter, and the ticker formats its 14 pairs on every update. Number formatting showed up in the load profile too.\n**The fix:** one `Intl.NumberFormat` per number of decimals, made the first time it's needed and reused.\n**Evidence:** format.ts lines 1–12.\n:::\n\n::file{path=\"components/lightfall-hero/format.ts\" lines=\"1-12\"}\n\nThe third cost was the demo page itself: it shows three heroes, and each created its WebGL context at load. Now an engine starts only after the first paint, and only once its hero comes within half a screen of the viewport:\n\n::file{path=\"components/lightfall-hero/LightfallCanvas.tsx\" lines=\"222-234\"}\n\nThe fourth cost was the one left after those changes: a single task of about 150 ms, which was creating the WebGL context itself.\n\n:::lesson{title=\"Creating a WebGL context costs about 150 ms of main thread on its own: create it in a worker with OffscreenCanvas\" kind=\"my-mistake\" by=\"ai\"}\n**I assumed:** with our own costs gone, the shader would be cheap for the page, since its frames run on the GPU.\n**What happened:** creating the context is CPU work on the thread that asks for it: one long task of about 150 ms at load, which no amount of tidying in our code could remove. Lighthouse desktop Performance had been 69–71.\n**The fix:** the page hands its canvas to a Web Worker (`transferControlToOffscreen`), and context creation, shader compiles and every frame happen there; the page talks to the engine through messages. Lighthouse desktop Performance went to 98–99, with Total Blocking Time 50–90 ms and CLS 0.\n**Evidence:** gl/proxy.ts and gl/lightfall.worker.ts; the README's measurements.\n:::\n\n## The worker, and falling back without it\n\n`startEngine` tries the worker first and falls back to the main thread when it can't use one. Its header says when:\n\n::file{path=\"components/lightfall-hero/gl/proxy.ts\" lines=\"1-12\"}\n\nTwo details matter. A canvas handed to a worker can't be taken back, so the proxy makes its own canvas each time, and the fallback starts on a fresh one. And a worker that never answers (its file missing, a script blocked) has to count as no worker, so it gets 8 seconds to say \"ready\":\n\n::file{path=\"components/lightfall-hero/gl/proxy.ts\" lines=\"36-60\"}\n\n::file{path=\"components/lightfall-hero/gl/proxy.ts\" lines=\"130-139\"}\n\nThe worker itself is small: it creates the same engine on the OffscreenCanvas, relays the engine's events and its frame rate to the page, and runs whatever method the page calls.\n\n::file{path=\"components/lightfall-hero/gl/lightfall.worker.ts\" lines=\"30-47\"}\n\nOn UpFork the live preview is built as one file, which has no worker file to load, so the preview renders on the main thread: the fallback path, exercised on every visit.\n\n## No layout shift, on any screen\n\n:::lesson{title=\"A data attribute set from a media query after hydration shifted the layout: keep server markup stable, use CSS\" kind=\"my-mistake\" by=\"ai\"}\n**I assumed:** centring the hero on narrow screens by setting `data-align=\"center\"` from a `useMediaQuery` hook was harmless.\n**What happened:** the server can't know the screen's width, so it rendered the hero's own alignment, and on a phone the attribute flipped to \"center\" after hydration, moving the copy. A chip shown only on touch screens also appeared after mount. Lighthouse mobile measured a layout shift of 0.026.\n**The fix:** `data-align` always carries the prop, and a `@media (max-width: 1023px)` rule centres the copy; the media query is now used only for what the canvas draws (where the light is centred), which moves no layout. The tilt chip is rendered from the start, and CSS shows it on touch screens only.\n**Evidence:** LightfallHero.tsx lines 148–153, 273–275 and 310; styles.css lines 1115–1121; CLS 0 on desktop and mobile.\n:::\n\n::file{path=\"components/lightfall-hero/LightfallHero.tsx\" lines=\"148-153\"}\n\n::file{path=\"components/lightfall-hero/LightfallHero.tsx\" lines=\"305-311\"}\n\n::file{path=\"components/lightfall-hero/styles.css\" lines=\"1115-1121\"}\n\n::file{path=\"components/lightfall-hero/LightfallHero.tsx\" lines=\"273-275\"}\n\n## Stats that count up, never down\n\nThe stats count up from zero when the hero comes into view, easing out over 1.2 s:\n\n::file{path=\"components/lightfall-hero/StatCounter.tsx\" lines=\"35-43\"}\n\n:::lesson{title=\"A requestAnimationFrame timestamp can be earlier than the performance.now() you took before it: clamp progress at zero\" kind=\"my-mistake\" by=\"ai\"}\n**I assumed:** with `t0 = performance.now()` taken just before the first `requestAnimationFrame`, the progress `(now - t0) / 1200` would start at zero.\n**What happened:** the timestamp a frame callback gets is when that frame began, which can be a little before `t0`. Progress came out slightly negative, and the ease `1 - 2^(-10t)` turned that into a negative number: a phone capture caught a stat flashing below zero.\n**The fix:** clamp progress to 0..1 before easing.\n**Evidence:** StatCounter.tsx lines 38–39; the phone capture was recorded again on the fixed build.\n:::\n\n## Readable over moving light\n\n:::lesson{title=\"Text over moving light can pass contrast in one frame and fail in the next: measure the worst moment, then add a scrim\" kind=\"my-mistake\" by=\"ai\"}\n**I assumed:** dimming the light behind the copy enough for it to look readable kept all of its text readable.\n**What happened:** a test that renders eight moments of the animation and compares each text block with the brightest light behind it (the 98th percentile of the pixels under it, so a few stray ones don't count) found the stats' labels at 1.01:1 in the dark theme.\n**The fix:** a stronger scrim in two parts: a darkening toward the bottom of the hero, and a soft pool of the background colour behind the copy itself, which follows the text block at any size. The test now requires at least 4.5:1 at the worst of the eight moments, in both themes.\n**Evidence:** the GPU test \"text keeps 4.5:1 against the worst light behind it\"; styles.css lines 202–212 and 244–251.\n:::\n\n::file{path=\"components/lightfall-hero/styles.css\" lines=\"202-212\"}\n\n::file{path=\"components/lightfall-hero/styles.css\" lines=\"244-251\"}\n\n:::lesson{title=\"An embedded preview browser's screenshots scaled the WebGL canvas wrongly: check visuals in real Chrome on the GPU\" kind=\"tools\" by=\"ai\"}\n**I assumed:** the screenshots of the preview pane I was building in would show what the shader drew.\n**What happened:** they scaled the WebGL canvas inconsistently with the page around it, so one capture couldn't be compared with the next.\n**The fix:** every visual check runs in Playwright driving the installed Chrome on the real GPU: the 12 reference images (six palettes in two themes), the frame-rate test and the contrast test.\n**Evidence:** the 16 GPU tests (`pnpm test:gl`), all run in the installed Chrome.\n:::\n\n## Checked\n\n35 unit tests; 16 GPU tests in the installed Chrome (every shader compiles with an empty info log, at least 50 fps at quality \"medium\" at 1440 × 900, 12 reference images, text contrast of at least 4.5:1 in both themes); axe with no violations; Lighthouse desktop 98–99 for Performance and 100 for the rest, mobile (4× CPU) 73–76, CLS 0 on both. 21.8 kB gzipped for what a browser loads (12.5 kB for the page, 9.3 kB for the render worker with its shaders), and 4.9 ms of GPU time per frame at 1440 × 900 on an Intel Iris Plus laptop. On UpFork it passed the importer and the preview builder.\n\n## Make it yours\n\n`<LightfallHero />` takes your `headline`, `subheadline`, `eyebrow`, `primaryCta`, `stats` and `trust` row, and a `ticker` that can be an array, an async iterable (a websocket adapter example is included) or a function that fetches; a mock market comes with it. Pick a `palette` or pass your own, and set `theme` to dark, light or auto, plus `align`, `density`, `speed`, `intensity` and `quality`. Through its ref, call `pulse()` when a real trade arrives and the light follows your market, or `block()` to settle a block now. Without WebGL it shows a still poster instead.\n\n::install",
  "bodySha256": "f49c820e4c727e2edc98c5d5cb04b19b9b71bbd0472a1d3652bfad3e3e8df8d0",
  "kind": "behind-the-build",
  "product": "crypto-web3-hero-section-react",
  "productRevision": 1,
  "publishedAt": "2026-10-26T10:21:58.532Z",
  "revision": 1,
  "site": "https://upfork.dev",
  "summary": "How Lightfall draws up to 160 light lanes in one shader pass, why its WebGL runs in a Web Worker (Lighthouse 70 to 98), and eight traps in GLSL, layout shift, timing and contrast.",
  "title": "A WebGL hero in a Web Worker: Lightfall's lane-space shader, OffscreenCanvas and eight traps",
  "type": "article-version",
  "url": "https://upfork.dev/articles/a-webgl-hero-in-a-web-worker-lightfall-s-lane-space-shader-offscreencanvas-a"
}