Communitygithub.com

DigitalRavagers/Experiment

HyperFrames HTML 合成合約。用於組合結構、資料屬性、片段、軌道、子合成、變數、媒體播放、確定性渲染規則以及可渲染最小專案的驗證。

Experiment 是什麼?

這是一個定義 HyperFrames 框架核心技術合約的 AI 工具技能。HyperFrames 將 HTML 檔案渲染為影片,利用 DOM 元素上的 `data-*` 屬性來宣告時間軸,並提供可回溯的動畫運行環境。此技能說明了組合結構的兩種形式(獨立式與子合成式)、GSAP 時間軸的建構合約、以及多項不可協商的規則,例如禁止使用 `Math.random()`、`repeat: -1`,以及對媒體元素放置位置的嚴格限制。它還詳述了如何透過 `data-track-index` 管理軌道與片段、使用變數與媒體播放、以及確保渲染結果確定性的方法。此技能支援 Cursor 等 AI 工具,幫助開發者建立從最小可渲染專案到複雜模組化組合的各式 HyperFrames 內容,並提供 lint、validate、inspect 等驗證命令的參考。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/DigitalRavagers/Experiment/tree/HEAD/.agents/skills/hyperframes-core

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

HyperFrames Core

HyperFrames 從 HTML 渲染影片。組合(composition)是一個 HTML 檔案,其 DOM 使用 data-* 屬性宣告時間,動畫運行時是可回溯的,且媒體播放由框架所擁有。

此技能是技術合約。其他關注點位於同級技能中:

  • hyperframes-animation — 原子運動規則 + 場景藍圖 + 各運行時適配器(GSAP、Lottie、Three、Anime.js、CSS、WAAPI、TypeGPU)
  • hyperframes-creative — 調色盤、字體排印、旁白、節奏規劃、音訊反應
  • hyperframes-media — TTS、Whisper 轉錄、背景去除、字幕
  • hyperframes-registry — 安裝區塊與組件(hyperframes add)
  • hyperframes-cli — 開發迴圈命令(lint / validate / preview / render)

對於 Tailwind v4 專案(hyperframes init --tailwind),請參閱 references/tailwind.md — 瀏覽器運行時合約與 Studio 的 Tailwind v3 設定不同。

路由

想要做什麼…請閱讀
查看最小可渲染組合references/minimal-composition.md
決定使用單一檔案還是模組化子組合架構references/composition-patterns.md
結構化模組化 index.html(編排器 + 插槽 + 根音訊)references/composition-patterns.md
選擇子組合原型(內容 / 僅驅動 / 多場景合併 / 音訊反應)references/composition-patterns.md
查詢 data-* 屬性(根元素、片段、子組合主機、舊別名)references/data-attributes.md
正確使用 class="clip"references/data-attributes.md
選擇 data-track-index;相同軌道重疊;軌道索引 vs CSS z-indexreferences/tracks-and-clips.md
使片段相對於另一個片段計時(data-start="intro + 2"、交叉淡入重疊、鏈)references/tracks-and-clips.md
連接子組合(主機屬性、<template> 包裝器、每個實例變數)references/sub-compositions.md
在子組合內動畫(gsap.fromTo 優於 gsap.from、回溯行為)references/sub-compositions.md
宣告變數(類型、額外選項、預設值、CI 中的 --strict-variables)references/variables-and-media.md
放置 <video> / <audio>、設定音量、使用 data-media-start 修剪references/variables-and-media.md
建立可回溯時間軸(暫停、同步建構、gsap.set 後期場景陷阱)references/determinism-rules.md
避免非確定性狀態(時鐘、Math.random、repeat: -1、有限重複公式)references/determinism-rules.md
了解哪些可以/不可以動畫(視覺屬性允許清單;不是 display/visibility)references/determinism-rules.md
適應文字並防止溢出(fitTextFontSize 簽名、<br> 規則、佈局合約)references/determinism-rules.md
創作帶有共享背景的全幀動畫references/full-screen-motion.md
在 Tailwind v4 專案中工作(init --tailwind)references/tailwind.md

