HyperFrames 組合合約 — 建立一個可渲染的專案。用於組合結構、`data-*` 時間屬性、`class="clip"`、軌道、子組合、變數、框架擁有的媒體播放、確定性渲染規則及驗證。在撰寫組合 HTML 前請先閱讀。
HyperFrames Core
HyperFrames 從 HTML 渲染影片。組合是一個 HTML 檔案，其 DOM 使用 data-* 屬性宣告時間，動畫執行環境可搜尋，且媒體播放由框架擁有。
此技能是技術合約 — 如何建立一個 hyperframes 專案。以下內容為建置指南；各主題細節位於 references/（索引如下），按需閱讀。其他相關內容位於同領域技能 — hyperframes-animation、hyperframes-creative、hyperframes-media、hyperframes-cli、hyperframes-registry。/hyperframes 中的能力地圖說明了每個技能涵蓋的範圍。
參考資料
| 檔案 | 閱讀目的… |
|---|---|
references/minimal-composition.md |
從最小的可渲染組合骨架開始 |
references/composition-patterns.md |
選擇單體式或模組化；結構化模組化 index.html；選擇子組合原型 |
references/data-attributes.md |
查詢所有 data-*（根 / clip / 子組合宿主 / 舊別名）；使用 class="clip" |
references/tracks-and-clips.md |
選擇 data-track-index，處理同軌重疊 / z-index，相對於另一個 clip 設定時間 |
references/sub-compositions.md |
連接子組合（宿主屬性、<template>、每個實例的變數）並在其中製作動畫 |
references/variables-and-media.md |
宣告變數；放置 <video>/<audio>，設定音量，裁剪 |
references/determinism-rules.md |
建立可搜尋時間軸；確定性禁止事項；可動畫屬性允許清單；佈局 / 文字適應 |
references/full-screen-motion.md |
使用共享背景製作全幀動畫 |
references/storyboard-format.md |
撰寫 STORYBOARD.md 計劃（加上解析後清單） |
references/script-format.md |
撰寫選用的 SCRIPT.md 鎖定旁白 |
references/subagent-dispatch.md |
將子代理分發動詞（平行展開 / 背景 / 等待）對應到你的 harness |
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>包裝（包裝會隱藏所有內容並破壞渲染）。 - 子組合（透過
data-composition-src載入）— 根必須包在<template>中。
⚠ 傳輸規則：執行時期只複製
<template>內容；外部所有內容（包括<head>樣式/腳本）都會被丟棄 — 將<style>/<script>放在模板內部。
⚠ 宿主 ID 規則：宿主插槽的data-composition-id必須完全等於內部模板的data-composition-id以及window.__timelines["<id>"]鍵 — 沒有-mount/-slot/-host後綴。
檔案形狀、宿主接線及預渲染檢查清單 → references/sub-compositions.md。
根必須設定尺寸（靜默佈局錯誤）
獨立根需要明確的尺寸盒子（width/height 以 px 為單位），且每個祖先直到 height:100% 元素都必須有解析的高度 — 否則 flex/100% 子元素會收縮到約 0，內容堆疊到左上角。lint/validate/inspect 不會捕捉此問題。骨架 → references/minimal-composition.md。
一個暫停的時間軸
每個組合註冊恰好一個 gsap.timeline({ paused: true }) 於 window.__timelines["<id>"]（鍵 = 根 data-composition-id），在頁面載入時同步建立。渲染持續時間 = 根 data-duration，而非時間軸長度。不要手動將子時間軸嵌套到宿主中。完整合約（包括非 GSAP 執行時期）→ references/determinism-rules.md + hyperframes-animation/adapters/。
不可協商的規則（lint/validate/inspect 不會捕捉的靜默錯誤）
在此列出；完整理由請參閱連結參考資料。請勿違反：
- 無渲染時鐘 / 未播種的
Math.random/ 網路 / 輸入狀態；無repeat: -1（使用有限次數）。→determinism-rules.md - 僅動畫視覺屬性允許清單；絕不使用
display/visibility；不在後續場景的 clip 上使用gsap.set。→determinism-rules.md - 正文中無
<br>；變換元素必須是區塊級且設定尺寸；脈衝的絕對定位裝飾元素需要峰值間距。→determinism-rules.md <video>/<audio>必須是宿主根的直接子元素（絕不能放在子組合<template>/包裝器內）；框架擁有播放控制。→variables-and-media.md- 每個
id在組合後的頁面中必須唯一；在子組合內部，使用組合 ID 前綴 id（#<id>-hero）。重複的<video>/<img>id 會渲染空白 — 製作者透過getElementById注入幀，跨檔案重複會逃過lint。→composition-patterns.md - 全螢幕場景填充應放在全出血的子元素（
position:absolute; inset:0），絕不能放在組合根本身 — 製作者的幀合成可能會丟棄根元素的background（幀渲染為黑色），即使預覽/snapshot顯示正確。→composition-patterns.md
編輯現有組合
- 先閱讀檔案。保留不相關的時間、軌道、ID、變數、媒體路徑。
- 匹配現有組合 ID 和時間軸鍵。
- 新增 clip：選擇不重疊的
data-track-index或有意調整周圍時間。 - 新增子組合：在連接宿主前驗證其內部
data-composition-id。
驗證
使用 hyperframes-cli 取得命令細節
- [ ]
npx hyperframes lint通過（0 錯誤） - [ ]
npx hyperframes validate通過（0 控制台錯誤） - [ ]
npx hyperframes inspect通過（0 錯誤） - [ ] 包含子組合的專案：
npx hyperframes snapshot --at <midpoints>並目視檢查每個幀 - [ ]
npx hyperframes preview用於審查（使用者可在 Studio 時間軸中編輯任何內容） - [ ]
npx hyperframes render僅在使用者批准後執行
