@autoaiai/aicut 0.1.7 → 0.1.11

package/skills/bang-motion/references/ae-bridge-higgsfield.md

@@ -0,0 +1,160 @@
+# After Effects lewat bridge Higgsfield — membangun kartun panggung langsung di AE
+
+Dibaca bila user sudah membuka proyek After Effects dan bridge Higgsfield (MCP `ae_*`)
+tersambung, lalu meminta explainer dibangun **langsung di AE**. Angka acuan dari satu
+build explainer kartun panggung (103 dtk VO, 10 panggung, 20 karakter bersendi, 96 aset
+PNG): ±67 menit dari comp master sampai contact sheet terakhir, ±100 panggilan tool AE,
+0 kredit Higgsfield. Hukum gaya tetap dari `kartun-panggung.md`; dokumen ini hanya
+soal CARA membangunnya lewat bridge.
+
+## Apa yang bisa dan tidak bisa dilakukan bridge
+
+| Bisa | Tidak bisa (dan jalan keluarnya) |
+|---|---|
+| `ae_build_scene_from_lottie` membuat comp + precomp + layer shape sederhana sekaligus | Lottie besar (>~60 KB) — pecah: Lottie hanya untuk **kerangka**, isi lewat op atomik |
+| `ae_batch` menjalankan puluhan op (`add_shape_layer`, `add_null_layer`, `import_image`, `modify_layer`, `set_keyframes`, `set_expression`) dalam satu panggilan | `apply_gradient`, `get_layer_info`, `export_frame` di dalam batch → seluruh batch error; panggil standalone |
+| `add_shape_layer` rectangle (dengan `roundness`) dan ellipse, warna `{r,g,b}` 0–1 | Path/poligon/bintang, stroke, gradient pada shape → gambar sebagai SVG di luar, render ke PNG, impor |
+| `ae_import_image` PNG/JPG/WAV (WAV memberi peringatan "hidden property" yang tidak berbahaya) | SVG ("invalid file type"); file di folder sementara/virtual milik aplikasi agent sering tidak terlihat oleh AE → salin aset dulu ke folder biasa (mis. `C:/aset-ae/`) |
+| `ae_apply_gradient` Gradient Ramp 2 stop / 4-Color pada shape statis (langit) | Gradient di layer berkeyframe; gradient di dalam batch |
+| `set_expression` pada Position/Scale/Rotation/Opacity/Anchor | Expression pada properti efek atau path; `ae_reorder_layers` selalu "layer not found" → **urutan tumpuk = urutan pembuatan**, buat dari belakang ke depan |
+| `ae_export_contact_sheet` (5–8 waktu) dan `ae_export_frame` → URL r2.dev | Melihat URL r2.dev dari Indonesia (diblokir) → relay: `media_import_url(url)` di MCP Higgsfield → `curl https://d2ol7oe51mr4n9.cloudfront.net/<user>/<media_id>.png` → Read. Relay kadang gagal ("Something went wrong"); ekspor ulang, URL baru biasanya lolos |
+| `ae_get_layer_info`, `ae_list_layers`, `ae_list_compositions` untuk verifikasi angka | Menyimpan proyek, merender, menghapus comp. User harus **Ctrl+S**; MP4 lewat Render Queue atau `aerender.exe` |
+
+Jebakan bridge yang paling sering terjadi:
+
+1. **Null baru lahir di (960,540).** `add_null_layer` lalu langsung di-parent-kan →
+   semua anak yang belum berkeyframe melompat −960,−540. Segera `modify_layer`
+   anchorPoint `[0,0]` + position `[0,0]` pada null itu SEBELUM parenting apa pun.
+2. **Parenting ke CAM yang sudah berkeyframe** membakar transform CAM ke anak: posisi
+   ikut tergeser, skala ikut mengecil. Setelah parent, set ulang position/scale anak
+   secara eksplisit (atau parent dulu, animasikan CAM belakangan).
+3. **Keyframe pada layer ber-parent memakai ruang induk.** Mata di dalam kepala bukan
+   `[932,472]` (comp) tapi `[-28,-2]` (relatif pusat kepala). Salah ruang = bagian
+   wajah terlempar ke luar frame.
+4. **Batch parsial.** Bila satu op gagal dengan `stopOnError:false`, op lain tetap
+   diterapkan; baca `results[i].ok` satu per satu, jangan mengulang seluruh batch.
+5. **Lottie: posisi anak ditulis di ruang comp**, bukan relatif induk; converter juga
+   membuat comp duplikat bila nama sama dan membuang gradient/gambar/mask/expression.
+   `ip/op/st` pada layer precomp diterjemahkan benar — gunakan itu untuk timing master.
+6. **Contact sheet di dalam precomp yang di-zoom master tampak buram** → kamera bukan di
+   layer precomp master, tapi null `CAM` di dalam tiap panggung.
+
+## Arsitektur yang terbukti
+
+```
+# <judul>                     comp master 1920×1080 30fps, durasi = VO
+├─ VO (wav)                   detik 0
+└─ > P01 … > P10              layer precomp, ip/op dari jeda VO, st = ip (lokal mulai 0)
+     ### P01 <nama panggung>  precomp, durasi = segmen + 0,6 dtk (P04 +8 dtk bila dipakai ulang sebagai penutup)
+     ├─ langit                rect seukuran comp dari Lottie → ae_apply_gradient
+     ├─ CAM                   null, anchor [0,0] pos [0,0]; SEMUA layer dunia di-parent ke sini
+     ├─ bukit, tanah, …       PNG 2× dari SVG, scale 50, anchor dari manifest, pos = pivot comp
+     ├─ <tokoh> ROOT + 29 bagian   shape asli AE (lihat rig)
+     └─ lapisan gelap/pagi/api  PNG/rect overlay, dibuat TERAKHIR (paling atas), opacity berkeyframe
+```
+
+**Kamera = null CAM.** Untuk melihat titik (x,y) pada zoom z:
+`CAM.Position = [960 − x·z, 540 − y·z]`, `CAM.Scale = [100z, 100z]`. Keyframe dengan
+`influence` 50–75 untuk ease. Zoom tidak pernah < 1,08 (Hukum 1 kartun panggung).
+
+**Comp dipakai ulang sebagai panggung lain** (penutup memakai panggung api unggun):
+layer precomp kedua di master dengan `st` = ip − waktu_lokal_mulai; animasi bagian
+penutup ditaruh di waktu lokal itu (contoh: 13 dtk), dipisah dari adegan pertama dengan
+keyframe hold ganda (12,93 → 12,967) supaya tidak ada interpolasi antar adegan.
+
+**Aksen geser 96 px** (satu kali, pergantian zaman): keyframe Position layer precomp di
+master — P08 960→864 (0,3 dtk, influence 70→10), P09 1056→960 (0,4 dtk, influence 10→80);
+tambah Scale 100→111 dan 111→100 di waktu yang sama supaya tepi comp tidak terbuka.
+
+## Alur kerja
+
+0. Rundown per panggung dikunci ke jeda VO (`vo-pauses.html` atau `ffmpeg silencedetect`),
+   plus daftar kamera per panggung `(t, x, y, z)`. Style brief kartun panggung tetap wajib.
+1. **Kerangka lewat satu Lottie kecil**: comp master + tiap precomp berisi hanya layer
+   `langit`, layer precomp di master dengan `ip/op/st`. Impor WAV VO ke master.
+2. **Aset ilustrasi dari kode** (`scripts/ae/bridge/aset-svg.py`): tiap aset = satu
+   fungsi menggambar (rect/ellipse/path halus) di koordinat lokal dengan pivot yang
+   ditentukan; skrip menulis SVG + `manifest.json` berisi `png, pos, anchor(px 2×),
+   scale 50`. Render semua dengan `node scripts/ae/bridge/svg2png.cjs <folder>`
+   (puppeteer, PNG transparan seukuran SVG 2×). Gambar sesuai zona kamera: yang di
+   luar zoom ≥1,08 tidak perlu digambar.
+3. **Per panggung, satu `ae_batch`** urut belakang → depan:
+   `add_null_layer CAM` → `modify_layer` CAM anchor/pos 0 → `import_image` + `modify_layer`
+   (anchor, position, scale 50, opacity awal) per aset → `modify_layer parentLayerName:"CAM"`
+   untuk semua → `set_keyframes` kamera & aset → `set_expression` gerak idle.
+   `ae_apply_gradient` langit dipanggil terpisah SEBELUM batch.
+4. **Karakter**: `python scripts/ae/bridge/rig-tokoh.py "<comp>" <prefix> <x> <gy> <skala> [varian]`
+   mencetak ±90 op; tambahkan `modify_layer <prefix> ROOT parentLayerName CAM` dan set
+   ulang ROOT position/scale (jebakan 2). Kirim sebagai satu `ae_batch` per karakter
+   (±15 KB). Setelah rig jadi, batch kedua berisi pose/aksi + expression idle.
+5. **Verifikasi tiap panggung** dengan `ae_export_contact_sheet` 5–8 waktu kunci → relay
+   → lihat. Cek: rig utuh (sendi tidak lepas), latar tidak bergeser (jebakan 1–2),
+   overlay di atas, ≥10 benda bergerak. Terakhir contact sheet **master** di satu waktu
+   per panggung + waktu transisi.
+6. **Penyerahan**: minta user Ctrl+S (bridge tidak bisa simpan), hapus comp uji coba,
+   render lewat Render Queue atau
+   `"C:/Program Files/Adobe/Adobe After Effects 2026/Support Files/aerender.exe" -project … -comp "# …" -output ….mp4`.
+   Sebutkan kompromi yang tersisa (contoh: urutan layer yang tidak bisa disusun ulang).
+
+## Rig karakter native (`rig-tokoh.py`)
+
+Pola yang terbukti: **buat shape di posisi comp → `modify_layer` anchor = titik sendi
+(koordinat layer, relatif pusat bentuk) + position = titik sendi (comp) → parent**.
+Parenting "melompat" menjaga tampilan, dan Rotation berputar tepat di sendi.
+
+```
+<p> ROOT (null, pelvis = gy − 214s, anchor [50,50])
+├─ paha-L/R (anchor [0,−52s], sendi pinggul ±24s) → betis (lutut gy−112s) → kaki (mata kaki gy−16s)
+└─ torso (anchor [0,76s], sendi pelvis)
+   ├─ lengan-L/R (bahu ±52s, gy−340s) → lenganbawah (siku gy−262s) → tangan (pergelangan gy−190s)
+   ├─ tunik-rumbai, leher
+   └─ kepala (anchor [0,72s], leher gy−398s)
+      └─ telinga, rambut-1..5, janggut (varian utama/anggota3), mata-L/R, alis-L/R, hidung, mulut
+```
+
+Urutan pembuatan = urutan tumpuk: kaki belakang (R) → lengan belakang (R) → torso →
+kepala + wajah → lengan depan (L). Skala 0,75 (jauh), 0,85–0,9 (panggung normal), 1,15–1,4
+(close-up). Varian kulit/tunik/rambut di `VAR`; jangan menambah varian dengan nama
+merek/tokoh nyata.
+
+Angka ekspresi/aksi yang dipakai (semua deterministik dari `time`):
+
+| Gerak | Expression / keyframe |
+|---|---|
+| Napas | torso Scale `[value[0], value[1]*(1+Math.sin(time*2.4)*0.015)]` (fase beda per tokoh) |
+| Kedip | mata Scale `var c=(time+0.4)%3.3; c<0.12?[value[0],value[1]*0.1]:value` |
+| Jalan (digate) | paha `value ± sin((time−t0)*11)*24`, betis `max(0, ±sin(…−1))*20`, lengan berlawanan `*18`, ROOT y `−abs(sin)*6` — hanya dalam `t0<time<t1` |
+| Lompat | ROOT Position 3× (0,25 dtk turun-naik 55 px), paha `−abs(sin(π·2t))*25`, betis `+35` |
+| Lempar melengkung | lengan Rotation 0 → −20 (ancang) → 110 (lepas, influence 30) → 0; benda: 3 keyframe Position (tangan → puncak → tangan penerima) + Rotation 540–720 |
+| Melambai | lengan Rotation −150 ↔ −120 tiap 0,3 dtk |
+| Memeluk/cemas | lengan-R −35, lenganbawah-R −60, lengan-L −70, lenganbawah-L −40; alis ±15; mulut Scale `[70,60]` |
+| Kaget/senang | mulut Scale `[130,260]` dalam 0,03 dtk; mata Position bergeser ±10 di ruang kepala |
+| Tidur | ROOT Rotation −90 (cut, hold ganda), mata Scale `[110,12]`, napas 1,6 Hz amplitudo 0,03 |
+| Api | lidah api Scale `1+sin(time*13..21)*0.07..0.18`, Rotation `sin(time*8..10)*4..5`; cahaya api PNG opacity 30, Scale bernapas 3 % |
+| Lalat/bintang/semak | Position `sin/cos` amplitudo 30–80 px; bintang Opacity `value*(0.85+sin(time*2.3)*0.15)`; semak Rotation `sin(time*1.7)*2` |
+
+## Yang dikompromikan pada build ini (katakan ke user di awal)
+
+- Urutan layer mengikuti urutan pembuatan; benda yang harus melintas DI DEPAN tokoh
+  harus dibuat setelah tokoh, atau dibuat ulang.
+- Aset ilustrasi berupa PNG raster; mengubah warna/bentuk = edit skrip SVG, render
+  ulang, ganti footage. Karakter tetap vektor dan bisa diedit penuh di AE.
+- Tanpa motion blur, tanpa efek selain Gradient Ramp; blur/glow ditambahkan user di AE.
+- Setiap karakter = ±15 KB teks perintah yang harus ditulis penuh (bridge tidak membaca
+  file op); 20 karakter ≈ 300 KB. Ini penyumbang waktu terbesar, bukan latensi bridge
+  (rata-rata `ae_batch` 6,5 dtk, contact sheet 12 dtk, relay 7 dtk).
+
+## Checklist bridge
+
+- [ ] CAM: anchor `[0,0]`, position `[0,0]` sebelum ada anak; kamera hanya di CAM,
+      layer precomp master diam (kecuali aksen geser 96 px)
+- [ ] Semua layer dunia ber-parent ke CAM; setelah parent, posisi/skala aset dicek
+      lewat `ae_get_layer_info` (tanah harus `[0,0]`, scale `[50,50]`)
+- [ ] Urutan pembuatan: langit → latar jauh → tanah → properti → tokoh → benda yang
+      dilempar → overlay cahaya/malam
+- [ ] Keyframe bagian tubuh dalam ruang induk; hold ganda (Δ1 frame) untuk cut di dalam
+      panggung yang dipakai ulang
+- [ ] Contact sheet tiap panggung dilihat mata (via relay bila r2 diblokir), lalu
+      contact sheet master satu waktu per panggung
+- [ ] `apply_gradient` / `get_layer_info` / `export_*` tidak pernah di dalam `ae_batch`
+- [ ] Pesan penutup: Ctrl+S, hapus comp uji, perintah `aerender`, daftar kompromi

