HyperFrames Core
HyperFrames는 HTML에서 동영상을 렌더링합니다. 구성은 data-* 속성으로 타이밍을 선언하는 DOM을 가진 HTML 파일이며, 애니메이션 런타임은 탐색 가능하고 미디어 재생은 프레임워크가 관리합니다.
이 스킬은 기술 계약입니다. 다른 관련 내용은 다음 스킬에 있습니다:
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-index | references/tracks-and-clips.md |
다른 클립에 상대적인 시간 지정(data-start="intro + 2", 크로스페이드 중첩, 체인) | references/tracks-and-clips.md |
하위 구성 연결(호스트 속성, <template> 래퍼, 인스턴스별 변수) | references/sub-compositions.md |
하위 구성 내 애니메이션(gsap.fromTo over 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>블록을<head>가 아닌<template>내부에 배치하세요.⚠ 호스트 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>Title</h1>
</section>
</div>
</body>
중앙 정렬 컨테이너에 padding(≥80px)을 유지하세요. 큰 텍스트가 프레임 가장자리에 닿지 않도록 하는 타이틀 안전 여백입니다. references/minimal-composition.md를 참조하세요.
타임라인 계약(GSAP 기본값)
모든 구성은 정확히 하나의 GSAP 타임라인을 등록합니다.
gsap.timeline({ paused: true })로 생성 — 플레이어가 재생을 관리합니다.window.__timelines["<composition-id>"]에 등록합니다. 키는 루트의data-composition-id와 정확히 일치해야 합니다. 점 구문(window.__timelines.<id> = tl)은 id가 유효한 식별자일 때 동일합니다. 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). (동기 타임라인 구축은 위의 타임라인 계약에서 다룹니다.)
- 시각적 요소에
Math.random()/Date.now()/performance.now()사용 금지 — 시드 기반 PRNG를 사용하세요. repeat: -1금지.repeat: Math.max(0, Math.floor(duration / cycleDuration) - 1)사용 —floor,ceil아님(ceil은data-duration을 초과하여gsap_repeat_ceil_overshoot린트를 유발합니다.max(0, …)는 음수 반복 = 무한을 방지합니다).<video>/<audio>는 호스트 루트(index.html)의 직접적인 자식이어야 합니다. 하위 구성<template>내부나 래퍼<div>내부에 절대 배치하지 마십시오. 그렇지 않으면 디코딩되지 않고 빈/검은색으로 렌더링됩니다(무음). 프레임워크가 재생을 관리합니다.video.play()/audio.play()/currentTime = …사용 금지. 하위 구성은 호스트 요소를 구동할 수 없으므로(선택자 또는querySelector) 호스트 미디어는 메인 타임라인에서 글로벌 시간으로 애니메이션 처리하세요.references/variables-and-media.md를 참조하세요.- 이후 씬의 클립 요소에
gsap.set()사용 금지(아직 DOM에 없음). 클립의data-start시점 또는 이후에tl.set(selector, vars, time)을 사용하세요. display/visibility애니메이션 금지.opacity/ 변환을 애니메이션 처리하세요. 클립 수명 주기가 표시/숨김을 처리합니다.- 본문 텍스트에
<br>사용 금지.max-width를 통해 텍스트가 줄바꿈되도록 하세요. - 변환된 요소는 블록 수준이어야 하며 크기가 지정되어야 합니다.
transform/scaleX/scaleY는 인라인<span>에서 작동하지 않으며, 자동 너비(0px) 요소를 스케일링하면 아무것도 표시되지 않습니다 → 보이지 않는 막대/채우기.display: block/inline-block/flex-item 및 실제width/height(예: 크기 조정된 부모 내에서width: 100%)를 지정하세요. - 절대 위치 지정 장식 요소(배지, 알약, 태그)가 맥동하거나 오버슈트하는 경우(
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>실행 후 각 프레임을 육안 검사