fire-paper-loader

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

页面构建期间，一圈燃烧的纸在黑色背景上缓缓展开。其机制是：火焰由 Worker 在从
<head>
启动的 OffscreenCanvas 上绘制，因此即使主线程被阻塞数百毫秒，加载环仍会持续燃烧。火焰外观属于表现层；无论外观如何，停滞 450 ms 的加载器看起来都会像卡死。

最接近的 skill：

web-design-performance

涵盖常规页面性能；这个 skill 专门用于即使线程被阻塞也能存活的加载器。如果需要用于滚动转场（而非加载器）的燃烧纸张效果，火焰 GLSL 使用相同的

kbFlame

，但改由页面绘制。如果需要 spinner 或 AI 状态球，请使用

thinking-orbs

。

源码中已验证的技术栈：Vanilla JavaScript、原生 WebGL 1（GLSL ES 1.00，加载器中不使用 Three.js）、Worker 与 OffscreenCanvas，以及用于标签和淡出的 CSS。

Start from the head, not from the body

从 head 启动，而不是从 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
```
eval
```
s 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.

症状：加载器晚 1–2 秒才出现，或 Worker 始终无法取得 GL context，或 three.js 下载期间火焰静止不动。只有主线程空闲时，Worker 才能启动并创建其 WebGL context；这样的时机出现在

<head>

中加载样式表的阶段，页面解析完成后就不会再有。

在
```
<head>
```
中的
```
<script>
```
内：创建 canvas，调用
```
transferControlToOffscreen()
```
，通过一个微型 boot script 的 Blob URL 启动 Worker，发送
```
{kbPre, canvas}
```
，并立即在 Worker 内调用
```
getContext('webgl', {antialias:false, alpha:false, depth:false, stencil:false})
```
。将 canvas 与 Worker 挂到
```
window.__kbPre
```
上。
boot script 只是一个外壳。加载器自身的
```
<script>
```
（位于 body 中稍后的位置）会把自己的
```
textContent
```
连同
```
{kbInit, src, canvas:null, t0, origin: performance.timeOrigin, reduced, view, target}
```
一并发给 Worker，再由 Worker 对其执行
```
eval
```
。同一份源码会同时运行在两个线程上：
```
const IN_W = typeof document === 'undefined'
```
。维护两份副本会发生漂移。
为每一步做好降级保护：没有 Worker、没有 OffscreenCanvas、没有
```
transferControlToOffscreen
```
、触发 Worker
```
onerror
```
，或收到
```
fail
```
消息时，就改由主线程使用相同代码，并在完成相同预热后绘制。
转换时钟。Worker 的
```
performance.now()
```
与页面不同：发送
```
performance.timeOrigin
```
，并在 Worker 中加上
```
performance.timeOrigin - origin
```
，这样页面读取的每个时间戳都基于页面自身的时钟。

Compile in parallel, warm the pipeline, then show

