FAÍSCA は何をしますか？
起動キーワード: faísca. ユーザーが「faísca」と入力し、動画のテーマ、フレーズ、フォーマットを説明すると、このスキルがプロジェクトを作成し、タイムラインを構築し、MP4をレンダリングします。
SKILL_DIR = このファイルのフォルダ。コンポジションは HyperFrames（HTML + GSAP）を使用し、タイムラインを SLOW 倍に引き伸ばして60fpsでレンダリングします。render-faisca.sh は各 SLOW サブフレームの平均を計算し、結果として本物のモーションブラーを生成し、After Effectsのような見た目を実現します。
- 既存のエフェクトカタログ、タイミング、コード内の位置:
referencias/efeitos.md - リファレンス動画の分析（計測、フォントと色の比較）:
referencias/recriar-referencia.md - コードで作曲されたオリジナルトラックと、オーディオに反応するモーション:
referencias/trilha-propria.md、テンプレートはtrilha/ - HyperFrames 契約:
hyperframesスキルがインストールされている場合、構造を変更する前に読むこと。npx hyperframes docs gsapとnpx hyperframes docs data-attributesも役立ちます。
最初に行うこと
- 作品のクライアント. 公開者のブランドカラーとフォントを使用します。ブランドが指定されていない場合は、デフォルトのライムグリーンを使用します。
- 伝える内容. 画面ごとに短いインパクトのあるフレーズ（2～4語）と、連続したキャプション。ユーザーから指定されたコンテンツのみを使用し、何も創作しないこと。
- フォーマットと尺. デフォルトは16:9。Reels や TikTok は 9:16（
referencias/efeitos.mdの末尾参照）。ナレーションなしの場合、スタイルは4～15秒に収まる。ナレーションありの場合はさらに長くできるが、各画面は 0.4～0.8 秒ごとに切り替えること。 - フォルダ. 動画ごとに専用のフォルダを作成し、可能な限り同期フォルダ（iCloud、Dropbox）の外に配置すること。
- クレジットなし. すべてローカルで動作する。
ステップ1 · プロジェクトの作成
SKILL_DIR/scripts/novo-faisca.sh <プロジェクトフォルダ>
hyperframes init を実行し、テンプレート（動作する4秒のコンポジション、ローカルフォント）をコピーし、lint が 0 エラーであることを確認します。OK: が表示されない場合は、停止して修正すること。
ステップ2 · アイデンティティ
- アクセントカラー:
:root内の4つの変数--acento、--acento-rgb、--acento-claro、--acento-escuro。すべてのエフェクト（グロー、スパーク、レーザー、ピル、プレート、3D）はこれらから派生します。 - フォント:
assets/fonts/に配置し、ファイル自体で@font-faceを使用すること（lintはローカルファイルを要求します）。タイトル用のフォントは、太くてコンデンスされたものに変更すること。事前に測定すること（recriar-referencia 参照）。 - HUD (
#hudBrand): 作品のブランド名。他の会社のブランド名を決して使用しないこと。
ステップ3 · スクリプトとタイムライン
- ショットリストを作成する: 各イベントの時刻（実時間の秒数）、テキスト、カタログから選んだエフェクトをリストアップする。各アイデアは 0.4～0.8 秒ごとに配置する。
DURを調整し、同時に#rootと#stageのdata-durationをDUR × SLOWに設定する（render-faisca.shは一致しないと拒否します）。// ---------- linha do tempoブロック内のテキストと時刻を置き換える。新しいシーンの場合は、カタログのエフェクトのパターンをコピーする。位置を追跡するエフェクトはdraw(t)に記述する。SLOW = 8でほぼすべてのケースをカバーできる。ズームや非常に速い通過は8サンプルでは「リング」アーティファクトが発生する: 16に上げる（レンダリング時間は2倍になる）。- ナレーションありの場合: 各単語のタイミングを取得し（Whisperなど）、推測ではなくそれらの時刻にエフェクトを固定する。
ステップ4 · フレームレビュー
SKILL_DIR/scripts/quadros.sh <プロジェクト> 0.3,0.9,1.3,1.6,2.3,2.7,3.2,3.6,3.9
時刻は実時間の秒数（スクリプトが SLOW を乗算します）。シートを確認すること: テキストが途切れている、単語の位置がずれている、エフェクトが表示されない。フレームは単一サンプルであり、ブラー効果はありません。
ステップ5 · レンダリングと検証
SKILL_DIR/scripts/render-faisca.sh <プロジェクト> <プロジェクト>/renders/<名称>.mp4 [--audio トラック.wav]
SKILL_DIR/scripts/render-faisca.sh <プロジェクト> /tmp/sabotagem.mp4 --sabotar # これは FAIL する必要がある
レンダラーは3つの項目をチェックします: data-duration = DUR × SLOW、60fpsでのフレーム数、そしてブラーの存在（最終的な動画が、動きのある部分で単一サンプルと異なる必要があります）。--sabotar はブラーなしで生成し、ERRO: sem desfoque で終了する必要があります: これによりチェックが正しく失敗することを証明できます。4秒のレンダリングはマシンにもよりますが、約1～4分かかります。
npx hyperframes check も実行されますが、レイアウト監査は設計上の理由でエラーを報告することがあります: まだ表示されていないキャプションの単語（透明、text_not_painted）や3Dレイヤーの重なり（content_overlap）。必須条件: lint エラー0。これらのレイアウト指摘は想定内です。
ステップ6 · 納品
- MP4 を納品し、その場所を伝える。
- 依頼と異なる点を隠さずに説明する。
- 他者の動画の研究: 比較画像は研究目的のみとし、公開しないこと。
既知のトラップ
| 症状 | 原因と修正方法 |
|---|---|
| プロシージャルエフェクトが消えたり、特定のフレームで停止する | draw(t) が状態を保持したりDOMを測定していた。t の純粋関数にする必要がある。build() で測定すること |
| バーが震えて上昇しなくなる | draw が GSAP でアニメーション中の同じ要素に style.transform を書き込んでいた。震えは子要素（#rbInner）に移動すること |
| 非表示の要素がレンダリングに現れない | fromTo で opacity: 1 を「from」だけに設定している。ターゲット側にも opacity: 1 を設定すること |
| キャプションのピルが不可視 | z-index: -1 がスタッキングコンテキストなし。単語に isolation: isolate を設定すること |
| プレビューフレームが間違った時刻に表示される | --at のスナップショットは引き伸ばされたタイムライン上の時刻。quadros.sh を使用すること（SLOW を乗算します） |
| 最終ズームでリングアーティファクト | 8サンプルでは指数関数的なスケールに不十分。SLOW = 16（data-duration も同時に変更） |
| 撮影したリファレンスの色が異なって見える | カメラで画面を撮影すると色が変わってしまう。サンプルではなく、元の色を使用すること |
| プレビューフレームがすべて同じ（背景のみ） | ツールが build() の完了前にキャプチャした。quadros.sh はすでに20秒待機する |
| レンダリングが遅い、またはフリーズする | 一時ファイルが同期フォルダにある。スクリプトは MOTION_TMP またはシステムの一時フォルダを使用する |
| レンダリングが数十GBのディスク容量を要求する | 並列キャプチャで各フレームを記録している。render-faisca.sh はすでに HF_CAPTURE_PARALLEL_STREAM=true を設定している |
className や textContent が GSAP で変更されない | GSAP 3 は set でこれらのプロパティを適用しない。draw(t) で、t の関数として変更すること |
translateX(-50%) で中央揃えした要素が位置から外れる | GSAP のスケールが transform を上書きする。xPercent: -50 で中央揃えすること |