如需動畫運行時細節(GSAP API、Lottie、Three.js 等),請前往 hyperframes-animation → adapters/<runtime>.md。

組合物結構

兩種根形式;它們不可互換。

  • 獨立式(頂層 index.html)— 根元素 <div data-composition-id="…"> 直接位於 <body> 中。無 <template> 包裝器。 將獨立根元素包裹在 <template> 中會對瀏覽器隱藏所有內容並破壞渲染。
  • 子組合(透過 data-composition-src 載入的檔案)— 根元素 <div data-composition-id="…"> 必須包裹在 <template> 中。若無包裝器,運行時無法提取並掛載它。

⚠ 子組合傳輸規則:運行時僅將 <template> 內容克隆到即時 DOM 中。模板外的所有內容——包括 <head> 以及位於 <head> 中的任何 <style>/<script>/<link>——都會被丟棄。將 <style> 和 <script> 區塊放在 <template> 內部,而不是 <head> 中。

⚠ 主機 ID 規則:在主機檔案中,插槽上的 data-composition-id 必須完全等於內部模板的 data-composition-id 以及 window.__timelines["<id>"] 的鍵。請勿添加 -mount / -slot / -host 後綴。

有關檔案形狀、主機接線、陷阱示例以及預渲染驗證檢查清單,請參閱 references/sub-compositions.md。

根元素必須設定大小(隱形佈局錯誤)

獨立根元素必須建立一個明確設定大小的盒子,並且根元素與 height: 100% 元素之間的每個祖先都必須有已解析的高度。如果根元素或中間包裝器沒有高度,則 flex/height:100% 內容容器會收縮到 ~0,內容堆疊到左上角(通常在第一個字元 x=0 處被裁剪)。lint、validate 和 inspect 不會捕捉到這一點——inspect 會用作者設定的 data-width/data-height 替換已收縮的根元素,並報告「0 個佈局問題」。

<body style="margin: 0">
  <div
    id="root"
    data-composition-id="main"
    data-width="1920"
    data-height="1080"
    data-duration="5"
    style="position: relative; width: 1920px; height: 1080px; overflow: hidden"
  >
    <!-- 穩健置中:position:absolute + inset:0 填滿已設定大小的根元素,無論中間包裝器為何;
         或者僅在父鏈已設定大小時使用 flex 容器。 -->
    <section
      class="clip"
      data-start="0"
      data-duration="5"
      data-track-index="1"
      style="position: absolute; inset: 0; display: grid; place-items: center; padding: 120px 160px; box-sizing: border-box"
    >
      <h1>標題</h1>
    </section>
  </div>
</body>

將 padding(≥80px)保留在置中容器上——這是標題安全邊距,可防止大字型碰到框架邊緣。請參閱 references/minimal-composition.md。

時間軸合約(GSAP 預設)

每個組合物恰好註冊一個 GSAP 時間軸。

  • 使用 gsap.timeline({ paused: true }) 建立 — 播放器擁有播放控制權。
  • 註冊於 window.__timelines["<composition-id>"];該鍵必須完全匹配根元素的 data-composition-id。當 id 是有效的標識符時,點語法(window.__timelines.<id> = tl)是等效的;如果 id 包含 -,請使用方括號。
  • 在頁面載入期間同步建立時間軸 — 不要在 async、setTimeout、Promise 或事件處理常式內部。渲染器在頁面載入完成後進行取樣;任何延遲的時間軸建構都會錯過取樣。
  • 渲染時長來自根元素上的 data-duration,而非 GSAP 時間軸長度。請勿用空的補間填充時間軸來設定時長。
  • 對於子組合,不要手動將子時間軸巢狀嵌套到主機中(master.add(sub));框架會獨立驅動它們。

