hyperframes-core

HyperFrames Core

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/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/storyboard-format.md	撰寫一個 STORYBOARD.md 計劃 (+ 解析的清單)
references/review-loop.md	在一個即時看板上執行計劃 → 草圖 → 建置審查 — 所有分鏡規劃工作流程共享
references/production-loop.md	將已批准的計劃轉變為交付的影片 — 階段依賴關係 (音訊、幀、組合、轉場、字幕、驗證、交付) 一個自由形式的建置會直接跟隨
references/brief-contract.md	簡報的基本規則 — 模式推導 (協作 / 自主)、共享欄位註冊表、問題不變性 (提問本身存在於 /hyperframes → 意圖層)
references/brief-format.md	撰寫 BRIEF.md — 已確認的意圖文件，由工作流程的設定階段寫入，並由後續每個步驟讀取
references/script-format.md	撰寫可選的 SCRIPT.md 鎖定旁白
references/subagent-dispatch.md	將子代理分發動詞 (並行扇出 / 背景 / 等待) 對應到你的調用器
references/frame-worker-core.md	共享的幀工作者角色契約 — 每個敘事工作流程的封包建置器將其預先掛載到該工作流程的 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。

一個暫停的時間軸

每個組合在 window.__timelines["<id>"] (鍵 = 根元素的 data-composition-id) 註冊恰好一個 gsap.timeline({ paused: true })，在頁面載入時同步建置。渲染持續時間 = 根元素的 data-duration，而非時間軸長度。不要手動將子時間軸巢狀嵌入到宿主中。完整契約 (包括非 GSAP 執行時期) → references/determinism-rules.md + hyperframes-animation/adpaters/。

首次 Lint 的常見陷阱 (保證的首次建置失敗)

lint 確實會捕獲的兩個規則，但僅在事後 — 第一次就正確撰寫它們：

• 根組合元素必須攜帶 data-start="0" (連同 data-composition-id/data-width/data-height)；省略它會導致 lint 失敗，出現 root_composition_missing_data_start。
• 永遠不要將 CSS 初始 transform 與 GSAP 在相同屬性上的 tween 配對 — CSS 值和 tween 的起始值會衝突，lint 會以 gsap_css_transform_conflict 拒絕它。使用 gsap.fromTo(el, { x: -40 }, { x: 0 }) 在 tween 內部設定初始狀態，而不是使用 CSS transform: translateX(-40px)。

不可妥協的規則 (自動化閘門可能遺漏的無聲錯誤)

在此處列出；完整理由請參閱連結的參考文件。請勿違反：

• 沒有執行時期時鐘 / 未種子 Math.random / 網路 / 輸入狀態；沒有 repeat: -1 (使用有限的計數)。 → determinism-rules.md
• 僅在視覺屬性允許清單上執行動畫；永遠不要對 display 或原始 visibility 進行 tween。GSAP autoAlpha 和零持續時間時間軸邊界設定是唯一的可見性例外，且僅限於非剪輯元素或剪輯內部的包裝器。框架單獨控制 .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 --background 用於審查 (使用者可以在 Studio 的時間軸中編輯任何內容，並且伺服器會在調用指令後持續運行)
• 僅在使用者批准後執行 npx hyperframes render