ilya-makarov-dev/Reframe

HyperFrames

HTML 是影片的真相來源。合成是一個帶有 data-* 屬性（用於時間控制）、GSAP 時間軸（用於動畫）和 CSS（用於外觀）的 HTML 檔案。該框架負責處理剪輯的可見性、媒體播放和時間軸同步。

方法

在撰寫 HTML 之前，先從高層次思考：

1. 什麼 — 觀眾應該體驗什麼？找出敘事弧線、關鍵時刻和情感節奏。
2. 結構 — 有多少個合成？哪些是子合成，哪些是內聯合成？哪些音軌負責什麼（影片、音訊、疊加層、字幕）？
3. 時間 — 哪些剪輯決定持續時間？轉場發生在哪裡？節奏如何？
4. 佈局 — 先建立最終狀態。請參閱下方的「先佈局，後動畫」。
5. 動畫 — 然後使用以下規則添加動畫。

對於小型編輯（修正顏色、調整時間、添加一個元素），可直接跳到規則。

視覺辨識閘門

按此順序檢查：

1. 專案中是否存在 DESIGN.md？ → 閱讀它。使用其精確的顏色、字體、動畫規則和「禁止事項」限制。
2. 是否存在 visual-style.md？ → 閱讀它。套用其 style_prompt_full 和結構化欄位。（注意：visual-style.md 是專案特定的檔案。visual-styles.md 是包含 8 個命名預設的樣式庫 — 不同的檔案）。
3. 使用者指定了樣式（例如「Swiss Pulse」、「黑暗科技風」、「奢華品牌」）？ → 閱讀 visual-styles.md 以取得 8 個命名預設。生成一個精簡的 DESIGN.md，包含：## 風格提示（一段）、## 顏色（3-5 個十六進位值及角色）、## 排版（1-2 個字體系列）、## 禁止事項（3-5 個反模式）。
4. 以上皆非？ → 在撰寫任何 HTML 之前，先問 3 個問題：
   • 情緒是什麼？（爆炸性 / 電影感 / 流暢 / 技術感 / 混亂 / 溫暖）
   • 淺色還是深色畫布？
   • 是否有任何特定的品牌顏色、字體或視覺參考？ 然後根據答案生成一個精簡的 DESIGN.md。

每個合成必須將其調色盤和字體追溯回 DESIGN.md、visual-style.md 或使用者的明確指示。如果您正在使用 #333、#3b82f6 或 Roboto — 您跳過了這個步驟。

對於動畫預設、尺寸、入場模式和緩動 — 請遵循 house-style.md。House style 處理事物如何移動。DESIGN.md 處理事物看起來像什麼。

先佈局，後動畫

將每個元素放置在其最可見的時刻應在的位置 — 即它已完全進入、正確放置且尚未退出的畫面。首先將其撰寫為靜態 HTML + CSS。暫時不要使用 GSAP。

為何如此重要： 如果您將元素放置在它們的動畫起始狀態（螢幕外、縮放至 0、透明度 0）並將其補間到您認為應著陸的位置，您是在猜測最終佈局。重疊在影片渲染之前是不可見的。透過先建立最終狀態，您可以在添加任何動畫之前看到並修復佈局問題。

過程

1. 為每個場景找出主要畫面 — 最多元素同時可見的時刻。這就是您要建立的佈局。
2. 為該畫面撰寫靜態 CSS。.scene-content 容器必須使用 width: 100%; height: 100%; padding: Npx; 並搭配 display: flex; flex-direction: column; gap: Npx; box-sizing: border-box 來填滿整個場景。使用 padding 將內容向內推 — 永遠不要對內容容器使用 position: absolute; top: Npx。絕對定位的內容容器在內容高於剩餘空間時會溢出。僅將 position: absolute 保留給裝飾性元素。
3. 使用 gsap.from() 添加入場 — 從螢幕外/不可見動畫到 CSS 位置。CSS 位置是基本真理；補間描述了到達那裡的旅程。
4. 使用 gsap.to() 添加出場 — 從 CSS 位置動畫到螢幕外/不可見。

範例

/* scene-content 填滿場景，padding 定位內容 */
.scene-content {
  display: flex;
  flex-direction: column;
  justify-content: center;
  width: 100%;
  height: 100%;
  padding: 120px 160px;
  gap: 24px;
  box-sizing: border-box;
}
.title {
  font-size: 120px;
}
.subtitle {
  font-size: 42px;
}
/* 容器填滿任何場景尺寸（1920x1080、1080x1920 等）。
   Padding 定位內容。Flex + gap 處理間距。 */