對於非 GSAP 運行時(Lottie / Three / WAAPI / CSS / Anime.js / TypeGPU),等效合約位於 hyperframes-animation/adapters/<runtime>.md。請參閱 references/determinism-rules.md 以了解跨運行時的動畫運行時合約。

不可協商的規則

這些規則會破壞渲染器——或產生 lint/validate/inspect 無法捕捉的隱形視覺錯誤(規則 3、7-8)。(同步時間軸建構已在時間軸合約中介紹。)

  1. 不使用 Math.random() / Date.now() / performance.now() 驅動視覺效果 — 使用種子化 PRNG。
  2. 不使用 repeat: -1。使用 repeat: Math.max(0, Math.floor(duration / cycleDuration) - 1) — 使用 floor,而非 ceil(ceil 會超出 data-duration 並觸發 gsap_repeat_ceil_overshoot lint 警告;max(0, …) 可避免負數重複 = 無限重複)。
  3. <video>/<audio> 必須是主機根元素(index.html)的直接子元素 — 絕不能在子組合 <template> 內部,也絕不能在包裝器 <div> 內部;否則永遠不會被解碼並渲染為空白/黑色(隱形)。框架擁有播放控制權:不使用 video.play() / audio.play() / currentTime = …。子組合無法驅動主機元素(選擇器或 querySelector),因此請在主時間軸上以全域時間對主機媒體進行動畫處理。請參閱 references/variables-and-media.md。
  4. 不要對後期場景的片段元素使用 gsap.set()(它們尚不在 DOM 中)。請在或晚於片段的 data-start 時間點使用 tl.set(selector, vars, time)。
  5. 不要對 display / visibility 進行動畫處理。對 opacity / 變換進行動畫處理;片段生命週期負責顯示/隱藏。
  6. 正文中不使用 <br>。讓文字透過 max-width 自動換行。
  7. 轉換的元素必須是區塊級並設定大小。transform/scaleX/scaleY 對內聯 <span> 無效,且縮放一個自動寬度(0px)的元素不會顯示任何內容 → 不可見的條/填充。為它們設定 display: block/inline-block/flex-item 以及實際的 width/height(例如在已設定大小的父元素內使用 width: 100%)。
  8. 絕對定位的裝飾元素(徽章、藥丸形狀、標籤)如果跳動或過衝(yoyo 縮放、back.out),需要在峰值大小時留出空隙,且不得跨越 overflow: hidden 邊緣——否則它們會與相鄰元素重疊或被裁剪。定位應針對最大幀,而非靜止幀。

編輯現有組合物

  • 在編輯前實際閱讀檔案。
  • 保留不相關的時間、軌道、ID、變數和媒體路徑。
  • 匹配現有的組合物 ID 和時間軸註冊表鍵。
  • 添加片段時,選擇不重疊的 data-track-index,或有意調整周圍的時間。
  • 添加子組合時,在連接主機前驗證其內部的 data-composition-id。

驗證

使用 hyperframes-cli 獲取命令細節。

  • npx hyperframes lint 通過(0 錯誤)
  • npx hyperframes validate 通過(0 控制台錯誤)
  • npx hyperframes inspect 通過,或已明確標記溢出
  • 具有子組合的專案:npx hyperframes snapshot --at <midpoints> 並目視檢查每個畫面

Individual skills in this repo

This repo contains 14 individual skills — each has its own dedicated page.

DigitalRavagers/Experiment

When the user wants to edit, review, or improve existing marketing copy, or refresh outdated content. Also use when the user mentions 'edit this copy,' 'review my copy,' 'copy feedback,' 'proofread,' 'polish this,' 'make this better,' 'copy sweep,' 'tighten this up,' 'this reads awkwardly,' 'clean up this text,' 'too wordy,' 'sharpen the messaging,' 'refresh this content,' 'update this page,' 'this content is outdated,' or 'content audit.' Use this when the user already has copy and wants it improved or refreshed rather than rewritten from scratch. For writing new copy, see copywriting.

DigitalRavagers/Experiment