package/skills/bang-motion/references/anti-ppt.md

@@ -0,0 +1,110 @@
+# Anti-PPT — hukum desain adegan
+
+Dokumen ini adalah alasan skill ini ada: hasil yang "secara teknis benar" tetap
+gagal bila terasa seperti presentasi PPT.
+
+## Kenapa model selalu jatuh ke pola slide
+
+Model dilatih menyusun INFORMASI: judul → penjelas → bukti pendukung.
+Struktur itu bagus untuk dokumen, dan fatal untuk motion graphic.
+Video promosi tidak menjelaskan — ia **menyatakan**, satu pukulan per shot,
+dan membiarkan gerakan + musik yang membawa emosinya. Kalau kamu merasa
+sebuah adegan "kurang informasi", itu justru tanda adegannya sudah benar.
+
+## Tabel pelanggaran → perbaikan
+
+| Pelanggaran | Perbaikan |
+|---|---|
+| Kicker "02 — FITUR" + judul 2 baris + body copy 2 baris + 4 chip badge, layout kolom kiri-kanan | Satu kalimat ≤ 5 kata di tengah-atas + satu objek produk naik ke tengah |
+| Tiga baris teks besar berisi tiga klaim "TANPA …" | Headline 2 kata + satu cara dari menu fitur (`opener-konsep.md`): satu fitur didemokan, kata berganti, objek bertransformasi, kartu dikocok, grid tile… — dipilih per proyek |
+| Opener produk B memakai kulit opener produk A (palet, glow, nebula, font yang sama) karena diambil dari starter/proyek lama | Gaya diturunkan dari brand B lewat style brief: palet dari logo/ikon B, font berkarakter lain, bahasa latar lain, tanda tangan gerak lain (SKILL.md Hukum #3) |
+| Semua judul KAPITAL SEMUA, font lebar bobot 800, selalu di tengah, masuk dengan stagger huruf yang sama — terasa kaku | Sentence case bobot 500, penekanan pada kata kunci (sorotan kata opsional — bisa juga kata per kata, ukuran, jeda, objek di samping kata), tanpa titik otomatis (tanda baca hanya bila mengubah arti), ukuran/arah/posisi bergantian (techniques.md §1) |
+| Setiap judul/klaim diakhiri titik, termasuk frase dua kata — terasa kaku dan seperti template | Default tanpa titik; `?` untuk pertanyaan sungguhan, titik hanya untuk gaya dua kalimat pendek yang disengaja dan konsisten (techniques.md §1 aturan 5) |
+| Ladang 96 batang cahaya putih ber-bloom di belakang judul — latar ramai, teks tidak kontras | Kantong gelap di bawah teks, partikel berwarna sisi gelap palet dan redup, ≤ 40 elemen terang, bloom hanya di objek (techniques.md §1b) |
+| Semua opener gelap dengan nebula/partikel, latar tidak pernah dipertimbangkan per segmen | Latar dari tema (gradien terang, warna lembut, blok warna, kertas, foto, atau gelap); pergantian diputuskan per segmen di style brief dan terjadi di balik cut/wipe (techniques.md §7b) |
+| Setiap opener memberi kata sorotan (garis bawah/pill) di setiap kalimat, atau memakai pill + bintang yang sama persis dengan proyek lain | Sorotan kata opsional dan diputuskan di style brief; bila dipakai, satu bentuk per video yang dipilih per proyek, tidak di setiap kalimat, ornamen hanya dari bentuk brand (techniques.md §1) |
+| Opener app/SaaS hanya menampilkan screenshot diam yang di-zoom atau digeser | UI dirakit ulang dari komponen produk, dipakai (kursor, jari, atau UI yang bereaksi sendiri), data mengisi, transisi dibawa UI (`opener-konsep.md` bagian animasi UI) |
+| Video ditempel layar penuh dengan `autoplay loop`, berjalan dengan jamnya sendiri, dan animasi lain berhenti selama klip diputar | Klip dipasang lewat `clip()` sebagai layer footage yang terikat timeline, dibungkus wadah/perangkat/bingkai yang ikut dianimasikan, teks dan anotasi tetap hidup di atasnya (techniques.md §9b) |
+| Dua opener untuk produk berbeda sama-sama berlatar batang/potongan cahaya melesat ke samping ("lane" / "range") — hasil aturan "objek melintas tiap detik" | Gerak latar dipilih dari menu techniques.md §7c (gradien berpindah, blob, grain hidup, sapuan cahaya, bentuk berputar, partikel naik, grid bernapas…) dan berbeda dari proyek sebelumnya; aliran horizontal hanya untuk tema kecepatan/aliran |
+| Transisi: balok/persegi warna datar raksasa menyapu miring di setiap cut ("kotak persegi aneh"), atau garis tipis menyapu | Menu transisi techniques.md §4c: push-through 3D, kartu berputar dari kedalaman, objek berketebalan melewati lensa, mask bentuk brand, sapuan cahaya; minimal dua jenis, satu berkedalaman, wipe ≤ 2 |
+| Latar flat satu warna (gelap atau terang) dari awal sampai akhir | Permukaan latar ≥ 2 lapis dari menu §7d: glow horizon, duotone diagonal, mesh blob, spotlight + tint, langit berlapis, tekstur — warna dari palet |
+| Latar diam, atau warna latar tidak pernah berganti walau segmen/energi berubah | Latar selalu bergerak (§7c); warna latar boleh berganti kapan dibutuhkan asal ada pemicu terlihat: benda menutup lensa, aksi UI, push ke bidang warna, medan menyapu, cut di ketukan (techniques.md §7b) |
+| Menyalin palet, font, dan tata letak video referensi yang disodorkan user | Ambil ritme dan energinya saja; kulit lahir dari tema produk — katakan itu ke user satu kalimat |
+| Menampilkan `com.example.app` (nama package) di adegan CTA | Dihapus. User tidak peduli; kalau perlu, cukup baris hasil pencarian store |
+| Teks in/out dengan kamera statis | Ukuran shot berganti ke elemen yang sedang bercerita (techniques.md §3b) + koreografi elemen beririsan (§4b); napas kamera sebagai lapisan dasar; push-through hanya bila termotivasi, ±1 per video |
+| "Zoom in-out" dikerjakan sebagai napas kamera beberapa persen — tidak terlihat, video tetap terasa statis | Pergantian ukuran shot yang jelas: kamera mendekat ke elemen (medium close-up / close-up) lalu mundur ke wide saat komposisi butuh seluruh frame; label di lapisan layar supaya tidak terpotong (techniques.md §3b) |
+| Glow tebal 4 lapis di semua judul | Judul putih bersih + drop shadow tipis; glow disimpan untuk OBJEK (objek produk, ornamen) |
+| Latar warp 520 garis putih panjang | 300 partikel pendek berwarna gelap senada — latar tidak boleh bersaing dengan subjek |
+| Latar biru merata (flat) | Gradasi vertikal tegas: nyaris hitam di atas, menyala di horizon bawah |
+| Elemen UI (badge status) muncul mendahului kalimat utamanya | Urutan atensi: kalimat → objek utama → detail pendukung |
+| Zoom push-through dipakai di SEMUA transisi | Perpustakaan gerakan: spin, yaw 3D, roll, elemen terbang melewati lensa; zoom hanya saat termotivasi (mis. menyelam ke layar mockup). "Satu jenis transisi di semua cut" = template transisi PPT, cuma versi mahal |
+| Whip-pan translasi — tepi panggung tersingkap jadi gap hitam | Terbaca "pindah halaman". Jangan pernah menggeser dunia sampai tepinya terlihat |
+| Spin/yaw/roll kejut (zoom+putar tiba-tiba dengan blur di tiap cut) | Itu bahasa PRESET editor video, bukan motion design. Ganti: kamera bernapas + koreografi elemen beririsan + object wipe |
+| Demo UI terasa statis: UI penuh di frame, kamera diam, hanya kursor bergerak, klik terlalu kecil untuk terbaca | Kamera mengikuti interaksi bila perlu: dekati area yang akan diklik (scale 1,4–2,2, 0,6–0,9 dtk ease in-out), klik terbaca, lalu mundur/geser ke hasilnya; tidak di setiap klik (techniques.md §8) |
+| Opener produk berbeda-beda keluar dengan kerangka sama: teks zoom lalu keluar ke kiri, tiga tile fitur, kotak input diketik, hook → fitur → fitur → janji → logo → CTA — kesannya template walau warnanya baru | Tiga kandidat konsep dari `opener-konsep.md`, satu dipilih dari sifat produk; sidik jari struktur berbeda dari opener sebelumnya; komponen kanonik maks dua dan hanya bila dituntut konsep |
+
+## Pola gagal yang umum pada explainer
+
+Contoh explainer sejarah 30 dtk, 6 adegan, yang terasa seperti PPT. Kodenya:
+
+| Yang dibuat | Kenapa PPT | Yang seharusnya |
+|---|---|---|
+| 6 × `<section class="scene">` berisi foto full-bleed, dinyalakan `autoAlpha` bergantian | Ganti section = ganti slide, apa pun transisinya | Satu dunia yang mengalir; adegan berganti karena kamera/dunia bergerak atau whip ke sudut lain |
+| Tiap section: eyebrow (kicker) + judul 2 baris + kredit | Tiga tingkat teks = layout slide | Satu angka/kalimat besar + satu label yang hidup di dunia |
+| Gerak hanya Ken Burns foto 1.08 → 1.015 dan scale bump `#world` 1.12 → .96 di tiap cut | Gerak yang sama di semua cut = template | Parallax, objek melintas, whip, instrumen (peta/profil/speedometer), kamera bernapas beda per momen |
+| Light leak di setiap cut | Preset editor video | Simpan untuk satu momen istimewa |
+| Tidak ada subjek yang bertahan antar adegan | Tidak ada yang "dibawa" penonton | Hero hadir > 60 % durasi |
+
+Pelajaran: hukum naratif saja tidak cukup; perlu larangan struktural yang bisa diperiksa dari kode
+(SKILL.md → "Larangan struktural") dan starter yang memaksa rig yang benar
+(`assets/starter-explainer.html`).
+
+## Prinsip yang bisa dibawa ke proyek mana pun
+
+1. **Satu shot = satu pernyataan.** Kalimat ≤ 5 kata lebih kuat daripada
+   kalimat lengkap. "Dua kata. Satu pukulan." mengalahkan "Aplikasi ini
+   bisa melakukan X, Y, dan Z untuk kamu".
+2. **Hierarki atensi per adegan:** kalimat dulu, objek utama menyusul,
+   detail paling akhir — jangan pernah terbalik.
+3. **Teks panjang adalah bug.** Kalau sebuah klaim butuh > 6 kata,
+   pecah jadi dua adegan atau ubah jadi visual (ikon, angka, mockup).
+4. **Metadata bukan konten.** Nama package, URL panjang, versi, footnote —
+   buang. Penonton awam tidak membacanya, penonton teknis tidak membutuhkannya.
+5. **Mockup UI adalah pengecualian teks banyak** — layar aplikasi boleh penuh
+   teks kecil karena ia dibaca sebagai GAMBAR, bukan sebagai teks. Justru
+   itu: mockup harus setia pada aplikasi aslinya (font, warna, layout).
+6. **Gerakan adalah kalimatnya juga.** Zoom masuk = penekanan; pan menyusur =
+   pengungkapan bertahap; pull-back = reveal; bounce kecil = playful.
+   Pilih gerakan yang searti dengan kalimatnya, jangan acak.
+7. **Transisi ala motion designer, bukan preset editor.** Dua kegagalan
+   umum: whip translasi menyingkap tepi ("pindah halaman"); spin/yaw kejut
+   terbaca efek preset editor. Yang benar:
+   (a) kamera BERNAPAS — drift zoom pelan tanpa henti, tak pernah
+   menyentak; (b) perpindahan dikerjakan KOREOGRAFI ELEMEN yang keluar-
+   masuk beririsan waktu; (c) OBJECT WIPE — sebuah elemen/ornamen menyapu
+   dekat lensa menutup frame, adegan berganti di baliknya; (d) zoom cepat
+   hanya bila TERMOTIVASI (menyelam ke layar mockup). Efek kejut apa pun
+   (zoom/putar tiba-tiba + blur di tiap cut) adalah tanda bahaya.
+8. **Kamera adalah pemersatu.** Sekali kamu punya rig kamera yang menggerakkan
+   seluruh dunia, adegan-adegan terpisah terasa satu film. Tanpa itu,
+   berapapun polesan per adegan, hasilnya tetap deck yang di-autoplay.
+9. **Ritme keluar-masuk asimetris.** Masuk pelan-tegas (0.7–1.3 detik,
+   `power4.out`), keluar cepat (0.35–0.55 detik, `power2.in`). Simetris
+   terasa mekanis.
+10. **Pilih 1–2 momen istimewa.** Efek paling mahal (pan 3D per kata, logo
+   build-on) dipakai sekali-dua kali saja. Dipakai di semua tempat,
+   berhenti terasa istimewa.
+11. **Kalau ragu, gelapkan latarnya dan besarkan teksnya.** Kontras adalah
+    produksi termurah yang paling sering dilupakan.
+
+## Kalibrasi rasa (heuristik cepat)
+
+Screenshot sebuah frame lalu tanya:
+
+- Bisakah frame ini jadi slide korporat tanpa diubah? → gagal, rombak.
+- Apakah mataku tahu harus melihat ke mana dalam 0,2 detik? → kalau tidak,
+  kurangi elemen.
+- Kalau semua teks disembunyikan, apakah latarnya masih menarik tapi tidak
+  berisik? → keduanya harus ya.
+- Apakah ada sesuatu yang BERGERAK karena kamera, bukan karena elemen
+  menganimasikan dirinya sendiri? → harus ya di tiap transisi.

package/skills/bang-motion/references/architecture.md

@@ -0,0 +1,188 @@
+# Arsitektur — struktur proyek dan alasannya
+
+Tiap keputusan di sini pernah salah dulu sebelum benar. Bagian "kenapa"
+lebih penting daripada kodenya.
+
+## Struktur berkas
+
+```
+proyek/
+├── index.html          markup semua adegan + filter SVG motion blur
+├── css/app.css         token warna, layout adegan, state awal tersembunyi
+├── js/three-scene.js   dunia WebGL ber-state (latar, partikel, ornamen, bloom)
+├── js/timeline.js      SATU-SATUNYA tempat waktu ditulis (GSAP master timeline)
+├── js/util.js          splitChars + blurTween (motion blur berarah)
+├── js/main.js          perekat: fit stage, loop render, panel kontrol
+└── tools/
+    ├── serve.py        dev server Cache-Control: no-store
+    └── export-frames.mjs  render frame-by-frame (puppeteer)
+```
+
+Boleh dipadatkan jadi satu berkas (lihat `assets/starter-opener.html`) untuk
+prototipe; pecah ke struktur di atas begitu adegan > 3.
+
+## Panggung: 1920×1080 dipatok, lalu di-scale
+
+```css
+#stage{position:fixed;left:50%;top:50%;width:1920px;height:1080px;
+  transform:translate(-50%,-50%) scale(var(--fit));overflow:hidden}
+```
+```js
+const s = Math.min(innerWidth/1920, innerHeight/1080);
+```
+
+**Kenapa:** komposisi tidak boleh berubah karena ukuran jendela. Posisi yang
+disetujui di monitor 27" harus identik saat direkam. Ukuran jendela hanya
+mengubah zoom, bukan layout.
+
+## Rig kamera `#world`
+
+```
+#stage
+└── #world            ← rig kamera: DI-SCALE/TRANSLATE oleh timeline
+    ├── <canvas>      ← WebGL (latar 3D)
+    ├── .bgfx         ← gradient overlay (blend screen)
+    └── #dom          ← semua adegan teks/UI
+├── .leak             ← light leak: DI LUAR world, lapisan paling atas
+├── .vignette, .grain
+```
+
+**Kenapa world membungkus canvas juga:** saat kamera zoom, yang ikut membesar
+harus teks DAN latarnya.
+Men-zoom layer teks saja terasa palsu; men-zoom seluruh dunia terasa kamera.
+Light leak justru HARUS di luar world: ia cahaya di depan lensa, bukan
+bagian dunia.
+
+## State-driven WebGL
+
+Scene Three.js tidak tahu apa-apa soal waktu. Ia mengekspos satu objek:
+
+```js
+const state = {
+  grid: 0, dust: .5, nebula: .6, stars: 0, tunnel: 0, flow: 0,
+  camX: 0, camY: 0, camZ: 16, camRoll: 0, bloom: .85, shake: 0,
+  heroO: 0, heroS: 1, heroX: 0, heroY: 0, heroZ: 6,   // ornamen utama
+};
+```
+
+dan timeline GSAP men-tween angka-angka itu. Fungsi `render(t)` menerima
+`t = tl.time()`.
+
+**Kenapa:** satu sumber kebenaran waktu. Scrub, pause, dan export otomatis
+benar karena WebGL tidak punya jam sendiri.
+
+**Aturan `flow`:** benda yang "mengalir" (tunnel, hujan partikel) disimpan
+sebagai JARAK yang di-tween (`flow: '+=300'`), posisi tiap partikel =
+`(seed + flow*speed) % span`. JANGAN `pos += speed*dt` — itu akumulasi yang
+membuat scrub dan export tidak reproducible.
+
+## Timeline: detik absolut
+
+```js
+tl.fromTo(chars, {...}, {...}, 8.10);   // ← angka absolut, bukan "+=0.3"
+```
+
+**Kenapa:** rundown adegan berisi angka detik; menulis angka yang sama di
+kode membuat urutan terbaca sekali lihat, dan menggeser satu adegan tidak
+merembet ke adegan lain. Sediakan konstanta `DURATION` di satu tempat.
+
+## State awal di CSS, bukan di GSAP
+
+```css
+.hero, .line, .obj, .ornament { opacity: 0 }
+```
+```js
+tl.fromTo(el, {opacity:0,y:60}, {opacity:1,y:0, immediateRender:false}, 8.1);
+```
+
+**Kenapa:** dengan `immediateRender:false`, CSS-lah yang memegang keadaan
+sebelum tween mulai — tanpanya semua elemen berkedip di frame pertama.
+
+**JEBAKAN yang pernah terjadi:** selector state awal kalah spesifisitas.
+`.card.ghost{opacity:.85}` mengalahkan `.card{opacity:0}` sehingga elemen
+muncul mendahului animasinya. Jangan pernah menulis `opacity` di selector
+yang lebih spesifik dari selector state-awal; biarkan GSAP yang memberi
+nilai akhirnya.
+
+## Determinisme — daftar larangan
+
+| Larangan | Gantinya |
+|---|---|
+| `Math.random()` di render loop | sinus frekuensi tinggi: `Math.sin(t*137.2)` |
+| `Date.now()` / `performance.now()` | `tl.time()` diteruskan sebagai parameter |
+| `setInterval` untuk teks berjalan/mengetik | tween `{i:0→n}` + `onUpdate` slice |
+| akumulasi `pos += v*dt` | posisi = fungsi(seed, state.flow) |
+| `Math.random()` saat SETUP boleh | seed dibuat sekali saat load, bukan per frame |
+
+## Dev server wajib no-cache
+
+`python -m http.server` membiarkan browser menahan module JS lama lewat
+heuristic caching — edit "tidak ngefek", dan kamu akan mengejar hantu.
+Selalu pakai server yang mengirim `Cache-Control: no-store`
+(`scripts/serve.py`). ES module tidak jalan lewat `file://`, jadi server
+memang wajib.
+
+## Verifikasi vs export — dua hal berbeda
+
+- **Verifikasi** (setiap batch perubahan): `scripts/snap.mjs` memotret
+  6–20 detik kunci lewat `OPENER.seek(t)`; hasilnya dilihat, bukan
+  disimpan. Tanpa Node: `?debug=1` + screenshot manual.
+- **Export** (hanya bila user minta MP4): render semua frame. Jangan
+  tertukar — merender penuh untuk "ngetes" membuang ribuan gambar dan tidak
+  memberi penilaian apa pun.
+
+## Export ke video
+
+Jangan merekam layar untuk hasil final (frame drop). Karena semuanya
+deterministik: set `tl.time(frame/fps)` → tunggu 2× rAF (satu untuk GSAP
+menulis style, satu untuk render loop menggambar) → screenshot → ulangi.
+`scripts/export-frames.mjs` melakukannya via puppeteer; gabungkan dengan:
+
+```
+ffmpeg -framerate 60 -i frames/f%05d.png -c:v libx264 -pix_fmt yuv420p -crf 16 out.mp4
+```
+
+Ekspos `window.OPENER = { tl, DURATION }` supaya skrip export (dan debugging
+konsol) bisa mengendalikan timeline.
+
+## Panel kontrol developer — tersembunyi
+
+Jangan tampilkan player di deliverable. Default: autoplay saat dibuka, loop
+saat selesai, R ulang, Space jeda. Panel (play/pause, slider scrub, jam
+`t.toFixed(2)`) hanya muncul dengan `?debug=1`; `?clean=1` = tanpa panel dan
+tanpa autoplay untuk skrip export. Scrub tetap alat review utama user —
+mereka berpikir dalam "detik ke-X" — tapi lewat URL debug, bukan di hasil.
+
+## Verifikasi visual (bukan opsional)
+
+Setelah tiap batch perubahan: buka di browser, `tl.pause(); tl.time(X)` di
+konsol untuk tiap detik kunci, screenshot, nilai dengan heuristik di
+`anti-ppt.md`. Kode yang jalan ≠ adegan yang benar; hampir semua revisi
+user datang dari MELIHAT, bukan dari error.
+
+
+## Bentuk deliverable: satu berkas, tanpa server
+
+Selama pengembangan boleh multi-file (css/, js/) + server no-cache. Tapi yang
+DISERAHKAN adalah satu `index.html` yang bisa diklik dua kali:
+
+- `<style>` dan `<script type="module">` ditulis inline. Alasannya teknis:
+  Chrome menolak `<script type="module" src="js/app.js">` dari `file://`
+  (origin `null` → CORS), sedangkan module inline boleh meng-`import` dari
+  CDN https tanpa masalah.
+- Import map + GSAP/Three dari CDN tetap dipakai (butuh internet, tidak butuh
+  server). Font Google juga.
+- Aset lokal (ikon, gambar) cukup path relatif — `<img src="icon.png">`
+  aman di `file://`.
+- Hindari `fetch()`/XHR ke berkas lokal — itu diblokir di `file://`.
+- Node/puppeteer hanya untuk render MP4; jangan sampai user mengira opener
+  butuh `node_modules`. Jelaskan itu di README. Tanpa Node: rekam layar
+  (dengan catatan bisa drop frame). Tanpa Python: tidak ada yang hilang —
+  server hanya perlu bila memakai module lokal, dan deliverable satu-berkas
+  tidak memakainya.
+- Skrip render/snap memakai default `pathToFileURL(process.cwd())` supaya
+  bekerja tanpa server; URL http tetap bisa dioper lewat env `URL`.
+
+Proses inline yang aman: baca css & js, ganti tag `<link>`/`<script src>`
+dengan isinya, pastikan JS tidak mengandung `</script>`, lalu hapus folder
+sumbernya supaya tidak ada dua kebenaran.