シークセーフモーション
HyperFramesはタイムラインを再生しません。シークします。各フレームに対してレンダラーはタイムラインをそのフレームの時間に設定し、ページをキャプチャします。HyperFrames 0.8.xでは、これを3つのワーカーで並列に実行し、各ワーカーが3フレームごとに担当し、各シークは1ms戻ってから前に進むことで安定させます。そのため、すべてのフレームは時間の純粋関数でなければなりません。以前にレンダリングされたもの、クロック、または偶然に依存するものは、ワーカーごとに異なるレンダリング結果を生み、結果として3フレームごとに要素が欠落する現象が発生します。
このバグはStudioプレビュー(順次再生)や単一スナップショットでは見えません。このスキルが生まれたプロダクションでは、レビュアーに届く唯一の欠陥でした。オープニングタイトルが最初の7秒間「スタッタリングしてフラッシュ」するというものでした。
まずはLint
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/seek-safe-motion/scripts/lint_motion.py" <video_dir>/video
これはindex.html、src/*.tpl、およびそれらに隣接する*.js(インラインスクリプトのみ)を読み取り、file:line: severity RULE: whyに加えて修正内容を出力し、エラーがあれば終了コード1で終了します(--strictで警告も失敗扱い、--jsonでツール向け出力)。タイムラインを編集するたび、およびレンダリングの前に実行してください。これは静的解析であり、実行時に計算される変数(「チェック不可」としてカウント)や、時間的に重なる2つのトゥイーンを検出できません。それらは以下の再現方法に従って、あなたが確認する必要があります。qa.py(render-qa)もこれを実行し、エラーがあればレポートを失敗として報告します。
ルールとその存在理由
- すべての
fromToのfromVarsのキーはtoVarsにも存在すること(SS001、エラー)。ワーカーのフレームがトゥイーンの開始位置にちょうど当たった場合、1msのバックステップでトゥイーンは開始前に戻り、fromVarsにのみ存在するキーは二度と書き込まれません。タイトルトゥイーンはfromTo(sel, {yPercent: 110, opacity: 1}, {yPercent: 0})でした。opacity: 1はfromVarsにのみ存在したため、1つのワーカーがトゥイーンの残りの間、タイトルをopacity 0のままにしました。{yPercent: 110, opacity: 1}から{yPercent: 0, opacity: 1}と書くか、tl.set()の後にtl.to()を使用してください。to()内のstartAtについても同様です(SS002)。 - 時刻0以降のすべての
fromToにimmediateRender: false(SS003、警告)。そうしないと、トゥイーンはタイムラインが構築されたときに開始値を書き込み、以前のトゥイーンが設定したものを上書きし、タイムラインの途中にシークすると間違った状態から始まります。 fromよりもfromToを優先(SS004、警告)。from()は、要素が構築時に持っていた値で終了します。以前のトゥイーンが要素に触れると、ワーカー間で合意が得られなくなります。displayやvisibilityをアニメーションさせない(SS005、エラー)。これらは補間できません。トゥイーンの任意の時点で切り替わります。明示的な時刻で持続時間ゼロのtl.set()を使って変更し、opacityまたはautoAlphaでフェードさせてください。- クロック、偶然、タイマー禁止(SS006、エラー):表示されるものに対して
Date、performance.now()、Math.random()、setTimeout、setInterval、requestAnimationFrameを使用しないでください。タイピングのジッターや波形はシード付きジェネレーターを使用します。画面に表示される通話タイマーは、タイムラインのonUpdate内でtl.time()から計算します。 - 一時停止したタイムラインを1つ登録し、決して再生しない(SS007、SS011、SS012)。
gsap.timeline({ paused: true })で作成し、完全に構築(テキストメトリクスに依存する位置の場合はdocument.fonts.ready内で)してから、window.__timelines["<composition id>"] = tlを割り当てます。構築が完了する前に空のタイムラインを登録すると、空白のビデオがレンダリングされます。tl.play()はレンダラーのシークと競合します。 - スクロールは開始と終了を明示した
fromToにする。すべてのワーカーが同じオフセットを計算し、実際のコンテンツにクランプされるため、ラインやアイコンの停止が端で途切れません。 - 同じ要素の同じプロパティに対して2つのトゥイーンを同時に持たせない。次の移動内に収まったカーソルリセットは、シーク後にポインターを間違った位置に残しました。lintはチェックしません。ビルドのタイミングテーブルを確認してください。
- レイアウトではなく変換をアニメーションさせる(SS009、警告):
left、top、width、marginの代わりにx、y、scale、clip-pathを使用します。レイアウトトゥイーンはフレームごとにリフローし、hyperframes checkでgsap_non_transform_motionとしてフラグが付けられます。実際の製品コントロール(サイドバーの展開)での短い幅変更は、製品を再現する場合に受け入れられます。 .clip要素をトゥイーンさせない(SS010、エラー)。HyperFramesはdata-startとdata-durationを通じてクリップの可視性を管理します。その内部のラッパーをアニメーションさせてください。- 有限の繰り返し(SS008、警告)。
repeat: -1は有限のルートdata-durationの下でのみ許可されます。Math.max(0, Math.floor(span / period) - 1)でカウントを計算してください。 - すべての初期状態を時刻0で明示的に設定する。
gsap.set(sel, vars)を行うヘルパーは、tl.set(sel, vars, 0)も実行して、0にシークし直したときに、ワーカーがレンダリングした最後の状態を保持するのではなく、最初のフレームを復元するようにします。
レンダリング前に疑わしいバグを再現する
lintはパターンを見つけます。スナップショットはピクセルを証明します。t0で開始する疑わしいトゥイーンの場合:
npx --yes hyperframes@<pinned> snapshot . --at <t0 + 0.3> --no-end --describe false -o a
npx --yes hyperframes@<pinned> snapshot . --at <t0>,<t0 + 0.3> --no-end --describe false -o b
t0 + 0.3のフレームはaとbで同一でなければなりません。異なる場合、トゥイーンの開始をシークすることで状態が変化しています。1つのワーカーを正確に再現するには、フレーム0, 3, 6, ...をその順序で、トゥイーンを少し過ぎたところまでスナップショットしてください。時間範囲を半分にして、1つのトゥイーンが残るまで二分探索します。レンダリング後、scan_render.py(render-qa)は同じバグをWORKER PATTERN実行として報告します。つまり、すべてが1つのフレームインデックスmod 3を共有する外れフレームです。
リファレンス
references/patterns.md: 各ルールの修正前後のコード、テンプレートを安全に保つヘルパー(lineIn、init、タイピング、スクロール、カーソルクリック)、およびlintが検出できるものとできないもの。新しいヘルパーを作成するときやlintの指摘を修正するときに読んでください。