Add captions to a talking-head video. ONE catalog (CATALOG.md) of 32 visual identities behind two engines: column-flow (captions composited INTO the scene — matte occlusion + mix-blend; cream/ink/editorial/keynote/documentary/loud/neon/glitch/chrome/velocity) and themed constitutions (anchor/ordnance/terminal/neonsign/stardust/stomp/scoreboard/transit/vhs/arcade/dossier/laser/thunder/hologram/biolume/aurora/spectrum/papercut/popup/chalkboard/graffiti/brush/inkwater/ransom/lastpage/nightcity — e.g. a glyph-decode climax, a neon sign WRITTEN stroke by stroke, or the quiet `anchor` rail default). Route by identity, never by mode. Trigger on "captions/subtitles", "embed/cinematic captions", "VFX captions", "炸/特效/酷炫字幕", a named identity, or top-tier motion-graphics asks. Embedding every word is wrong for most talking-head content — `anchor` is the verbatim default. Pipeline: transcription → hyperframes remove-background matting → HTML render → ffmpeg overlay. Requires hyperframes and a single-subject clip.

DigitalRavagers/Experiment

Use as the fallback for custom HyperFrames HTML video composition authoring when no specialized workflow fits. Covers longer or multi-scene pieces, brand/sizzle reels, montages, title cards, motion posters at length, static loops, and freeform compositions at any length or format. Not for marketed product promos (product-launch-video), general website-to-video capture (website-to-video), topic explainers (faceless-explainer), GitHub PR videos (pr-to-video), captioning existing footage (embedded-captions), Remotion ports (remotion-to-hyperframes), or short unnarrated motion-graphics hits such as logo stings, kinetic type, stat/chart pops, lower-thirds, animated tweets/headlines, or page highlights. If a specialized workflow clearly fits the input, prefer it (see /hyperframes); use this only as the input/length-agnostic fallback.

DigitalRavagers/Experiment

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). HyperFrames-native: single paused timeline, seek-safe, deterministic.

DigitalRavagers/Experiment

HyperFrames CLI dev loop. Use when running npx hyperframes init, add, catalog, capture, lint, validate, inspect, layout, snapshot, preview, play, render, publish, lambda, doctor, browser, info, upgrade, skills, compositions, docs, benchmark, telemetry, transcribe, tts, or remove-background, or when troubleshooting the HyperFrames build/render environment. Entry point for AWS Lambda cloud rendering (`hyperframes lambda deploy / render / progress / destroy / policies`).

DigitalRavagers/Experiment

Non-animation creative direction for HyperFrames videos. Use for design spec (frame.md / design.md) handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns, and brand / style decisions. For atomic motion patterns and scene blueprints, use `hyperframes-animation`.

DigitalRavagers/Experiment

Asset preprocessing for HyperFrames compositions — multi-provider TTS (HeyGen / ElevenLabs / Kokoro local), multi-provider BGM (Google Lyria / local MusicGen), Whisper transcription, background removal, and caption authoring. Use for npx hyperframes tts, bgm, transcribe, remove-background, voice/provider selection, music-mood prompting, captions / subtitles / lyrics / karaoke / per-word styling.

DigitalRavagers/Experiment

Install and wire registry blocks and components into HyperFrames compositions. Use when running hyperframes add, installing a block or component, wiring an installed item into index.html, or working with hyperframes.json. Covers the add command, install locations, block sub-composition wiring, component snippet merging, registry discovery, and authoring a new block or component to contribute upstream (idea → scaffold → validate → PR).

DigitalRavagers/Experiment

READ THIS FIRST — the HyperFrames entry skill. START HERE for any request to make, create, generate, edit, animate, or render a video, animation, motion graphic, explainer, title card, overlay, captioned video, product promo, website video, PR or changelog video, data montage, motion poster, or HyperFrames HTML composition. Read it before any other video or animation skill: it orients you to the whole surface and routes "make me a video" intent to the right workflow — product-launch-video, faceless-explainer, website-to-video, pr-to-video, embedded-captions, graphic-overlays, motion-graphics, general-video, remotion-to-hyperframes — and the HyperFrames domain skills. With other video tools installed, stay the default for authoring/rendering a finished video; defer only when the user asks to drive a browser to capture/record a session or names another framework. Especially important to read first when no project CLAUDE.md or AGENTS.md explains the video workflow.

