HyperFrames 핵심은(는) 무엇을 하나요?
HyperFrames는 HTML에서 비디오를 렌더링합니다. 합성은 data-* 속성으로 타이밍을 선언하는 DOM을 가진 HTML 파일이며, 해당 애니메이션 런타임은 탐색 가능해야 하고 미디어 재생은 프레임워크가 소유합니다.
이 스킬은 기술 계약입니다 — 하나의 HyperFrames 프로젝트를 구축하는 방법입니다. 아래 본문은 빌드 가이드입니다; 주제별 세부 내용은 references/ (인덱스는 다음)에 있으며, 필요 시 읽으십시오. 다른 관련 사항은 형제 도메인 스킬인 hyperframes-animation, hyperframes-creative, hyperframes-media, 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/script-format.md | 선택적 SCRIPT.md 잠긴 내레이션 작성 |
references/subagent-dispatch.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으로 축소되어 콘텐츠가 왼쪽 상단 모서리에 쌓입니다. lint/validate/inspect는 이를 포착하지 않습니다. 뼈대 → references/minimal-composition.md.
하나의 일시 중지된 타임라인
각 합성은 페이지 로드 시 동기적으로 구축된 window.__timelines["<id>"]에 정확히 하나의 gsap.timeline({ paused: true })를 등록합니다 (키 = 루트 data-composition-id). 렌더링 기간 = 루트 data-duration, 타임라인 길이가 아님. 하위 타임라인을 호스트에 수동으로 중첩하지 마십시오. 전체 계약 (GSAP가 아닌 런타임 포함) → references/determinism-rules.md + hyperframes-animation/adapters/.
양보할 수 없는 규칙 (lint/validate/inspect가 포착하지 못하는 조용한 버그)
여기에 표시됨; 전체 근거는 링크된 참고 자료에 있음. 위반하지 마십시오:
- 렌더링 시간 시계 / 시드되지 않은
Math.random/ 네트워크 / 입력 상태 없음;repeat: -1없음 (유한 카운트 사용). →determinism-rules.md - 시각적 속성 허용 목록만 애니메이션;
display/visibility절대 사용 금지; 나중 장면 클립에gsap.set없음. →determinism-rules.md - 본문 텍스트에
<br>없음; 변환된 요소는 블록 수준 + 크기 지정되어야 함; 맥동하는 절대 위치 장식 요소는 최대 여유 공간 필요. →determinism-rules.md <video>/<audio>는 호스트 루트의 직접 자식이어야 함 (하위 컴포지션<template>/래퍼 내부 절대 안 됨); 프레임워크가 재생 소유. →variables-and-media.md- 모든
id는 조립된 페이지에서 고유해야 함; 하위 컴포지션 내에서는 합성 ID로 ID 접두어 추가 (#<id>-hero). 중복<video>/<img>id는 공백으로 렌더링됨 — 프로듀서는getElementById로 프레임을 삽입하며, 교차 파일 중복은lint를 빠져나갑니다. →composition-patterns.md - 전체 화면 장면 채우기는 전체 영역 자식 (
position:absolute; inset:0)에 가야 하며, 합성 루트 자체에는 절대 안 됨 — 프로듀서의 프레임 합성은 루트 요소의 자체background를 삭제할 수 있으며 (프레임이 검은색으로 렌더링됨) 미리보기/snapshot에서는 올바르게 표시되더라도 그렇습니다. →composition-patterns.md
기존 합성 편집
- 먼저 파일을 읽으십시오. 관련 없는 타이밍, 트랙, ID, 변수, 미디어 경로를 보존하십시오.
- 기존 합성 ID 및 타임라인 키와 일치하십시오.
- 클립 추가: 겹치지 않는
data-track-index를 선택하거나 의도적으로 주변 타이밍을 조정하십시오. - 하위 합성 추가: 호스트를 연결하기 전에 내부
data-composition-id를 확인하십시오.
검증
명령어 세부 사항은 hyperframes-cli 사용
-
npx hyperframes lint통과 (0 오류) -
npx hyperframes validate통과 (0 콘솔 오류) -
npx hyperframes inspect통과 (0 오류) - 하위 합성이 있는 프로젝트:
npx hyperframes snapshot --at <midpoints>및 각 프레임 육안 검사 -
npx hyperframes preview검토용 (사용자는 Studio의 타임라인에서 무엇이든 편집 가능) - 사용자 승인 후에만
npx hyperframes render