并行编译、预热 pipeline，然后再显示

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

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.
```
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.
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.
Show one canvas, not two. Drawing the fire on both threads first cost compile time in the first visible frames.

症状：最初几个可见帧恰好是加载过程中最慢的帧（30–130 ms，在 Metal 上有一次达到 408 ms）。

创建 ring 和 cinders 两个 program，为其 attach shaders 并分别执行
```
linkProgram
```
，之后才查询状态。使用
```
KHR_parallel_shader_compile
```
时，驱动会在自己的线程上完成编译；逐个 shader 读取
```
COMPILE_STATUS
```
会抵消这种并行优势。扩展存在时，应跳过逐 shader 检查。
```
warmUp()
```
：将两个 program 的真实帧 draw 调用运行到 1x1 viewport 中，然后执行
```
readPixels
```
读取 1 个像素，并等待完成。首次 draw 会构建 GPU pipeline；应确保它发生在任何内容被看到之前。
完成上述步骤后，才启动
```
requestAnimationFrame
```
。页面中的
```
LOAD.ready()
```
会在 Worker 完成绘制时 resolve（通常为 0.15–0.3 s，1.2 s 超时）；页面构建会等待它，从而不会在火焰静止时让主线程额外停顿一秒。
只显示一个 canvas，而不是两个。如果最初在两个线程上都绘制火焰，其编译时间会落入最初几个可见帧之中。

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.

症状：煤块在一秒内保持同一尺寸，随后突然跃升 2.5 倍；或者一个停滞的加载环被更快的加载环追上，看起来像两团火。

在
```
S = gain + ln(radius / first radius)
```
中规划增长，而不是在原始进度
```
u
```
中规划。S 中相同的步长，在任何尺寸下都呈现为均匀增长。淡入在 S 中的权重为 0.3（权重为 1 时，它会将尺寸压住 0.9 s）。
让 S 通过临界阻尼 spring 跟随目标（omega 5/s，速度限制为 1.6/s，以 1/120 s 子步长积分），目标值采用真实进度，但始终不低于 creep：
```
creep = 0.38*(1 - exp(-t/800 ms))
```
。等待期间，目标值不能超过
```
WAIT
```
0.290，而是以 2.5 s 时间常数向
```
CEIL
```
0.335 缓动。硬性暂停和成块抵达的进度，会让加载环看起来先停住、再被猛推。
绝不能静止：最低
```
VMIN
```
为 0.016/s（在 8 fps 下约为每帧 5 px），最高
```
VMAX
```
为 0.05/s。可见半径在进度为 0 时是一块 4 px 的微粒，到 0.15 时增至 5.8 px，随后过渡到燃烧本身对应的半径。
在页面尚未给出任何状态前，进度会按照自己的时钟缓慢爬升，因此即使 three.js 仍在传输，加载环也始终保持活性。

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.

症状：加载环猛然闯入页面的 intro，或者加载器消失时令页面产生 55–240 ms 的卡顿。

```
done()
```
会在 S 中执行 Hermite 插值，将速度从 creep 的速度过渡到页面 intro 的速度
```
V_HAND
```
0.24（u/s），持续
```
ds = clamp(2.8*du/vH, 0.30, 1.2)
```
秒，并在环缘抵达交接进度
```
HAND
```
0.36 时报告状态。页面从完全相同的进度和时钟继续自己的 intro。安全计时器（
```
doneDur + 400 ms
```
，页面侧另设为 2.4 s）无论
```
requestAnimationFrame
```
是否卡住都会 resolve。
标签数值落到 100，并通过 compositor 淡出（
```
transition: opacity .40s linear .12s
```
）：繁忙的首帧无法提前截断这一过程。
```
close()
```
：设置
```
alive = false
```
，并通知 Worker 停止绘制。淡出期间两个 context 同时绘制会共享 GPU 资源，并使淡出帧耗时达到 35–67 ms。最后一帧继续保留，并通过 CSS opacity 淡出（120 ms；减少动态效果时为 250 ms），同时使用 Web Animations keyframes 沿 intro 自身的曲线缩放，使其在离开时仍贴合页面环缘。
页面显示期间，绝不要调用
worker.terminate()
。这种操作曾在主线程上造成 55–240 ms 的阻塞。发送
```
free
```
消息，让 Worker 在自身线程中释放 GL context，并且只在
```
visibilitychange
```
变为 hidden 或触发
```
pagehide
```
时才 terminate。也绝不要在主线程调用
```
loseContext()
```
：它会等待所有已排队的 GPU 工作，包括 intro 的最初几帧（约 100 ms）。
在各个构建步骤之间让出执行权：
```
await LOAD.step(p)
```
会设置进度，等待频率最多为每 45 ms 一次（Worker 绘制时为 90 ms，因为此时只需更新计数），等待内容为一个
```
requestAnimationFrame
```
加一次
```
setTimeout 0
```
。隐藏标签页中不等待，因为
```
requestAnimationFrame
```
不会运行。

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
```
.

按顺序列出需求方指出的症状：“太静态了”、“黑色部分应该用 alpha 遮罩”；在采用四级 posterised ramp 后，又出现：“太不真实了，和之前一样，页脚的燃烧效果更好”。

