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/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 | 共享幀工作者角色合約 — 每個敘事工作流程的封包建置器將其預先附加到該工作流程的 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。
根必須設定大小(無聲版面錯誤)
獨立根需要一個明確的尺寸框(width/height 以 px 為單位),且每個直達 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 tween 配對在相同屬性上 — CSS 值和 tween 的起點會衝突,lint會以gsap_css_transform_conflict拒絕。請在 tween 內部使用gsap.fromTo(el, { x: -40 }, { x: 0 })設定初始狀態,而不是使用 CSStransform: translateX(-40px)。
不可協商的規則(自動化閘門可能遺漏的無聲錯誤)
在此處提出;完整理由請參閱鏈接參考資料。請勿違反:
- 無渲染時鐘 / 未播種的
Math.random/ 網路 / 輸入狀態;無repeat: -1(使用有限次數)。→determinism-rules.md - 僅對視覺屬性允許清單進行動畫;切勿對
display或原始visibility進行 tween。GSAPautoAlpha和零持續時間時間軸邊界設定是唯一的 visibility 例外,且僅在非剪輯元素或剪輯內的包裝器上。框架單獨控制.clipvisibility。不要在頁面載入時對後期場景剪輯執行gsap.set。→determinism-rules.md - 正文中無
<br>;轉換元素必須是區塊級 + 已設定大小;脈衝絕對裝飾需要峰值間隙。→determinism-rules.md <video>/<audio>在任何巢狀深度都能運作(包括在子合成<template>或包裝器內部);框架擁有播放權,並在任何位置搜尋/解碼媒體。唯一的注意事項是時間軸,而不是放置:子合成時間軸無法對主機根元素進行動畫。→variables-and-media.md- 每個
id在組裝後的頁面中必須是唯一的;在子合成內部,使用合成 ID 前綴 ids(#<id>-hero)。重複的<video>/<img>ids 會渲染為空白 — 生產者透過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、執行時期、版面、動態和對比度上均無發現) - 含有子合成的專案:
npx hyperframes snapshot --at <midpoints>並目視檢查每一幀 -
npx hyperframes preview供審查(使用者可以在 Studio 的時間軸中編輯任何內容) - 僅在使用者批准後執行
npx hyperframes render