HyperFrames 核心
HyperFrames 從 HTML 渲染影片。一個合成是一個 HTML 檔案，其 DOM 使用 data-* 屬性宣告時間，其動畫執行時間是可尋的，並且媒體播放由框架擁有。
此技能是技術合約 — 如何建立一個 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，將一個剪輯片段相對於另一個進行時間定位 |
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/review-loop.md | 在活動面板上執行計畫 → 草稿 → 建構審查流程 — 所有故事板規劃工作流程共享 |
references/production-loop.md | 將已批准的計畫轉化為交付影片 — 階段依賴關係（音訊、影格、組合、轉場、字幕、驗證、交付）一個自由形式的建構直接遵循 |
references/brief-contract.md | 簡報的基本規則 — 模式推導（協作 / 自主）、共享欄位註冊表、問題不變量（提問本身存在於 /hyperframes → 意圖層） |
references/brief-format.md | 撰寫 BRIEF.md — 已確認的意圖文件，工作流程的 Setup 階段會寫入，後續每個步驟都會讀取 |
references/script-format.md | 撰寫選用的 SCRIPT.md 鎖定旁白 |
references/subagent-dispatch.md | 將子代理分發動詞（並行扇出 / 背景 / 等待）對應到你的工具 |
references/frame-worker-core.md | 共享的 frame-worker 角色合約 — 每個敘事工作流程的封包建構器會將其預置到該工作流程的 sub-agents/frame-worker.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>包裝（包裝它會隱藏所有內容並中斷渲染）。 - 子合成（透過
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。
根必須設定尺寸（無聲的版面錯誤）
獨立式的根需要一個明確的尺寸盒模型（以 px 為單位的 width/height），並且直到一個 height:100% 元素的所有祖先都必須有已解析的高度 — 否則 flex/100% 的子元素會崩潰到接近 0，內容會堆疊到左上角。不要僅依賴自動化閘門來捕捉此問題；請檢查快照。骨架 → 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 易錯點（保證的首次建構失敗）
lint 確實會捕捉到兩個規則，但僅在事後 — 請在第一次就正確編寫它們：
- 根合成元素必須帶有
data-start="0"（以及data-composition-id/data-width/data-height）；省略它會導致lint失敗，錯誤碼為root_composition_missing_data_start。 - 永遠不要將 CSS 初始
transform與 GSAP 對同一個屬性的補間動畫配對 — CSS 值與補間的起點會衝突，lint會以gsap_css_transform_conflict拒絕它。使用gsap.fromTo(el, { x: -40 }, { x: 0 })在補間內部設定初始狀態，而不是使用 CSStransform: translateX(-40px)。
不可協商的規則（自動化閘門可能遺漏的無聲錯誤）
在此列出；完整的理由在連結的參考文件中。不要違反：
- 沒有渲染時時鐘 / 未預先 seed 的
Math.random/ 網路 / 輸入狀態；沒有repeat: -1（使用有限次數）。→determinism-rules.md - 僅對視覺屬性允許清單進行動畫處理；永遠不要補間
display或原始visibility。GSAPautoAlpha和零持續時間的時間軸邊界設置是唯一的可見性例外，且僅適用於非剪輯片段元素或剪輯片段內的包裝器。框架單獨控制.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 和時間軸鍵。
- 添加剪輯片段：選擇一個不重疊的
data-track-index，或有意地調整周圍的時間。 - 任何合成元素上的
data-hidden會在預覽和渲染中隱藏它，覆蓋其時間視窗；它是非破壞性/可逆的，並由 Studio 時間軸的眼睛圖示切換。 - 添加子合成：在連接宿主之前驗證其內部的
data-composition-id。
驗證
使用 hyperframes-cli 獲取命令詳細資訊
-
npx hyperframes check通過（在 lint、執行時期、版面、動態和對比度方面有 0 個發現） - 帶有子合成的專案：
npx hyperframes snapshot --at <midpoints>並目視檢查每個影格 -
npx hyperframes preview用於審查（使用者可以在 Studio 時間軸中編輯任何內容） - 僅在使用者批准後執行
npx hyperframes render