HyperFrames 品質關卡
概述
一個優秀的 HyperFrames 執行與平庸執行之間的差距，不在於創意，而在於驗證紀律。優秀的執行將每個影格視為未經證明的，直到其像素在多個尋點時間被檢視過。平庸的執行則信任檢查器，並在程式碼通過 lint 後就直接產出。
核心原則：lint 工具檢查的是矩形和屬性；只有渲染後的像素才能說真話。在親眼看到影格之前，永遠不要宣告一個影格完成。
非協商關卡
對於你建立或編輯的每個影格，必須依序通過這些關卡。因為「只是一個小改動」而跳過關卡，就是品質下降的原因。
- 閱讀故事板本身的
## Video direction區塊，並遵守它，而非預設的樣板。 當故事板要求 sentence case 而預設的 frame.md 使用大寫時，以故事板為準。專案方向優先於預設設定。 - 每個影格只有一個主要動態。 如果你的影格同時有兩個元素在動作，刪減其中一個。先讓所有元素動起來然後靜止（「幻燈片模式」），以及所有元素持續漂浮（「螢幕保護模式」）都是失敗的。
- 自我檢查機械陷阱（見下方表格），在宣告完成之前，在你的檔案中 grep 檢查這些陷阱。
- 在瀏覽器中進行尋點測試後再回報完成。 複製
<template>，註冊時間軸，然後在以下時間點執行timeline.seek(t, false)：t=0、每個場景邊界 ±0.05 秒，以及最後一幀。為每個時間點截圖。檢視它們。 沒有經過尋點測試的影格報告是未經驗證的主張。suppressEvents陷阱：單純的.seek(t)會抑制onUpdate回呼 — 計數器/打字效果在你的測試環境中看起來壞了，但在渲染器中是正常的。務必傳入false。
- 在重新定時後，重新推導受影響剪輯的
data-start/data-duration。 GSAP 動畫時間和剪輯的可見時間窗口是兩個獨立的系統；只重新定時其中一個而不更新另一個，會導致不可見的元素或靜默間隙。這是回歸問題的頭號來源。 - 組裝後，在每個剪輯邊界和每個影格的中點為完整影片拍攝快照，並親自閱讀聯絡表圖像。 修正看起來不對的地方，重新拍攝快照，然後才進行渲染。
機械陷阱表格（在你的檔案中 grep 這些）
| 陷阱 | 症狀 | 修復方法 |
|---|---|---|
id 以數字開頭 + querySelector("#...") | SyntaxError 靜默地終止時間軸註冊 → 空白影格 | 在 id 前加上字母，或先使用 getElementById |
CSS transform: 用於 GSAP 動畫的元素上 | GSAP 在第一次動畫時覆蓋 CSS 偏移量 | 將偏移量設定為 left/top；transform 只屬於 GSAP |
在內邊距卡片上缺少 box-sizing: border-box | 寬度膨脹、置中偏移、卡片碰撞 | 在每個有內邊距的卡片上設定 |
@font-face 指向 fonts.gstatic.com / 任何 CDN | 非確定性渲染；離線時中斷 | 本地檔案位於 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） |
編排模式（多影格建置）
- 每個影格一個工作程序，每個工作程序一個檔案；工作程序絕不觸碰共享檔案。
- 在分派工作程序之前，暫存共享資產（字型、標誌、螢幕截圖）；資料包指定確切路徑。
- 每個資料包包含：該影格的故事板區塊原文、全域的 Video direction 區塊、上述的陷阱表格，以及尋點測試要求。
- 無論工作程序回報了什麼，編排器在組裝後都重新執行 lint + check + 聯絡表檢查 — 工作程序的自我回報只是主張，不是證明。
紅旗 — 停下來驗證
- 「Lint 和 check 通過了，所以影格是正確的」 → 檢查無法看到被埋沒的文字或靜默間隙。請看像素。
- 「我重新定時了動畫；完成了」 → 你也重新定時了剪輯的
data-*時間窗口嗎？ - 「我會跳過尋點測試，程式碼很簡單」 → 空白影格錯誤（數字開頭的 id 選擇器）正是在簡單的程式碼中出現，而且只有尋點測試抓到了它。
- 「那張卡片大概沒有覆蓋另一張」 → 計算矩形；然後截圖。
- 「這次就用 CDN 字型，沒關係的」 → 不行；渲染必須在無網路環境下進行。
以上所有情況都意味著：執行你正打算跳過的那個關卡。