HyperFrames 核心
HyperFrames 從 HTML 渲染影片。組合是一個 HTML 檔案，其 DOM 透過 data-* 屬性宣告時間，動畫運行時可逐幀搜尋，媒體播放由框架掌握。
這是組合合約 — 如何建構一個 hyperframes 專案。以下內容為建構指南；每個主題的詳細資訊位於 references/（請參閱索引），按需閱讀。其他關注點位於同一技能的姐妹區塊 — ../cli（開發迴圈）和 ../registry（安裝區塊/元件）— 以及姐妹設計技能 /hyperframes-motion（動畫食譜）和 /hyperframes-design（調色盤、字體排印、幀預設）。../SKILL.md 中的能力圖說明了每個部分涵蓋的內容。
參考文件
| 檔案 | 閱讀目的… |
|---|---|
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，將一個片段相對於另一個片段計時 |
references/sub-compositions.md | 接線一個子組合（宿主屬性、<template>、每個實例的變數）並在其中製作動畫 |
references/variables-and-media.md | 宣告變數；放置 <video> 以進行僅視覺播放 |
references/determinism-rules.md | 建構一個可搜尋的時間軸；確定性禁止事項；可動畫屬性的允許清單；版面/文字適應 |
references/full-screen-motion.md | 使用共享背景創作全幀運動 |
references/storyboard-format.md | 撰寫 STORYBOARD.md 計畫（+ 解析後的操作清單） |
references/subagent-dispatch.md | 將子代理分派動詞（並行展開/背景/等待）對應到您的框架 |
references/tailwind.md | 在 Tailwind v4 專案中工作（init --tailwind；運行時合約與 Studio 的 v3 不同） |
若需動畫運行時細節（GSAP API、Lottie、Three.js 等），請參閱 /hyperframes-motion → 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。
一個暫停的時間軸
每個組合在 window.__timelines["<id>"]（鍵 = 根 data-composition-id）註冊恰好一個 gsap.timeline({ paused: true })，在頁面載入時同步建構。渲染持續時間 = 根 data-duration，而不是時間軸長度。不要手動將子時間軸嵌套到宿主中。完整合約（包括非 GSAP 運行時）→ references/determinism-rules.md + /hyperframes-motion/adapters/。
不可協商的規則（lint/validate/inspect 不會捕捉的無聲錯誤）
在此列出；完整理由請參閱連結的參考文件。請勿違反：
- 沒有執行時時鐘 / 未經種子初始化的
Math.random/ 網路 / 輸入狀態；沒有repeat: -1（使用有限次數）。→determinism-rules.md - 僅對視覺屬性允許清單進行動畫；永遠不要
display/visibility；不要在後續場景片段上使用gsap.set。→determinism-rules.md - 正文文字中沒有
<br>；變換元素必須是區塊級別且設有尺寸；脈衝的絕對定位裝飾元素需要間距容許值。→determinism-rules.md <video>必須是宿主根的直接子元素（永遠不要在子組合<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 和時間軸鍵。
- 新增片段：選擇一個不重疊的
data-track-index或有意調整周圍的時間。 - 新增子組合：在接線宿主之前，驗證其內部的
data-composition-id。
驗證
執行 CLI 閘道（請參閱 ../cli/SKILL.md → 工作流程 + 最低完成閘道以獲得標準的 lint / validate / inspect / snapshot / preview / render 檢查清單，包括子組合專案所需的視覺冒煙測試）。