采用明亮渐变，而不是 posterised 色阶。 余烬区是一条平滑的渐变带，从黄色过渡到橙色，再到深红色；高温区会把黄色向后方延伸，最终收束成清晰、撕裂状的边缘。硬色阶看起来会像海报。
最前缘是一串明亮的珠状亮线，宽度为 0.7–5 px，沿长度方向不断收细和鼓胀（均匀的 stroke 看起来像 neon），外围带有紧致的 additive glow，范围为 2–5 px。宽度不能更大；过宽的 bloom 会把环缘变成霓虹光圈。
它必须持续运动。 热量脉冲沿边缘双向奔涌（
```
run
```
），斑块以 7 Hz 闪烁（
```
flk
```
），珠状亮线不断漂移，一道滚流还会穿过余烬区向后传播。单看静止帧似乎没有问题，但加载器必须在运动中接受评判。
使用金色，而不是奶油色。 最热核心色为
```
(1.85, 1.02, 0.30)
```
，余烬色最高为
```
(1.10, 0.64, 0.17)
```
，且只应出现在高温区域。奶油色和卡其色通常来自两种错误：让最热端变白，或通过整体压暗来降低亮度。较暗区域应沿渐变降向深红色，而不是整体变暗。
使用多孔炭层，不添加发光轮廓。 余烬后方的炭化带接近黑色
```
(0.0085, 0.0062, 0.0048)
```
，并带有纤维纹理；孔隙会随时间扩大，并向下贯穿到下层画面。绝不要用发光边缘勾勒孔隙，否则所有孔隙都会沿边缘连成一条绘制出来的轮廓。
加载环绝不能从圆盘或
o
开始。它始于一段撕裂的余烬弧，厚度为 3.5–7 px，略超过半圆；弧线两端沿圆周缓慢爬行，并在 6.5–12 px 之间汇合。环宽必须保持在 3.5–7 px，不能更窄，否则会像一条绘制出来的轮廓。
Cinders：四组 instanced quads（1800、720、360、160 个，使用带种子的 mulberry32
```
0x2f6b9d1
```
），只从上方弧段（20–160°）散出，生命周期短，颜色从炽热橙色过渡到深红色，绝不出现白色。先进行 ACES tone mapping，再在 shader 中转为 sRGB（
```
aces
```
后执行
```
srgb
```
），因此要保持
```
gl_FragColor
```
的 alpha 为 1，并设置 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).

在主线程上绘制时，面对每次会阻塞 250–450 ms 的构建，火焰帧之间的最长间隔为 450 ms。改为在 Worker 中绘制后，同一页面的间隔为 9 ms。
DPR 最高为 1.5（这是源码中的上限；Web 的通用上限为 2）。加载环由一个全屏 triangle 和 3040 个 cinder quads 组成；成本主要来自 fragment shader，而不是 cinders。
时间步进：Worker 按自己的帧绘制，显示时钟则属于页面，因此动画 dt 会按设计进行 clamp（
```
dtp
```
最大 1.5 s，spring 使用 1/120 s 子步长）。

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.

在标签上使用
```
role="progressbar"
```
，并让
```
aria-valuenow
```
始终与进度同步；canvas 使用
```
aria-hidden
```
。计数采用文本，因此即使看不到火焰也能读取。
```
prefers-reduced-motion: reduce
```
：时间保持为 0（
```
tSec = 0
```
），不生成 cinders，也不使用 compositor scale；加载环仍会随进度展开，但呈现为静止、带颗粒的边缘，淡出时长为 250 ms。画面被设计为静态版本，而不是直接隐藏。
隐藏标签页：两个线程中的
```
requestAnimationFrame
```
都会暂停；
```
step()
```
停止等待；
```
done()
```
立即 resolve，并且只在此时 terminate Worker。
12 s 后若进度仍低于 40%，标签会显示“仍在引燃”：这样慢速连接能够及时得到提示，而不是无声无息地一直燃烧下去。
调整尺寸时，将新的
```
view
```
（w、h、DPR）发送给 Worker；canvas 会在下一帧完成 resize。

Boundary of what this skill gives you

此 skill 提供的边界

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.

机制（保留）：从 head 启动 Worker、同一份源码运行于两个线程、并行编译加带等待的 1 px warm-up、S 空间节奏控制、Hermite 交接、先停止再通过 CSS 淡出，以及不提前 terminate。表现层（可自由替换）：火焰的配色与形状、标签文案，以及最终交接到的页面。demo 代替页面的 intro：执行

done()

后，加载环会沿 intro 曲线继续运行 1.8 s，直到离开画面；真实页面随后从交接进度开始绘制自己的环缘。

来源：提取自 KIBORI 木彫的 KINDLING loader。这是一个滚动联动的 Three.js 木艺页面，其 1.1 MB 构建曾让主线程最多阻塞 1.2 s。