hyperframes-keyframes

HyperFrames Keyframes

關鍵影格是一種姿勢合約：可見狀態、連續主體身份、可搜尋的執行時間、經過驗證的像素。

使用 hyperframes-animation 處理廣泛場景配方。
使用 hyperframes-cli 查閱完整命令文件。
僅在選擇實作機制而非視覺風格時，才使用 references/keyframe-patterns.md。

程序

1. 識別動畫主體、可見狀態、最終狀態及執行時間。
2. 選擇能證明提示的最小機制。僅在機制不明確時閱讀 references/keyframe-patterns.md。
3. 在宣告的執行時間內撰寫可搜尋的關鍵影格。同步建構並註冊執行時間實例。
4. 使用 lint、validate、hyperframes keyframes、一個聚焦的 --shot 以及在證明時間點的快照進行驗證。
5. 若驗證失敗，修正來源關鍵影格，並在渲染前重新執行最小的失敗診斷。

合約

• 命名移動中的主體。
• 命名證明預期動作所需的姿勢，包括最終狀態。
• 關鍵影格應針對可見通道，而非隱藏的輔助狀態。
• 當連續性重要時，保持物件身份不變。
• 僅在預期動作為替換或溶解時使用交叉淡出。
• 保持可讀或語義狀態足夠長的時間以便觀察。
• 最終影格是動畫的一部分，而非清理。
• 除非要求，否則不要重置為靜止狀態。
• 除非要求，否則不要以黑色結束。
• 若編輯起始場景，除非要求重新設計，否則保留佈局、文案、素材、顏色及最終狀態。

執行時間規則

GSAP：

• 在頁面載入時同步建構
• 使用 gsap.timeline({ paused: true })
• 註冊為 window.__timelines[compositionId]
• 註冊鍵必須與 data-composition-id 相符
• 不要為渲染關鍵動作呼叫 tl.play()
• 保持重複次數有限

CSS 關鍵影格：

• 有限的持續時間和迭代次數
• 確定性的延遲
• animation-fill-mode: both
• 當時間屬於某個片段時使用 data-start

Anime.js：

• 同步建立
• autoplay: false
• 有限的持續時間和循環次數
• 將每個實例推入 window.__hfAnime

WAAPI：

• 有限的 duration
• fill: "both"
• 確定性的建構
• 文字表面不列出 WAAPI；使用 --shot（它會搜尋 WAAPI）和快照驗證

絕不用於渲染關鍵動作：

• Date.now()
• performance.now()
• 未設定種子的 Math.random()
• 懸停/滾動觸發
• 計時器
• 非同步建立的時間軸
• 未註冊的 requestAnimationFrame
• 無限循環

GSAP 骨架

const root = document.querySelector("[data-composition-id]");
const compositionId = root.dataset.compositionId;
const tl = gsap.timeline({ paused: true });

tl.addLabel("state-a", 0);
tl.to(".subject", {
  keyframes: [
    { x: 0, opacity: 1, duration: 0.2 },
    { x: 120, opacity: 1, duration: 0.4, ease: "power2.out" },
    { x: 100, opacity: 1, duration: 0.2, ease: "power2.inOut" },
  ],
  ease: "none",
});

window.__timelines = window.__timelines || {};
window.__timelines[compositionId] = tl;

使用標籤表示語義狀態。
使用位置參數而非鏈式延遲。
對後續影響相同屬性的 from()/fromTo() 補間使用 immediateRender: false。

關鍵影格形式

• 陣列關鍵影格：帶有逐步驟持續時間/緩動的姿勢階梯。
• 百分比關鍵影格：單一補間內的精確時間。
• 屬性陣列：緊湊的多停止點變化。
• 當每個停止點自帶緩動時，父級使用 ease: "none"。
• 當每個區段應共享相同感覺時使用 easeEach。

不要從範例複製數值距離或時間。應根據實際合成幾何和持續時間推導。

對於在兩個方框之間移動的單一主體，偏好使用一個連續的變換補間或 FLIP。僅在觀眾應感受到不同節拍時，才將 x/y/scale 拆分為多個帶緩動的關鍵影格；每個區段都會改變速度，可能被解讀為卡頓。

通道

偏好合成器/視覺通道：
x/y/z、xPercent/yPercent、scale、rotationX/Y/Z、skew、transformOrigin、svgOrigin、opacity、autoAlpha、clip-path、遮罩、CSS 變數、SVG 路徑/虛線值、攝影機變換、著色器統一變數。

避免佈局/生命週期通道：
top/left/right/bottom、width/height、margin/padding、display、visibility、後期 DOM 建立、執行主體動作的輔助疊加層。

機制選擇

選擇能證明提示的最小機制：

