HyperFrames 註冊表
註冊表提供可重複使用的區塊與元件，可透過 hyperframes add <name> 安裝。
- 區塊 — 獨立的子作品（擁有自己的尺寸、持續時間、時間軸）。在宿主作品中透過
data-composition-src引入。 - 元件 — 效果片段（沒有自己的尺寸）。直接貼入宿主作品的 HTML 中。
快速參考
hyperframes add data-chart # 安裝一個區塊
hyperframes add grain-overlay # 安裝一個元件
hyperframes add captions # 安裝所有標記為 captions 的區塊
hyperframes add shimmer-sweep --dir . # 針對特定專案
hyperframes add data-chart --json # 機器可讀輸出
hyperframes add data-chart --no-clipboard # 跳過剪貼簿（CI/無頭模式）
安裝後，CLI 會列印出寫入的檔案以及一段需要貼入宿主作品的程式碼片段。該片段僅為起點 — 在接入區塊時，您需要自行添加 data-composition-id（必須與區塊內部的作品 ID 一致）、data-start 和 data-track-index 屬性。
位置參數會先以精確的項目名稱解析。若無符合項目且該值為一個標籤，則指令會安裝所有帶有該標籤的區塊。註冊表依賴項會在請求的項目之前安裝。hyperframes add 僅適用於區塊與元件；如需範例，請使用 hyperframes init <dir> --example <name>。
安裝位置
區塊預設安裝至 compositions/<name>.html。元件預設安裝至 compositions/components/<name>.html。
這些路徑可在 hyperframes.json 中設定：
{
"registry": "https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry",
"paths": {
"blocks": "compositions",
"components": "compositions/components",
"assets": "assets"
}
}
詳細說明請參閱 install-locations.md。
接入區塊
區塊是獨立的作品 — 在您的宿主 index.html 中透過 data-composition-src 引入：
<div
data-composition-id="data-chart"
data-composition-src="compositions/data-chart.html"
data-start="2"
data-duration="15"
data-track-index="1"
data-width="1920"
data-height="1080"
></div>
關鍵屬性：
data-composition-src— 區塊 HTML 檔案的路徑data-composition-id— 必須與區塊的內部 ID 一致data-start— 區塊在宿主時間軸中出現的時間（秒）data-duration— 區塊播放的持續時間data-width/data-height— 區塊畫布尺寸data-track-index— 圖層順序（數值越大越靠前）
詳細說明請參閱 wiring-blocks.md。
接入元件
元件是程式碼片段 — 將其 HTML 貼入您的作品標記中，CSS 貼入樣式區塊，JS 貼入腳本（若有）：
- 讀取安裝的檔案（例如
compositions/components/grain-overlay.html） - 將 HTML 元素複製到您的作品
<div data-composition-id="...">中 - 將
<style>區塊複製到您的作品樣式中 - 將任何
<script>內容複製到您的作品腳本中（在時間軸程式碼之前） - 若元件暴露了 GSAP 時間軸整合（請參閱片段中的註解區塊），將那些呼叫添加到您的時間軸
詳細說明請參閱 wiring-components.md。
探索
將 CLI 作為主要探索介面。在瀏覽之前應先透過意圖搜尋： 註冊表中的項目遠多於肉眼可掃描的數量，因此列出所有項目並比對名稱或標籤是較慢的方式，且當作者用語與您的用語不同時會失敗。
# 將整個目錄與節拍應達成的效果進行排名
npx hyperframes catalog --query "reveal a headline one line at a time"
npx hyperframes add caption-clip-wipe
搜尋為本地執行，不會發送任何資料。預設情況下，它會根據與項目名稱、標題和描述共享的詞彙進行排名，因此只會找到重複您用語的項目；--on-device 則根據語義排名，但需一次性下載模型。搭配 --json 時，信封會標明是哪個層級回答的，因此請檢查該資訊，而不是假設排名已發生。
可安裝性是在排名之後應用的，而非之前：向量承載但此註冊表無法提供的名稱會從結果中移除，並計入 dropped 中，因此非零的 dropped 表示兩者屬於不同世代。請參閱 /hyperframes-cli 了解離線層級、同意門檻以及如何更新過期的索引。
若要瀏覽或篩選而非搜尋：
npx hyperframes catalog
npx hyperframes catalog --type block
npx hyperframes catalog --type component
npx hyperframes catalog --type block --tag social
npx hyperframes catalog --json
npx hyperframes catalog --human-friendly
一般表格模式和 --json 模式僅列出符合條件的項目；使用 hyperframes add <name> 安裝選定的名稱。--human-friendly 會開啟互動式選擇器並立即安裝選中的項目。在 CI 或代理工作流程中，建議使用 --json 後跟明確的 add。
若 CLI 無法連線到設定的註冊表，可透過以下方式檢查原始清單作為備用：
curl -s https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry/registry.json
每個項目的 registry-item.json 包含：名稱、類型、標題、描述、標籤、尺寸（僅區塊）、持續時間（僅區塊）以及檔案列表。
依類型和標籤進行篩選的詳細說明請參閱 discovery.md。
貢獻新的區塊或元件
若要編寫一個全新的註冊表項目（如字幕樣式、VFX 區塊、轉場、下三分之一或可重用元件）並將其作為上游 PR 提交 — 而非安裝現有項目 — 請遵循 contributing.md 中的完整構想 → 框架 → 建置 → 驗證 → 預覽 → 發布工作流程。入門範本（字幕 / VFX / 元件 / registry-item.json）可在 templates.md 中找到。