HyperFrames 關鍵影格 是做什麼的？
關鍵影格是一種姿勢合約：可見狀態、連續主體識別、可尋址執行時間、經過驗證的像素。
使用 hyperframes-animation 處理廣泛場景配方。使用 hyperframes-cli 獲取完整命令文件。僅在選擇實作機制（而非視覺風格）時，才使用 references/keyframe-patterns.md。
創作者編輯邊界
關鍵影格擁有視覺動畫，而非片段組合。來源範圍的硬剪輯、修剪、拼接和重新排序屬於 /hyperframes-core：為每個保留的範圍創作一個媒體元素，使用 data-start 和 data-duration 放置它，並使用 data-media-start 選擇其來源偏移。相鄰的範圍構成硬剪輯。淡入淡出使用不同軌道上的重疊片段加上視覺不透明度關鍵影格；聲音淡入淡出使用 /hyperframes-audio。
| 創作者需求 | 真實機制 |
|---|---|
| 推近 / 拉遠 (Punch-in / punch-out) | 在片段內的非計時視覺/裁剪包裝器上，對 scale 加上 x/y 或百分比位移進行關鍵影格設定。使用 set/short tween 實現硬推近，使用 tween 實現平滑移動。 |
| 平滑多狀態縮放或重新構圖 (Smooth multi-state zoom or reframe) | 保持一個主體包裝器存活，並將多個縮放/重新構圖狀態創作為一個帶有每個片段緩動的姿勢階梯。 |
| 平移、重新構圖或 Ken Burns 攝影機移動 | 對包裝器的位移加上縮放進行動畫設定。幾何是創作出的；這不是面部追蹤或自動語義重新構圖。 |
| 鏈式攝影機移動 (Chained camera moves) | 在一個已註冊的可尋址時間軸上，鏈式標記的變換節拍。 |
| 匹配剪輯或甩鏡 (Match cut or whip pan) | /hyperframes-animation 擁有視覺移交；/hyperframes-registry 提供基本元素；關鍵影格保留創作出的幾何、方向和速度。不存在自動匹配影格發現機制。 |
| 裁剪和遮罩重新構圖 (Crop and mask reframe) | 在內部視覺包裝器上對 clip-path 或遮罩進行插值，以進行裁剪/重新構圖，而不改變來源時間。多邊形關鍵影格可以形成多邊形/遮罩過渡。 |
| 定向擦除剪輯或遮罩/揭示剪輯 (Directional wipe cut or iris/reveal cut) | 在重疊的視覺片段上對遮罩/剪輯邊界進行動畫設定；/hyperframes-animation 擁有移交編排。 |
| 分割畫面移交 (Split-screen handoff) | 保持兩個視覺片段由核心放置，然後對它們的內部裁剪/遮罩包裝器和分隔線幾何進行關鍵影格設定。 |
| 恆定來源重新計時 (Constant source retime) | /hyperframes-core 擁有標準化的 data-playback-rate (0.1..5) ，用於渲染安全的圖片和保持音高的聲音。它對整個媒體元素是恆定的。 |
| 來源速度斜坡 (Source speed ramps) | 不支援：不存在隨時間變化的播放速率包絡。預先處理一個衍生的媒體資產，然後透過核心放置它。 |
| 凍結 / 保持 (Freeze / hold) | 一個視覺姿勢、最終來源影格或完成的子合成可以保持。不支援任意的中間來源凍結；預先處理一個靜止/衍生的片段，將其作為自己的片段放置，然後用另一個來源範圍恢復。 |
同時編輯畫面和聲音時，載入 /hyperframes-core、此技能用於視覺動畫，以及 /hyperframes-audio 用於淡入淡出、交叉淡入淡出、音量自動化、閃避/雕刻或對已放置軌道的效果。
視覺過渡或裁剪處理不是時間上的來源修剪或拼接。/hyperframes-core 擁有時間軸、片段時序和來源範圍；關鍵影格僅動畫化這些片段內部包裝器上的可見移交或裁剪。對於可複製的組合圖片/聲音配方，使用 /hyperframes-core → references/creator-editing-recipes.md。
程序
- 識別動畫主體、可見狀態、最終狀態和執行時間。
- 選擇能證明提示的最小機制。僅在機制不明確時閱讀
references/keyframe-patterns.md。 - 在聲明的執行時間內創作可尋址的關鍵影格。同步建構並註冊執行時間實例。
- 使用
hyperframes lint、hyperframes check、hyperframes keyframes、一個聚焦的--shot以及在證明時刻的快照進行驗證。 - 如果證明失敗，修正來源關鍵影格，並在渲染前重新執行最小的失敗診斷。
合約
- 命名移動的主體。
- 命名證明預期動畫所需的姿勢，包括最終狀態。
- 對可見通道進行關鍵影格設定，而非隱藏的輔助狀態。
- 當連續性重要時，保持物件識別。
- 僅當預期動畫是替換或溶解時才使用淡入淡出。
- 保持可讀或語義狀態足夠長的時間以便看清。
- 影格是動畫的一部分，而非清理。
- 除非要求，否則不要重設為靜止狀態。
- 除非要求，否則不要以黑色結束。
- 如果編輯初始場景，除非要求重新設計，否則保留佈局、複本、資源、顏色和最終狀態。
執行時間規則
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 創建、執行主體運動的輔助覆蓋層。
對於可見性變化，在已註冊的可尋址 GSAP 時間軸上使用 autoAlpha，或在明確邊界處使用零持續時間的 tl.set()。僅針對非剪輯元素或片段內部的包裝器；切勿針對 .clip 本身。切勿對原始 visibility 進行持續時間補間，也切勿對 display 進行補間。
機制選擇
選擇能證明提示的最小機制：
| 需求 | 機制 |
|---|---|
| 同一主體改變框或層級結構 | 共享元素 / 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，因為標記框無法看到內部 canvas 動畫。
CLI 證明
npx hyperframes lint
npx hyperframes check
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 | 遮罩、文字可讀性、完整狀態、最終鎖定、黑色/重設尾部 |
如果選擇器證明看起來不對：
- 重新執行
--json - 找到實際的動畫目標
- 射擊該目標
- 對完整影格進行快照
- 信任繪製的像素勝過日誌
診斷閱讀
flat 表示沒有明確的中間姿勢。keyframes 表示存在明確的停止點。`m