需求	機制
相同主體改變方框或層級結構	共享元素 / FLIP
主體沿可見路徑移動	路徑旅行
筆畫增長或描繪	筆畫繪製
形狀變成另一形狀	形狀插值
揭示邊界可見	裁剪、遮罩或著色器統一變數
多個項目按順序移動	交錯 / 索引延遲
文字本身移動	行、詞、字元或帶狀細分
表面彎曲、拉伸或裁剪	父/子反向變換
UI 具有狀態	明確狀態機
場景具有深度	DOM 3D、Three.js 或 WebGL 攝影機/物件關鍵影格

機制可以組合，但每個機制必須闡明想法。裝飾不是證明。

時間

• 僅在能釐清原因或方向時使用預期動作。
• 加速離開靜止。
• 峰值證明應明確展示機制。
• 跟隨動作傳達能量和方向。
• 僅在主體應感覺有彈性或觸感時使用過衝。
• 恆速路徑旅行通常需要 ease: "none"。
• 離散 UI 狀態通常需要銳利的淡出。
• 重複元素需要有序偏移，而非相同時間。
• 最終鎖定需要比過渡姿勢更長的停留。
• 平滑意味著同一主體上的連續速度。
• 不要重疊寫入相同變換屬性的補間，除非重疊是有意且經過驗證的。
• 避免在相同主要表面同時縮放或移動時，動畫化大型 clip-path/遮罩變化；應在主移動穩定後使用巢狀揭示。

文字

保留行框、字詞間距、可讀性和最終貼合。如果文字內部移動，移動字形或遮罩帶狀區域，而不僅是文字周圍的裝飾。對可讀影格進行快照。

SVG

對於筆畫增長，偏好 DrawSVGPlugin，然後是 stroke-dasharray/stroke-dashoffset。
對於形狀插值，偏好 MorphSVGPlugin；必要時將基本形狀轉換為路徑，並將複雜輪廓拆分為更簡單的部分。

3D

僅縮放是假深度。
在穩定父級上使用透視、transform-style: preserve-3d、z 軸移動、旋轉、攝影機/世界運動、遮擋以及物件交叉時的圖層順序。

使用一兩個能暴露深度關係的診斷角度。如果角度證明未顯示深度交叉，改善 z/攝影機/遮擋。

Canvas / WebGL

透過確定性狀態對攝影機位置、攝影機目標、物件變換、材質不透明度、著色器統一變數和後處理強度進行關鍵影格設定。從 HyperFrames 時間渲染。使用 --ghost，因為標記框無法看到內部畫布運動。

CLI 證明

npx hyperframes lint
npx hyperframes validate
npx hyperframes keyframes .
npx hyperframes keyframes . --json
npx hyperframes keyframes . --runtime all
npx hyperframes keyframes . --selector "<selector>" --shot "<file>" --samples <n>
npx hyperframes keyframes . --selector "<selector>" --shot "<file>" --layout strip --from <t0> --to <t1>
npx hyperframes keyframes . --shot "<file>" --ghost --angle <angle>
npx hyperframes snapshot . --at <times>

為實際動畫主體選擇 <selector>。
為第一影格、證明姿勢、最終減去停留以及精確最終選擇 <times>。
僅在需要證明深度時選擇 <angle>。

工具	證明
keyframes	目標、明確停止點、路徑、軌跡、組合的父/子運動、CSS 停止點、Anime 註冊
--shot	鬼影、路線形狀、時間間距、DOM 3D 投影、聚焦選擇器證明
--layout strip	原地運動、重疊、接觸、微妙縮放/不透明度、文字波浪
--ghost	canvas、WebGL、著色器運動、渲染 3D
snapshot --at	遮罩、文字可讀性、完整狀態、最終鎖定、黑色/重置尾部

如果選擇器證明看起來有誤：

1. 重新執行 --json
2. 找到實際動畫目標
3. 拍攝該目標
4. 快照完整影格
5. 信任繪製的像素勝過日誌

診斷解讀

flat 表示沒有明確的中間姿勢。keyframes 表示存在明確停止點。motionPath 表示存在路線。trace 表示多筆畫繪製。composed with 表示子運動繼承父運動。

均勻的鬼影間距表示恆速。聚集的鬼影表示慢入或穩定。大間距表示快速移動。

輔助選擇器拍攝不是證明。在破碎的完整影格上的洋蔥皮拍攝不是證明。

錯誤處理

失敗	修正
僅端點	添加中間姿勢、保持峰值證明、重新執行 --shot
身份中斷	保持一個元素存活、使用共享來源/最終方框、移除替代交叉淡出
假 3D	添加 z/攝影機移動、遮擋、角度證明
錯誤最終	添加最終停留、快照最終減去停留和精確最終
不可搜尋的執行時間	暫停自動播放、註冊實例、移除計時器、同步建構
不可讀文字	保留行框、減少位移、添加最終停留、快照文字影格

完成

執行 lint、validate、keyframes、一個聚焦的 --shot 和快照。確認第一影格、證明姿勢、最終減去停留、精確最終、主體擁有的運動，且無除錯疊加層。