錯誤 — 硬編碼尺寸和絕對定位：

.scene-content {
  position: absolute;
  top: 200px;
  left: 160px;
  width: 1920px;
  height: 1080px;
  display: flex; /* ... */
}

// 步驟 3：動畫進入這些位置
tl.from(".title", { y: 60, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
tl.from(".subtitle", { y: 40, opacity: 0, duration: 0.5, ease: "power3.out" }, 0.2);
tl.from(".logo", { scale: 0.8, opacity: 0, duration: 0.4, ease: "power2.out" }, 0.3);

// 步驟 4：從這些位置動畫退出
tl.to(".title", { y: -40, opacity: 0, duration: 0.4, ease: "power2.in" }, 3);
tl.to(".subtitle", { y: -30, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.1);
tl.to(".logo", { scale: 0.9, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.2);

當元素隨著時間共享空間時

如果元素 A 在元素 B 進入同一區域之前退出，兩者都應該有各自主要畫面的正確 CSS 位置。時間軸順序保證它們永遠不會在視覺上共存 — 但如果您跳過佈局步驟，您將不會發現因時間錯誤而意外重疊的情況。

什麼構成故意重疊

分層效果（文字後的光暈、陰影元素、背景圖案）和 Z 軸堆疊設計（卡片堆疊、深度圖層）是故意的。佈局步驟的目的是捕捉非故意的重疊 — 兩個標題相互疊加、一個統計資料覆蓋標籤、內容溢出畫面邊界。

資料屬性

所有剪輯

屬性	必要	值
id	是	唯一識別碼
data-start	是	秒數或剪輯 ID 參考（"el-1"、"intro + 2"）
data-duration	img/div/compositions 需要	秒數。影片/音訊預設為媒體持續時間。
data-track-index	是	整數。相同音軌的剪輯不能重疊。
data-media-start	否	從來源修剪的偏移量（秒數）
data-volume	否	0-1（預設 1）

data-track-index 不影響視覺分層 — 請使用 CSS z-index。

合成剪輯

屬性	必要	值
data-composition-id	是	唯一合成 ID
data-start	是	開始時間（根合成：使用 "0"）
data-duration	是	優先於 GSAP 時間軸持續時間
data-width / data-height	是	像素尺寸（1920x1080 或 1080x1920）
data-composition-src	否	外部 HTML 檔案的路徑

合成結構

透過 data-composition-src 載入的子合成使用 <template> 包裝。獨立合成（主要的 index.html）不使用 <template> — 它們將 data-composition-id div 直接放在 <body> 中。在獨立檔案上使用 <template> 會隱藏瀏覽器中的所有內容並破壞渲染。

子合成結構：

<template id="my-comp-template">
  <div data-composition-id="my-comp" data-width="1920" data-height="1080">
    <!-- 內容 -->
    <style>
      [data-composition-id="my-comp"] {
        /* 隔離樣式 */
      }
    </style>
    <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
    <script>
      window.__timelines = window.__timelines || {};
      const tl = gsap.timeline({ paused: true });
      // 補間...
      window.__timelines["my-comp"] = tl;
    </script>
  </div>
</template>

在根目錄中載入：<div id="el-1" data-composition-id="my-comp" data-composition-src="compositions/my-comp.html" data-start="0" data-duration="10" data-track-index="1"></div>

影片和音訊

影片必須是 muted playsinline。音訊始終是獨立的 <audio> 元素：

<video
  id="el-v"
  data-start="0"
  data-duration="30"
  data-track-index="0"
  src="video.mp4"
  muted
  playsinline
></video>
<audio
  id="el-a"
  data-start="0"
  data-duration="30"
  data-track-index="2"
  src="video.mp4"
  data-volume="1"
></audio>

時間軸合約

• 所有時間軸以 { paused: true } 開始 — 播放器控制播放
• 註冊每個時間軸：window.__timelines["<composition-id>"] = tl
• 框架自動巢狀化子時間軸 — 請勿手動添加
• 持續時間來自 data-duration，而非 GSAP 時間軸長度
• 永遠不要為了設定持續時間而建立空的補間

規則（不可協商）

確定性： 沒有 Math.random()、Date.now() 或基於時間的邏輯。如果您需要偽隨機值（例如 mulberry32），請使用種子 PRNG。

GSAP： 僅動畫視覺屬性（opacity、x、y、scale、rotation、color、backgroundColor、borderRadius、變形）。不要動畫 visibility、display 或呼叫 video.play()/audio.play()。

動畫衝突： 永遠不要同時從多個時間軸動畫同一個元素的同一個屬性。

無 repeat: -1： 無限重複的時間軸會破壞捕捉引擎。從合成持續時間計算精確的重複次數：repeat: Math.ceil(duration / cycleDuration) - 1。

同步時間軸建構： 永遠不要在 async/await、setTimeout 或 Promise 內部建構時間軸。捕捉引擎在頁面載入後同步讀取 window.__timelines。字體由編譯器嵌入，因此它們立即可用 — 無需等待字體載入。

絕對不要做：

1. 忘記註冊 window.__timelines
2. 使用影片作為音訊 — 永遠使用靜音影片 + 獨立 <audio>
3. 將影片巢狀在計時 div 內 — 使用非計時包裝器
4. 使用 data-layer（使用 data-track-index）或 data-end（使用 data-duration）
5. 動畫影片元素尺寸 — 動畫包裝器 div
6. 呼叫媒體的 play/pause/seek — 框架擁有播放權
7. 建立沒有 data-composition-id 的頂層容器
8. 在任何時間軸或補間上使用 repeat: -1 — 始終使用有限重複
9. 非同步建構時間軸（在 async、setTimeout、Promise 內部）
10. 在後續場景的剪輯元素上使用 gsap.set() — 它們在頁面載入時不存在於 DOM 中。請改用時間軸內部的 tl.set(selector, vars, timePosition)，在剪輯的 data-start 時間或之後。
11. 在內容文字中使用 <br> — 強制換行不考慮實際渲染的字體寬度。自然換行的文字加上一個 <br> 會產生多餘的不需要的換行，導致重疊。請改用 max-width 讓文字換行。例外：簡短的顯示標題，其中每個單字故意單獨一行（例如 "THE\nIMMORTAL\nGAME" 在 130px 字體大小下）。

場景轉場（不可協商）

每個多場景合成必須遵循所有這些規則。違反任何一條都會導致合成損壞。

1. 始終在場景之間使用轉場。沒有跳剪。沒有例外。
2. 始終在每個場景上使用入場動畫。每個元素透過 gsap.from() 動畫進入。沒有元素可以完整呈現。如果一個場景有 5 個元素，則需要 5 個入場補間。
3. 永遠不要使用出場動畫，除了在最後一個場景。這意味著：在轉場觸發之前，沒有 gsap.to() 將透明度動畫到 0、y 到螢幕外、縮放到 0 或任何其他「退出」動畫。轉場本身就是退出。在轉場開始的那一刻，退場場景的內容必須完全可見。
4. 僅限最後一個場景： 最後一個場景可以將元素淡出（例如淡出至黑色）。這是唯一允許 gsap.to(..., { opacity: 0 }) 的場景。

錯誤 — 在轉場前進行出場動畫：

// 禁止 — 這會在轉場可以使用場景之前清空它
tl.to("#s1-title", { opacity: 0, y: -40, duration: 0.4 }, 6.5);
tl.to("#s1-subtitle", { opacity: 0, duration: 0.3 }, 6.7);
// 轉場觸發在空畫面上

正確 — 僅入場，轉場處理退出：

// 場景 1 入場動畫
tl.from("#s1-title", { y: 50, opacity: 0, duration: 0.7, ease: "power3.out" }, 0.3);
tl.from("#s1-subtitle", { y: 30, opacity: 0, duration: 0.5, ease: "power2.out" }, 0.6);
// 沒有退出補間 — 在 7.2 秒處的轉場處理場景切換
// 場景 2 入場動畫
tl.from("#s2-heading", { x: -40, opacity: 0, duration: 0.6, ease: "expo.out" }, 8.0);

動畫護欄

• 將第一個動畫偏移 0.1-0.3 秒（不在 t=0）
• 在入場補間之間變化緩動 — 每個場景至少使用 3 種不同的緩動
• 不要在一個場景內重複入場模式
• 在深色背景上避免全螢幕線性漸層（H.264 頻帶 — 使用徑向或純色 + 局部光暈）
• 渲染影片使用 60px+ 標題、20px+ 正文、16px+ 資料標籤
• 在數字欄上使用 font-variant-numeric: tabular-nums

當沒有提供 visual-style.md 或動畫方向時，請遵循 house-style.md 以獲取美學預設。

排版和資源

• 字體： 只需在 CSS 中撰寫您想要的 font-family — 編譯器會自動嵌入支援的字體。如果不支援某個字體，編譯器會發出警告。
• 為外部媒體添加 crossorigin="anonymous"