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.

The burn look: the footer is the reference

Symptoms the owner named, in order: "too static", "the black part should be alpha masked", then after a four-step posterised ramp, "too non-realistic, like before, the footer burn was better".

• A luminous gradient, not posterised steps. The ember zone is a smooth ramp yellow to orange to deep red, hot stretches carrying yellow further back, ending at a crisp torn lip. Hard steps read as a poster.

• A bright beading thread at the front, 0.7-5 px, pinched and swollen along its length (an even stroke reads as neon), with a tight additive glow of 2-5 px. Nothing wider: a fat bloom turns the rim into a neon hoop.

• It must move. Heat pulses run along the edge both ways (run), patches flicker at 7 Hz (flk), beads drift, a roll travels back through the zone. A still frame of it looks fine; the loader is judged in motion.

• Gold, not cream. The hottest core colour is (1.85, 1.02, 0.30), ember (1.10, 0.64, 0.17) at most, only where hot. Cream and khaki came from letting the hot end go white or dimming by darkening; a dim stretch goes down the ramp toward deep red instead.

• Porous char, no rims. The charred band behind the ember is near black (0.0085, 0.0062, 0.0048) with fibre grain, and pores open in it with age down to the frame beneath. Never ring the pores with glowing edges: they joined into one drawn contour along the edge.

• A ring never starts as a disc or an "o". It begins as a torn ember arc, 3.5-7 px thick, a little over half round, whose ends crawl round and meet between 6.5 and 12 px. Ring width is never under 3.5-7 px or it reads as a drawn outline.

• Cinders: four instanced sets (1800, 720, 360, 160 quads, seeded mulberry32 0x2f6b9d1), only off the upper arc (20-160 degrees), short lives, heat orange to deep red and never white. Tone-mapped ACES, then sRGB in the shader (aces then srgb), so keep gl_FragColor alpha 1 and the canvas alpha:false.

Cost, measured

• Drawn on the main thread against a build that blocks it 250-450 ms at a time, the longest gap between fire frames was 450 ms. In the worker, on the same page, 9 ms.

• Render at DPR up to 1.5 (the source's cap; the general web cap is 2). The ring is one full-screen triangle plus 3040 cinder quads; the fragment shader is the cost, not the cinders.

• Time step: the worker draws on its own frames; the display clock is the page's, so a dt of the animation is clamped by design (dtp max 1.5 s, 1/120 s spring sub-steps).

Lifecycle and accessibility

• role="progressbar" on the label with aria-valuenow kept in step; the canvases are aria-hidden. The count is text, so it is readable without the fire.

• prefers-reduced-motion: reduce: no time (tSec = 0), no cinders, no compositor scale; the ring still opens with progress as a still, grained rim and the fade is 250 ms. The frame is designed as a still, not hidden.

• Hidden tab: rAF pauses in both threads; step() stops waiting; done() resolves at once, and the worker is terminated only then.

• After 12 s at under 40 percent, the label says "Still kindling": slow connections should be told rather than burnt at quietly forever.

• Resize: post the new view (w, h, DPR) to the worker; the canvas resizes on the next frame.

Boundary of what this skill gives you

Mechanism (keep): head-started worker, one source on two threads, parallel compile plus waited 1-px warm-up, S-space pacing, Hermite hand-off, stop-then-CSS-fade, no early terminate. Staging (replace freely): the fire's palette and shape, the label copy, the page it hands to. The demo stands in for the page's intro: after done() the loader's ring runs on along the intro curve for 1.8 s until it leaves the frame, where the real page draws its own rim from the hand-off progress.

Source: extracted from the KINDLING loader of KIBORI 木彫, a scroll-linked Three.js woodcraft page whose 1.1 MB build held the main thread for up to 1.2 s.