外掛安裝： 在執行設定或更新指令前，請先遵循外掛執行規則（當此技能位於 HyperFrames 外掛內時）。獨立安裝則保留下方的更新說明。
HyperFrames Core
代理陷阱（請先閱讀）：
- 使用 flex/
inset置中，不要在以 CSStransform: translate(-50%,-50%)定位的節點上再使用 GSAP 的x/y。靜態檢查：gsap_css_transform_conflict。請改用fromTo或xPercent/yPercent。 - 請勿添加場景退出的
tl.set(..., {visibility:"hidden"})。執行階段已會隱藏計時片段。在內部節點上使用透明度淡出（或對.clip使用opacity）就已足夠。標題強制隱藏則適用不同規則。 window.__timelines["id"]必須與根元素的data-composition-id相符。- 執行
render後，請讀取摘要的第二行：beginframevsscreenshot、GPU 模式、階段時間。screenshot+ Linux 上的software gpu是較慢的路徑。
HyperFrames 從 HTML 渲染影片。組合是一個 HTML 檔案，其 DOM 使用 data-* 屬性宣告時序，動畫執行階段是可搜尋的，媒體播放由框架控制。
此技能是技術合約 — 描述如何建構一個 hyperframes 專案。以下內容是建構指南；每個主題的詳細資訊位於 references/（下方索引），請按需閱讀。流程文件（簡報、分鏡、審查、製作、發佈、幀工作者）位於 /hyperframes → references/。其他關注點位於同領域技能中 — hyperframes-animation、hyperframes-creative、media-use、hyperframes-cli、hyperframes-registry。功能對應表位於 /hyperframes，說明每個技能的涵蓋範圍。
參考文件
| 檔案 | 閱讀目的... |
|---|---|
references/minimal-composition.md | 從最小的可渲染組合骨架開始 |
references/composition-patterns.md | 選擇整體式 vs 模組化；建構模組化 index.html；選擇子組合原型 |
references/data-attributes.md | 查詢任何 data-*（根/片段/子組合宿主/舊版別名）；使用 class="clip" |
references/tracks-and-clips.md | 了解 data-track-index 控制（和不控制）什麼、z-index、將一個片段相對於另一個計時；使用 npx hyperframes timeline 列出所有軌道和片段 |
references/creator-editing-recipes.md | 複製可靠的剪下/修剪/重排/重新計時/凍結/相機/遮罩/交叉淡入淡出/音訊編輯配方及其限制 |
references/sub-compositions.md | 接線子組合（宿主屬性、<template>、每個實例的變數）並在其中製作動畫 |
references/variables-and-media.md | 宣告變數；放置 <video>/<audio>、設定音量、修剪 |
references/determinism-rules.md | 建構可搜尋的時間軸；確定性禁止事項；版面/文字適應 |
references/full-screen-motion.md | 使用共享背景創作全幀動畫 |
references/tailwind.md | 在 Tailwind v4 專案中工作（init --tailwind；執行階段合約與 Studio 的 v3 不同） |
有關動畫執行階段的具體資訊（GSAP API、Lottie、Three.js 等），請前往 hyperframes-animation → adapters/<runtime>.md。
建構一個組合
兩種根形式（不可互換）
- 獨立（頂層
index.html）：根<div data-composition-id="…">直接位於<body>中，沒有<template>包裹。包裹獨立根會隱藏所有內容，lint會拒絕（standalone_composition_wrapped_in_template，錯誤）。 - 子組合（透過
data-composition-src載入）：將根包裹在<template>中。這是應撰寫的形式：載入器也接受普通的完整文件並回退至其<body>，但範例和工具假設的是範本形式。
⚠ 傳輸規則：對於範本化的子組合，組裝器會丟棄檔案自身的
<head><style>/<script>（位於packages/core/src/compiler/compositionAssembly.ts，hasTemplate閘），因此請將<style>/<script>放在範本內部。<link>無論如何都會被提升。 ⚠ 宿主 ID 慣例：請為宿主插槽、內部範本和window.__timelines["<id>"]鍵使用相同的 ID。支援不同的本地 ID（組裝器會回退至檔案中的第一個根），但不匹配時會靜默失敗，因此除非有理由，否則請使其匹配。
檔案形狀、宿主接線和渲染前檢查清單 → references/sub-compositions.md。
根必須設定大小（靜默版面錯誤）
獨立根使用 width/height: 100%。畫布大小為 data-width/data-height。執行階段會將這些像素應用到組合根上。請勿在 #root 上硬編碼 1920px/1080px。骨架 → references/minimal-composition.md。
一個暫停的時間軸
每個組合註冊恰好一個 gsap.timeline({ paused: true })，位於 window.__timelines["<id>"]（鍵 = 根元素的 data-composition-id）。在非同步回呼（document.fonts.ready）中建構它是可以的；重要的是你僅在建構完成後才註冊。渲染長度是根的 data-duration，而不是時間軸的長度：超過根持續時間的時間軸會被截斷，而提前結束的時間軸則會保持其最後一幀。省略根的 data-duration，則長度會改為推斷（時間軸、媒體視窗或適配器）。你不需要 window.__timelines = window.__timelines || {}：執行階段會在你的內嵌腳本執行前建立註冊表，lint 也不再要求它。請勿手動將子時間軸巢狀放入宿主；執行階段會自動巢狀化已註冊的子時間軸。完整合約（包括非 GSAP 執行階段）→ references/determinism-rules.md + hyperframes-animation/adapters/。
第一次 lint 常見問題（保證首次建構失敗）
lint 確實會捕捉的規則，但僅在事後。請在第一次就寫對：
- 切勿將 CSS 初始
transform與 GSAP 對相同屬性的補間配對 — CSS 值和補間的起始值會衝突，lint會用gsap_css_transform_conflict拒絕。請在補間內部使用gsap.fromTo(el, { x: -40 }, { x: 0 })來設定初始狀態，而不是使用 CSStransform: translateX(-40px)。 - 切勿在
<video>/<audio>上使用crossorigin。lint會無條件用media_crossorigin_breaks_preview（錯誤）拒絕它，包括用於 canvas/WebGL/WebAudio 讀回。沒有抑制方法。 - 切勿讓含有
data-start的<video>其祖先也帶有data-start。lint會用video_nested_in_timed_element（錯誤）拒絕。可以為包裹元素或影片設定時間，但不能同時設定。 - 每個
<audio>都需要一個id。lint會用media_missing_id拒絕，而且沒有 id 的<audio>永遠不會被混音器拾取，所以渲染結果會是無聲的。 - 切勿使用
autoAlpha或visibility對.clip進行補間 —lint會用gsap_animates_clip_element拒絕。請改為對子元素製作動畫。 - 命名的 CSS
font-family需要在檔案中有對應的@font-face，指向已發布的本地檔案，否則lint會觸發font_family_without_font_face。 - 子組合的
#root使用width/height: 100%（或inset: 0），而不是硬編碼的1920px/1080px。畫布大小為data-width/data-height。
lint 錯誤也會關閉版面與對比度審計：check 隨後會報告 0 sample(s) 和 0/0 text checks，這看起來像是一個乾淨的檔案，但實際上什麼都沒執行。在信任這些數字之前，請先清除 lint 錯誤。
不可協商的規則（自動化閘門可能遺漏的靜默錯誤）
在此列出；完整理由請參閱連結的參考文件。請勿違反：
- 沒有渲染時鐘 / 未經種子的
Math.random/ 網路 / 輸入狀態；沒有repeat: -1（請使用有限次數）。→determinism-rules.md - 切勿在
.clip元素上對display、visibility或autoAlpha進行補間。框架擁有片段的可見性，lint會拒絕（gsap_animates_clip_element）。請改為對子元素製作動畫。→determinism-rules.md - 正文中沒有
<br>；被轉換的元素必須是區塊級且已設定大小；脈動的絕對定位裝飾元素需要頂部間距。→determinism-rules.md <video>/<audio>是透過扁平的文件查詢找到的，因此框架可以在任何巢狀深度（包括在子組合<template>或包裹元素內部）尋找和解碼它們。一個硬性限制：lint會錯誤報告位於另一個也具有data-start的普通元素內部的<video data-start>，且此失敗是真實的（錯誤的來源幀，然後片段在插槽中間消失），因此請將時間放在包裹元素或影片上，切勿同時放在兩者上。子組合宿主是例外：子組合內部的媒體可以正確渲染。另一個注意事項是時間軸，而非位置：子組合時間軸無法動畫化宿主根元素。→variables-and-media.md- 確保每個
id在組合後的頁面中是唯一的（為子組合 ID 加上前綴，例如#<id>-hero），以便你自己的#idCSS 和getElementById調用能被解析。幀注入不再依賴於此：編譯器會在每個video[src]/audio[src]/img[src]上蓋上一個文檔唯一的data-hf-render-id。使用<source>子元素而不是src屬性的媒體不會被蓋章，因此唯一 ID 在那裡仍然重要。→composition-patterns.md - 在組合根上的全螢幕填充在正常渲染時是沒問題的。它僅在層合成路徑（HDR 內容，或使用著色器轉場的組合）上被丟棄，在這種情況下，引擎會強制每個組合根透明，以便底層能夠顯示出來。如果你的組合使用著色器轉場或 HDR 媒體，請將填充放在一個全出血的子元素上（
position:absolute; inset:0）。→composition-patterns.md
編輯現有組合
- 先閱讀檔案。保留不相關的時序、軌道、ID、變數、媒體路徑。
- 要了解專案時間軸上的內容（軌道、片段、開始、結束、播放內容），請執行
npx hyperframes timeline [--json]，而不是讀取index.html和每個子組合檔案。 - 匹配現有的組合 ID 和時間軸鍵。
- 添加片段：有目的地根據周圍片段設定其
data-start/data-duration。data-track-index是 Studio 的顯示通道，不是時間約束，因此不需要是空的。 - 結束時間超過根
data-duration的片段會被截斷：在同一編輯中將根的data-duration延伸到片段的結束時間（lint會發出clip_ends_past_root_duration警告）。 - 任何組合元素上的
data-hidden會同時在預覽和渲染中隱藏它，覆蓋其時間窗口；它是非破壞性/可逆的，並由 Studio 時間軸的眼睛圖示切換。 - 添加子組合：在接線宿主之前，請驗證其內部的
data-composition-id。
驗證
使用 hyperframes-cli 獲取命令詳細資訊
-
npx hyperframes check通過（在 lint、執行階段、版面、動畫和對比度方面找到 0 個問題） - 具有子組合的專案：
npx hyperframes snapshot --at <midpoints>並肉眼檢查每一幀 -
npx hyperframes preview --background用於審查（使用者可以在 Studio 的時間軸中編輯任何內容，且伺服器會在調用命令後持續運行） - 僅在使用者批准後才執行
npx hyperframes render