HyperFrames 品質ゲート
概要
優れた HyperFrames の実行と平凡なものの差は創造性ではなく、検証の規律です。優れた実行は、すべてのフレームを、複数のシーク時点でピクセルが確認されるまで未証明として扱います。平凡な実行はチェッカーを信頼し、リントが最初に通ったものをそのまま出荷します。
核となる原則: リントは矩形と属性をチェックしますが、レンダリングされたピクセルだけが真実を語ります。確認せずにフレームを完了と宣言してはいけません。
不可欠なゲート
構築または編集するすべてのフレームに対して、これらの手順を順番に実行してください。「小さな変更だから」という理由でゲートをスキップすると、品質が低下します。
- ストーリーボード自体の
## Video directionブロックを読み、プリセットのボイラープレートよりも優先します。 ストーリーボードが文の大文字小文字ルールを指定し、プリセットの frame.md が大文字を指定している場合、ストーリーボードが優先されます。プロジェクトの方向性 > プリセットのデフォルト。 - フレームごとに1つの主要な動き。 フレーム内で2つの要素が同時に解決しようとしている場合、1つを削除します。すべてを前倒ししてからフリーズする（「スライドショーモード」）と、すべてを浮かせる（「スクリーンセーバーモード」）は、どちらも失敗です。
- 機械的なトラップの自己チェック（下の表）を、完了と報告する前に自分のファイルでgrepして実行します。
- 完了と報告する前に、ブラウザでシークテストを実行します。
<template>をクローンし、タイムラインを登録し、timeline.seek(t, false)を次の時点で実行します: t=0、各シーン境界 ±0.05s、および最終フレーム。それぞれをスクリーンショットします。それらを確認します。 シークテストなしのフレーム報告は、未検証の主張です。suppressEventsトラップ: 裸の.seek(t)はonUpdateコールバックを抑制します — カウンター/タイピングがハーネスでは壊れて見えても、レンダラーでは正常に見えます。常にfalseを渡します。
- リタイミング後は常に、影響を受けたクリップの
data-start/data-durationを再導出します。 GSAP トゥイーン時間とクリップ表示ウィンドウは2つの独立したシステムです。一方だけをリタイミングすると、不可視要素や無音ギャップが発生します。これは最も多い回帰原因です。 - アセンブリ後、すべてのカット境界と各フレームの中間点でフルビデオのスナップショットを取得し、コンタクトシート画像を自分で読み取ります。 間違っている部分を修正し、再スナップショットし、その後にレンダリングします。
機械的トラップ表（自分のファイルでこれらをgrep）
| トラップ | 症状 | 修正方法 |
|---|---|---|
id が数字で始まり + querySelector("#...") | SyntaxError がタイムライン登録を静かに失敗させる → 空白フレーム | id に文字を前置するか、または getElementById を先に使用する |
GSAP アニメーション要素に対する CSS transform: | 最初のトゥイーンで GSAP が CSS オフセットを上書きする | オフセットを left/top に焼き付ける; transform は GSAP のみに属する |
パディングされたカードに box-sizing: border-box がない | 幅が膨張し、センタリングがずれ、カードが衝突する | すべてのパディングされたカードに設定する |
fonts.gstatic.com / 任意のCDN を指す @font-face | 非決定論的レンダリング; オフラインで壊れる | assets/fonts/ 下のローカルファイル、プロジェクトルート相対パス |
| 目視による重なり計算 | 後のカードが前のカードのテキストを埋める | getBoundingClientRect() でホールド時間の矩形を計算する; すべての重なり合う要素のキーテキストがスクリーンショットで見えることを確認する |
| クリップ/タイトな行送りのテキストに対するチェッカーの重なり検出 | 誤検出（矩形は重なるがグリフは重ならない） | 最初にピクセルを確認し、その後 data-layout-allow-overlap を使用する — 決して盲目的に抑制しない |
| 電話モックアップ内でのスクリーンショットの引き伸ばし/色の変更 | 不自然なデバイス | 常にネイティブアスペクト比; overflow:hidden でトリミングし、均一でないスケーリングは行わない |
外部ボリューム上の ._* AppleDouble ファイル | ビルド/レンダリングを壊す | アセンブル/レンダリング前に find . -name '._*' -delete を実行する |
| Node < 22 | CLI が失敗する | 前置: export PATH="$HOME/.nvm/versions/node/v22*/bin:$PATH"（または nvm use 22） |
オーケストレーションパターン（マルチフレームビルド）
- フレームごとに1つのワーカー、ワーカーごとに1つのファイル。ワーカーは共有ファイルに触れません。
- ワーカーをディスパッチする前に、共有アセット（フォント、ロゴ、スクリーンショット）をステージします。パケットは正確なパスを指定します。
- すべてのパケットには以下が含まれます: そのフレームのストーリーボードブロックの原文、グローバルな Video direction ブロック、上記のトラップ表、およびシークテストの要件。
- オーケストレーターは、ワーカーが報告した内容に関係なく、アセンブリ後に lint + check + コンタクトシート検査を再実行します。ワーカーの自己報告は主張であり、証拠ではありません。
危険信号 — 停止して確認
- 「リントとチェックに合格したので、フレームは正しい」→ チェックは埋もれたテキストや無音を検出しません。ピクセルを見てください。
- 「トゥイーンをリタイムしました。完了です」→ クリップの
data-*ウィンドウもリタイムしましたか？ - 「シークテストはスキップします。コードは簡単です」→ 空白フレームのバグ（数字idセレクター）は簡単なコードにあり、シークテストだけがそれを捕捉しました。
- 「そのカードはおそらくもう一方を覆わないでしょう」→ 矩形を計算し、その後スクリーンショットを確認してください。
- 「CDNフォントは今回だけは大丈夫です」→ 大丈夫ではありません。レンダリングはネットワークフリーでなければなりません。
これらすべては、スキップしようとしていたゲートを実行することを意味します。