Skip to content

An AI skill that turns books into animated, narrated, interactive web experiences

perf(engine): smooth playback in Firefox

yzr4dc3b61dff4b
diff --git a/.claude/skills/papermorph/assets/engine/engine.css b/.claude/skills/papermorph/assets/engine/engine.css
index 32acb76..17c8684 100644
--- a/.claude/skills/papermorph/assets/engine/engine.css
+++ b/.claude/skills/papermorph/assets/engine/engine.css
@@ -15,7 +15,8 @@ button[hidden] { display: none; }
/* One fixed 1600×960 frame (900 stage + 60 controls), scaled to fit the window. */
#frame { position: absolute; left: 50%; top: 50%; width: 1600px; height: 960px; transform: translate(-50%, -50%) scale(var(--k, .5));
border-radius: 20px; overflow: hidden; background: var(--board); box-shadow: 0 0 0 1px var(--edge), 0 30px 80px rgba(0, 0, 0, .45); }
-#stage { position: absolute; left: 0; top: 0; width: 1600px; height: 900px; display: block; }
+#stage { position: absolute; left: 0; top: 0; width: 1600px; height: 900px; display: block;
+ background: radial-gradient(75% 75% at 50% 45%, rgba(0,0,0,0) 60%, rgba(0,0,0,.35)), var(--grain, none), #1d2b27; }
#ui { position: absolute; left: 0; top: 0; width: 1600px; height: 900px; pointer-events: none; }
#ui > * { pointer-events: auto; }
diff --git a/.claude/skills/papermorph/assets/engine/engine.js b/.claude/skills/papermorph/assets/engine/engine.js
index 13bfe8e..fb64425 100644
--- a/.claude/skills/papermorph/assets/engine/engine.js
+++ b/.claude/skills/papermorph/assets/engine/engine.js
@@ -5,19 +5,6 @@
addEventListener('pagereveal', e => e.viewTransition?.ready.catch(() => {}));
document.body.insertAdjacentHTML('afterbegin', `<div id="frame">
<svg id="stage" viewBox="0 0 1600 900" role="img" aria-label="Lesson animation">
- <defs>
- <filter id="grain" x="0" y="0" width="100%" height="100%">
- <feTurbulence type="fractalNoise" baseFrequency=".85" numOctaves="2" seed="7" />
- <feColorMatrix values="0 0 0 0 .92 0 0 0 0 .95 0 0 0 0 .9 0 0 0 .07 0" />
- </filter>
- <radialGradient id="vignette" cx=".5" cy=".45" r=".75">
- <stop offset=".6" stop-color="#000" stop-opacity="0" />
- <stop offset="1" stop-color="#000" stop-opacity=".35" />
- </radialGradient>
- </defs>
- <rect width="1600" height="900" fill="#1d2b27" />
- <rect width="1600" height="900" filter="url(#grain)" />
- <rect width="1600" height="900" fill="url(#vignette)" />
<g id="scene"></g>
</svg>
<div id="ui"></div>
@@ -80,6 +67,16 @@ document.body.insertAdjacentHTML('afterbegin', `<div id="frame">
</div>
</div>`);
+// Board colour, grain and vignette are a static CSS background of #stage (engine.css). The grain is a small noise
+// texture made once here: an SVG turbulence filter behind animated content is recomputed on every frame in Firefox.
+{
+ const c = document.createElement('canvas'); c.width = c.height = 256;
+ const x = c.getContext('2d'), d = x.createImageData(256, 256);
+ for (let i = 0, s = 7; i < d.data.length; i += 4) { s = s * 16807 % 2147483647; d.data.set([235, 242, 230, s % 36], i); }
+ x.putImageData(d, 0, 0);
+ document.getElementById('stage').style.setProperty('--grain', `url(${c.toDataURL()})`);
+}
+
/* ---------- drawing helpers ---------- */
const NS = 'http://www.w3.org/2000/svg';
const COL = { nat: '#f4a48c', whole: '#86c9e8', int: '#f3c95c', rat: '#e8a0c8', irr: '#8fd6b0', real: '#bba8ee',
@@ -105,11 +102,11 @@ function mk(tag, attrs = {}, parent) {
// Keys: x y s r o (transform/opacity), d (0..1 stroke drawn), a_<attr> numeric attr, c_<attr> hex colour.
function st(e) { return e._st || (e._st = { x: 0, y: 0, s: 1, r: 0, o: 1 }); }
function put(e, o) { Object.assign(st(e), o); render(e); return e; }
+// Unchanged transform/opacity are not rewritten: per-frame updates of still elements cost repaints (notably in Firefox).
function render(e) {
- const s = e._st;
- if (s.x || s.y || s.s !== 1 || s.r) e.setAttribute('transform', `translate(${s.x},${s.y}) rotate(${s.r}) scale(${s.s})`);
- else e.removeAttribute('transform');
- e.setAttribute('opacity', s.o);
+ const s = e._st, tf = s.x || s.y || s.s !== 1 || s.r ? `translate(${s.x},${s.y}) rotate(${s.r}) scale(${s.s})` : null;
+ if (tf !== e._tf) { if (tf) e.setAttribute('transform', tf); else e.removeAttribute('transform'); e._tf = tf; }
+ if (s.o !== e._o) { e.setAttribute('opacity', s.o); e._o = s.o; }
if (s.d !== undefined) {
e.setAttribute('stroke-dashoffset', 1 - s.d);
e.style.visibility = s.d < .002 ? 'hidden' : '';
@@ -874,7 +871,8 @@ function camera(p, D, { box, x = 800, y = 450, z, r = 0, bg = COL.board } = {})
const e = k.amp * Math.min(1, (t - k.t0) / .3, (k.t0 + k.dur - t) / .3), w = 2 * Math.PI * k.hz * t;
sx += e * (Math.sin(w) + .5 * Math.sin(2.3 * w + 1)) / 1.5; sy += e * (Math.sin(1.7 * w + 2) + .5 * Math.sin(3.1 * w)) / 1.5;
}
- view.setAttribute('transform', `translate(${sx} ${sy}) rotate(${-s.r}) scale(${s.z}) translate(${-s.x} ${-s.y})`);
+ const tf = `translate(${sx} ${sy}) rotate(${-s.r}) scale(${s.z}) translate(${-s.x} ${-s.y})`;
+ if (tf !== view._tf) view.setAttribute('transform', view._tf = tf);
const dx = s.x - v0.x, dy = s.y - v0.y;
for (const L of layers) put(L.g, { x: L.wrap ? dx - ((L.k * dx) % L.wrap + L.wrap) % L.wrap : (1 - L.k) * dx, y: (1 - L.k) * dy });
}
@@ -928,7 +926,11 @@ function dot(key, v, r = 9, name = v) {
const arrow = (x, dir) => `M${x - 15 * dir} ${Y0 - 10}L${x} ${Y0}L${x - 15 * dir} ${Y0 + 10}`;
function panel(t0) {
if (t0 < .5) S.cleared = true; // the old panel fades, or this is the first panel after the title
- if (S.panel) hide(S.panel, t0, .4);
+ if (S.panel) { // fade the old panel, then take it out of rendering
+ const old = S.panel;
+ hide(old, t0, .4);
+ prog(q => { if (q === 1) old.style.display = 'none'; }, t0 + .4, 0, lin);
+ }
return (S.panel = G(scene));
}
function header(p, str, t0, x = 1000, y = 170) {
diff --git a/.claude/skills/papermorph/references/engine.md b/.claude/skills/papermorph/references/engine.md
index ba9a10a..357dbb7 100644
--- a/.claude/skills/papermorph/references/engine.md
+++ b/.claude/skills/papermorph/references/engine.md
@@ -61,6 +61,15 @@ For continuous motion (vehicles, orbits, rolling, scrolling scenery) and camera
- Labels drawn in the world scale with the zoom; put text that must stay readable in screen space (the panel) or give world labels a size for the shot's zoom. A beat whose camera shows a picture from its first frame while its first scheduled reveal is late may need `{ lead: false }`.
- Ease `soft` (cosine in-out) suits camera moves; `io`, `out`, `back`, `lin` or any `p => …` work too.
+## Performance (Firefox)
+
+Firefox repaints SVG on the main thread and is the slowest common browser for these pages. Measure in Playwright Firefox as well as Chromium: rAF frame times at beat transitions and during camera moves. Headless Chromium hides paint cost.
+
+- Never put an SVG filter behind animated content (the stage grain is a static CSS texture for this reason). Avoid clip-paths on moving or zooming groups where a box or an image does the job.
+- Large shapes under a big camera zoom or roll are expensive: a filled `<circle>` scaled 6× and rotating cost about 200 ms a frame in Firefox, while the same picture as one `<image>` cost about 3 ms. Prefer one image for a big detailed object (a planet, a map), and few elements over many small ones (merge cells into one path per colour, or use an image).
+- Write per-frame attributes and text only when they change (`render()` already skips unchanged transform and opacity). Old panels are set to `display: none` after their fade.
+- Pixel-art sprites: draw `<image>` with `style="image-rendering: pixelated"` at an integer scale, and pre-scale the file (nearest neighbour) so it stays crisp where the style is ignored.
+
## Questions
```js
diff --git a/site/science/lib/engine.css b/site/science/lib/engine.css
index 32acb76..17c8684 100644
--- a/site/science/lib/engine.css
+++ b/site/science/lib/engine.css
@@ -15,7 +15,8 @@ button[hidden] { display: none; }
/* One fixed 1600×960 frame (900 stage + 60 controls), scaled to fit the window. */
#frame { position: absolute; left: 50%; top: 50%; width: 1600px; height: 960px; transform: translate(-50%, -50%) scale(var(--k, .5));
border-radius: 20px; overflow: hidden; background: var(--board); box-shadow: 0 0 0 1px var(--edge), 0 30px 80px rgba(0, 0, 0, .45); }
-#stage { position: absolute; left: 0; top: 0; width: 1600px; height: 900px; display: block; }
+#stage { position: absolute; left: 0; top: 0; width: 1600px; height: 900px; display: block;
+ background: radial-gradient(75% 75% at 50% 45%, rgba(0,0,0,0) 60%, rgba(0,0,0,.35)), var(--grain, none), #1d2b27; }
#ui { position: absolute; left: 0; top: 0; width: 1600px; height: 900px; pointer-events: none; }
#ui > * { pointer-events: auto; }
diff --git a/site/science/lib/engine.js b/site/science/lib/engine.js
index 13bfe8e..fb64425 100644
--- a/site/science/lib/engine.js
+++ b/site/science/lib/engine.js
@@ -5,19 +5,6 @@
addEventListener('pagereveal', e => e.viewTransition?.ready.catch(() => {}));
document.body.insertAdjacentHTML('afterbegin', `<div id="frame">
<svg id="stage" viewBox="0 0 1600 900" role="img" aria-label="Lesson animation">
- <defs>
- <filter id="grain" x="0" y="0" width="100%" height="100%">
- <feTurbulence type="fractalNoise" baseFrequency=".85" numOctaves="2" seed="7" />
- <feColorMatrix values="0 0 0 0 .92 0 0 0 0 .95 0 0 0 0 .9 0 0 0 .07 0" />
- </filter>
- <radialGradient id="vignette" cx=".5" cy=".45" r=".75">
- <stop offset=".6" stop-color="#000" stop-opacity="0" />
- <stop offset="1" stop-color="#000" stop-opacity=".35" />
- </radialGradient>
- </defs>
- <rect width="1600" height="900" fill="#1d2b27" />
- <rect width="1600" height="900" filter="url(#grain)" />
- <rect width="1600" height="900" fill="url(#vignette)" />
<g id="scene"></g>
</svg>
<div id="ui"></div>
@@ -80,6 +67,16 @@ document.body.insertAdjacentHTML('afterbegin', `<div id="frame">
</div>
</div>`);
+// Board colour, grain and vignette are a static CSS background of #stage (engine.css). The grain is a small noise
+// texture made once here: an SVG turbulence filter behind animated content is recomputed on every frame in Firefox.
+{
+ const c = document.createElement('canvas'); c.width = c.height = 256;
+ const x = c.getContext('2d'), d = x.createImageData(256, 256);
+ for (let i = 0, s = 7; i < d.data.length; i += 4) { s = s * 16807 % 2147483647; d.data.set([235, 242, 230, s % 36], i); }
+ x.putImageData(d, 0, 0);
+ document.getElementById('stage').style.setProperty('--grain', `url(${c.toDataURL()})`);
+}
+
/* ---------- drawing helpers ---------- */
const NS = 'http://www.w3.org/2000/svg';
const COL = { nat: '#f4a48c', whole: '#86c9e8', int: '#f3c95c', rat: '#e8a0c8', irr: '#8fd6b0', real: '#bba8ee',
@@ -105,11 +102,11 @@ function mk(tag, attrs = {}, parent) {
// Keys: x y s r o (transform/opacity), d (0..1 stroke drawn), a_<attr> numeric attr, c_<attr> hex colour.
function st(e) { return e._st || (e._st = { x: 0, y: 0, s: 1, r: 0, o: 1 }); }
function put(e, o) { Object.assign(st(e), o); render(e); return e; }
+// Unchanged transform/opacity are not rewritten: per-frame updates of still elements cost repaints (notably in Firefox).
function render(e) {
- const s = e._st;
- if (s.x || s.y || s.s !== 1 || s.r) e.setAttribute('transform', `translate(${s.x},${s.y}) rotate(${s.r}) scale(${s.s})`);
- else e.removeAttribute('transform');
- e.setAttribute('opacity', s.o);
+ const s = e._st, tf = s.x || s.y || s.s !== 1 || s.r ? `translate(${s.x},${s.y}) rotate(${s.r}) scale(${s.s})` : null;
+ if (tf !== e._tf) { if (tf) e.setAttribute('transform', tf); else e.removeAttribute('transform'); e._tf = tf; }
+ if (s.o !== e._o) { e.setAttribute('opacity', s.o); e._o = s.o; }
if (s.d !== undefined) {
e.setAttribute('stroke-dashoffset', 1 - s.d);
e.style.visibility = s.d < .002 ? 'hidden' : '';
@@ -874,7 +871,8 @@ function camera(p, D, { box, x = 800, y = 450, z, r = 0, bg = COL.board } = {})
const e = k.amp * Math.min(1, (t - k.t0) / .3, (k.t0 + k.dur - t) / .3), w = 2 * Math.PI * k.hz * t;
sx += e * (Math.sin(w) + .5 * Math.sin(2.3 * w + 1)) / 1.5; sy += e * (Math.sin(1.7 * w + 2) + .5 * Math.sin(3.1 * w)) / 1.5;
}
- view.setAttribute('transform', `translate(${sx} ${sy}) rotate(${-s.r}) scale(${s.z}) translate(${-s.x} ${-s.y})`);
+ const tf = `translate(${sx} ${sy}) rotate(${-s.r}) scale(${s.z}) translate(${-s.x} ${-s.y})`;
+ if (tf !== view._tf) view.setAttribute('transform', view._tf = tf);
const dx = s.x - v0.x, dy = s.y - v0.y;
for (const L of layers) put(L.g, { x: L.wrap ? dx - ((L.k * dx) % L.wrap + L.wrap) % L.wrap : (1 - L.k) * dx, y: (1 - L.k) * dy });
}
@@ -928,7 +926,11 @@ function dot(key, v, r = 9, name = v) {
const arrow = (x, dir) => `M${x - 15 * dir} ${Y0 - 10}L${x} ${Y0}L${x - 15 * dir} ${Y0 + 10}`;
function panel(t0) {
if (t0 < .5) S.cleared = true; // the old panel fades, or this is the first panel after the title
- if (S.panel) hide(S.panel, t0, .4);
+ if (S.panel) { // fade the old panel, then take it out of rendering
+ const old = S.panel;
+ hide(old, t0, .4);
+ prog(q => { if (q === 1) old.style.display = 'none'; }, t0 + .4, 0, lin);
+ }
return (S.panel = G(scene));
}
function header(p, str, t0, x = 1000, y = 170) {