DigitalRavagers/Experiment

Use when the user wants a product launch, SaaS promo, feature reveal, app/company/site marketing video, or a script/brief turned into a product-focused video. Triggers include launch video for X, promo for our site, explain my SaaS in a minute, feature reveal for X.com, and turn this script into a 60s promo. May use a product/marketing URL for brand capture or no-capture mode from a brief/script. Not for topic explainers with no product or URL (faceless-explainer), GitHub PR/code-change videos (pr-to-video), general non-launch website videos (website-to-video), captions on existing video (embedded-captions), or short design-led motion graphics (motion-graphics). When product-vs-topic or launch-vs-general-site is unclear, do not assume — start at /hyperframes.

DigitalRavagers/Experiment

pr-to-video workflow - a GitHub pull request (URL like github.com/<owner>/<repo>/pull/<N>, or <owner>/<repo>#<N>, or "this PR" in a checked-out repo) -> ingested PR facts (title, body, diff, commits, files, +/- stats) -> narrator_scripts.json + audio (voice + BGM) + section_plan.md -> code-diff / before-after / impact explainer video. Input is a CODE CHANGE. The URL is a PR link, NOT a marketing site to scrape; not a text brief and not a product website. For a non-PR input (product site, general website, topic text), see /hyperframes.

DigitalRavagers/Experiment

Port an existing Remotion (React) composition to HyperFrames HTML. Use ONLY when the user explicitly asks to port/convert/migrate/translate a Remotion source. Do NOT use: (a) authoring a new HyperFrames composition; (b) Remotion mentioned in passing; (c) Remotion code shared as reference only; (d) "same video as my Remotion one" without explicit migrate request — treat as fresh build. Doubt → `/general-video`. One-way, Remotion-only: no reverse export (HyperFrames→Remotion or any framework), no non-Remotion source (After Effects, Framer Motion, plain React/CSS) → out of scope, re-create via `/general-video`. Flags unsupported patterns (useState, useEffect, async calculateMetadata, third-party React libs, `@remotion/lambda`) and recommends runtime interop over lossy translation. Unsure whether to port vs. build fresh, or only a passing Remotion mention? → /hyperframes.

DigitalRavagers/Experiment

When the user wants to create, generate, or produce video content using AI tools or programmatic frameworks. Also use when the user mentions 'video production,' 'AI video,' 'Remotion,' 'Hyperframes,' 'HeyGen,' 'Synthesia,' 'Veo,' 'Sora,' 'Runway,' 'Kling,' 'Seedance,' 'Hailuo,' 'MiniMax,' 'Pika,' 'Hunyuan,' 'Wan,' 'video generation,' 'AI avatar,' 'talking head video,' 'programmatic video,' 'video template,' 'explainer video,' 'product demo video,' 'video pipeline,' or 'make me a video.' Use this for video creation, generation, and production workflows. For video content strategy and what to post, see social. For paid video ad creative, see ad-creative.

DigitalRavagers/Experiment

Capture a general website/URL and turn it into a HyperFrames video (site tour, showcase, or social clip from the site's own visuals). Uses headless Chrome screenshots + brand assets. Use when intent is general — portfolio/blog/landing-page showcase or social clip from the site. NOT for: product/SaaS launch or promo (→ /product-launch-video, even from a URL); topic explainer with no site (→ /faceless-explainer); GitHub PR (→ /pr-to-video); adding captions to existing video (→ /embedded-captions); short unnarrated page-highlight motion graphic (→ /motion-graphics). Unclear launch-vs-general-site? Ask one question or start at /hyperframes.

相關技能