Fire Paper Loader

Fire-Paper Loader

A ring of burning paper opens on black while the page builds. The mechanism: the fire is drawn by a Worker on an OffscreenCanvas that is started from <head>, so the ring keeps burning while the main thread is blocked for hundreds of milliseconds. The flame look is staging; a loader that stops dead for 450 ms reads as a hang whatever it looks like.

Nearest skills: web-design-performance covers general page speed; this one is specifically a loader that survives a blocked thread. For the burning-paper look on scroll transitions (not a loader), the flame GLSL is the same kbFlame but the page draws it. For a spinner or AI-status orb, use thinking-orbs.

Stack, verified in the source: Vanilla JavaScript, raw WebGL 1 (GLSL ES 1.00, no Three.js in the loader), Worker plus OffscreenCanvas, CSS for the label and fade.

Start from the head, not from the body

Symptom: the loader appears 1-2 s late, or the worker never gets a GL context, or the fire stands still while three.js downloads. A worker can start and create its WebGL context only while the main thread is free, which is during stylesheet loading in <head> and not again until the page is parsed.

• In a <script> in <head>: create a canvas, transferControlToOffscreen(), start a Worker from a Blob URL of a tiny boot script, post {kbPre, canvas} and call getContext('webgl', {antialias:false, alpha:false, depth:false, stencil:false}) in the worker there and then. Keep the canvas and worker on window.__kbPre.
• The boot script is only a shell. The loader's own <script> (later in the body) sends its own textContent to the worker with {kbInit, src, canvas:null, t0, origin: performance.timeOrigin, reduced, view, target}, and the worker evals it. One source text runs on both threads: const IN_W = typeof document === 'undefined'. Two copies drift apart.
• Guard every step: no Worker, no OffscreenCanvas, no transferControlToOffscreen, worker onerror, or a fail message means draw on the main thread with the same code after the same warm-up.
• Convert clocks. The worker's performance.now() differs from the page's: send performance.timeOrigin, and add performance.timeOrigin - origin in the worker so every timestamp the page reads is its own.

Compile in parallel, warm the pipeline, then show

Symptom: the first visible frames are the slowest of the load (30-130 ms, once 408 ms on Metal).

1. Create both programs (ring, cinders), attach shaders, linkProgram both, and only then ask for status. With KHR_parallel_shader_compile the driver compiles on its own threads; reading COMPILE_STATUS per shader defeats it. Skip the per-shader check when the extension exists.
2. warmUp(): run a real frame's draws of both programs into a 1x1 viewport, then readPixels 1 pixel, waited. A first draw builds the GPU pipeline; make that happen before anything is seen.
3. Only then start requestAnimationFrame. The page's LOAD.ready() resolves when the worker draws (typically 0.15-0.3 s, timed out at 1.2 s); the build awaits it so it does not hold the thread off for a second while the fire stands still.
4. Show one canvas, not two. Drawing the fire on both threads first cost compile time in the first visible frames.

The ring's pace is planned in what is seen

Symptom: the coal sits at one size for a second, then leaps 2.5x; or a ring that stalls is overtaken by a faster one and reads as two fires.

• Plan the growth in S = gain + ln(radius / first radius), not in the raw progress u. Equal steps in S look like equal growth at every size. The fade-in weighs 0.3 in S (at 1 it held the size back for 0.9 s).
• Follow S with a critically damped spring (omega 5/s, speed clamped to 1.6/s, integrated in 1/120 s sub-steps) toward a goal that is the real progress but never behind a creep: creep = 0.38*(1 - exp(-t/800 ms)), and the goal cannot pass WAIT 0.290 while waiting, easing toward CEIL 0.335 with a 2.5 s time constant. A hard hold and progress arriving in lumps read as a ring parked, then shoved.
• Never still: minimum VMIN 0.016/s (about 5 px a frame at 8 fps), maximum VMAX 0.05/s. The seen radius: a 4 px fleck at progress 0, 5.8 px by 0.15, then the burn's own radius.
• Before the page has said anything, progress creeps on its own clock, so the ring lives while three.js is still on the wire.

Hand off without a stall

Symptom: the ring lurches into the page's intro, or the page stutters for 55-240 ms when the loader goes away.

• done() runs a Hermite in S from the creep's speed to the intro's speed V_HAND 0.24 (u/s), over ds = clamp(2.8*du/vH, 0.30, 1.2) seconds, and reports when the rim reaches the hand-off progress HAND 0.36. The page resumes its own intro from exactly that progress and clock. A safety timer (doneDur + 400 ms, and 2.4 s on the page side) resolves anyway if rAF stalled.
• The label lands on 100 and fades on the compositor (transition: opacity .40s linear .12s): a busy first frame cannot cut it short.
• close(): set alive = false and tell the worker to stop drawing. Two contexts drawing during the fade shared the GPU and ran the fade's frames at 35-67 ms. The last frame stays up and is faded with CSS opacity (120 ms, 250 ms under reduced motion), scaled by Web Animations keyframes along the intro's own curve so it stays on the page's rim while it goes.
• Do not worker.terminate() while the page is on screen. It held the main thread 55-240 ms at any time. Post free (lose the GL context in the worker, on the worker's thread) and terminate only on visibilitychange hidden or pagehide. Never loseContext() on the main thread either: it waits on all queued GPU work, including the intro's first frames (100 ms).
• Yield between build stations: await LOAD.step(p) sets progress and, at most every 45 ms (90 ms when the worker draws, since only the count needs it), waits one requestAnimationFrame plus setTimeout 0. In a hidden tab it does not wait, because rAF does not run there.