scroll-driven-canvas-scrubbing — v4.1.0

Teknik menggerakkan image sequence di <canvas> mengikuti posisi scroll. Bukan template landing page: markup, warna, tipografi, dan struktur halaman tetap milik yang memakai.

Dua cara pakai

Paket ini punya satu sumber kebenaran dan dua keluaran, karena dua pembacanya butuh hal berbeda.

A. Untuk agen (Claude Code, dsb.) — pakai struktur terpisah

SKILL.md                      205 baris: frontmatter + 7 aturan keras +
                              Fase 0–5 + playbook kegagalan
references/api.md             opsi + method instance + multi-instance
references/rationale.md       canvas vs video, matematika lerp, svh/lvh,
                              model memori tiga sumber, batasan yang disengaja
references/testing.md         desain harness, audit.js, batas jsdom, erratum
assets/scroll-scrub-engine.js engine (474 baris) — disalin ke proyek, tidak
                              perlu dibaca agen
tests/                        8 harness
audit.js                      11 pemeriksaan konsistensi

Ini yang dimaksud progressive disclosure: agen hanya memuat description (~100 token) sampai skill ter-trigger, lalu SKILL.md (~2 ribu token), dan hanya membuka references/ kalau tugasnya memerlukan. Engine tidak pernah masuk context window — agen menyalinnya, bukan membacanya.

B. Untuk manusia — pakai satu file

node build-bundle.js     # → SKILL-standalone.md (1.011 baris)

SKILL-standalone.md berisi semuanya: prosedur, ketiga referensi, dan engine lengkap tertanam byte-identik di §11. Cukup satu file itu untuk membangun dari nol — sudah diuji: engine diekstrak dari bundle, dipakai scrub 12 frame, frame 0 → 11 tercapai, nol error.

Kirim file ini ke orang lain. Jangan memelihara dua dokumen secara manual: build-bundle.js yang membangunnya, dan audit.js yang menolak kalau bundle menyimpang dari sumbernya.

SKILL-standalone.md tidak di-commit (lihat .gitignore) — ia hasil build, bukan sumber. Kalau kamu melihatnya di sebuah rilis, itu keluaran dari commit tertentu; jalankan node build-bundle.js untuk mereproduksinya.

Verifikasi

npm install jsdom
node build-bundle.js                       # dulu — audit menolak kalau bundle belum ada
for t in tests/*.js; do node "$t"; done    # 8 harness, 184 assertion, 0 gagal
node audit.js                              # 11/11 pemeriksaan, exit 0

Urutannya bukan selera: audit.js membangun ulang bundle dan membandingkannya byte per byte, jadi di clone baru yang belum pernah di-build ia akan gagal dengan pesan jalankan node build-bundle.js.

audit.js tidak membaca dokumen untuk memahaminya — ia mengekstrak nama opsi dari DEFAULTS dan nama method dari objek api, lalu menuntut keduanya ada di dokumentasi; menjalankan semua harness dan menuntut setiap angka yang disebut dokumen sama dengan keluaran nyata; memeriksa semua cuplikan js dengan node --check; membangun ulang bundle dan membandingkannya byte per byte.

Checker ini diuji dengan cara disabotase: opsi engine ditambahkan tanpa dokumentasi (tertangkap) · bundle diedit tanpa rebuild (tertangkap) · frontmatter dihapus (tertangkap). Harness patch diuji dengan me-revert tiap patch satu per satu. Checker yang tidak pernah gagal tidak membuktikan apa pun.

Batas yang tidak bisa ditutup test

jsdom tidak melakukan layout, tidak punya bitmap, tidak ada GPU/jaringan/GC. Jadi position:sticky, svh/lvh, dan byte RAM sungguhan tidak pernah dirender di harness. Checklist manual di Fase 4 adalah bagian dari verifikasi, bukan formalitas. Rinciannya: references/testing.md.

Sejarah singkat

Versi	Perubahan
v1 → v2	Pemetaan "section-scoped → svh" terbukti salah; menyebabkan strip hitam di lapangan
v2 → v3	Sumber memori ketiga (bitmap ter-decode) tidak pernah dihitung — dokumen menyebut 14.4 MB, sebenarnya 362 MB. Engine mendapat MAX_HELD
v3 → v4	Audit red team komunitas: 4 bug yang lolos dari 161 assertion (visualViewport bocor di destroy(), TOTAL_FRAMES < 2 → NaN, onerror tanpa retry, inflightCount O(n²))
v4 → v4.1	Merge dengan usulan red team: frontmatter, aturan keras, gerbang aset (Fase 0), gerbang verifikasi (Fase 4), playbook kegagalan, getFailed()/getInflight(), struktur assets/+references/, dan varian satu file yang dibangun otomatis

Tiga ronde umpan balik eksternal, tiga kali bug nyata lolos dari suite yang sudah hijau — semuanya tinggal di wilayah yang jsdom tidak bisa lihat. Itu alasan bagian "batas yang tidak bisa ditutup test" di atas ditulis eksplisit.