HyperFrames 코어
HyperFrames는 HTML에서 비디오를 렌더링합니다. 컴포지션은 data-* 속성으로 타이밍을 선언하고, 애니메이션 런타임이 탐색 가능하며, 미디어 재생이 프레임워크에 의해 소유되는 DOM을 가진 HTML 파일입니다.
이 스킬은 기술 계약서입니다 — 하나의 하이퍼프레임스 프로젝트를 구축하는 방법입니다. 아래 본문은 구축 가이드입니다. 주제별 세부 정보는 references/ (다음 인덱스 참조)에 있으며, 필요 시 읽으십시오. 다른 문제는 형제 도메인 스킬인 hyperframes-animation, hyperframes-creative, media-use, 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-인덱스 처리, 다른 클립에 상대적인 클립 타이밍 설정 |
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/review-loop.md | 라이브 보드에서 계획 → 스케치 → 구축 검토 패스 실행 — 모든 스토리보드 계획 워크플로우에서 공유됨 |
references/production-loop.md | 승인된 계획을 완성된 비디오로 전환 — 스테이지 종속성 (오디오, 프레임, 조립, 전환, 자막, 확인, 전달) 자유 형식 구축이 직접 따름 |
references/brief-contract.md | 브리프의 기본 규칙 — 모드 유도 (협업 / 자율), 공유 필드 레지스트리, 질문 불변 사항 (질문 자체는 /hyperframes → 의도 레이어에 있음) |
references/brief-format.md | BRIEF.md 작성 — 워크플로우의 설정이 작성하고 이후 모든 단계가 읽는 확인된 의도 문서 |
references/script-format.md | 선택적 SCRIPT.md 잠긴 내레이션 작성 |
references/subagent-dispatch.md | 하위 에이전트 디스패치 동사 (병렬 팬아웃 / 백그라운드 / 대기)를 하네스에 매핑 |
references/frame-worker-core.md | 공유 프레임 워커 역할 계약 — 각 내러티브 워크플로우의 패킷 빌더가 해당 워크플로우의 sub-agents/frame-worker.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.
루트는 크기가 지정되어야 함 (무음 레이아웃 버그)
독립형 루트는 명시적인 크기가 지정된 상자 (px 단위의 width/height)가 필요하며, height:100% 요소까지의 모든 상위 요소는 해결된 높이가 있어야 합니다. 그렇지 않으면 flex/100% 자식이 ~0으로 축소되고 콘텐츠가 왼쪽 상단 모서리에 쌓입니다. 자동화된 게이트만으로 이를 잡을 수 있다고 믿지 마십시오. 스냅샷을 검사하십시오. 스켈레톤 → references/minimal-composition.md.
하나의 일시 중지된 타임라인
각 컴포지션은 window.__timelines["<id>"] (키 = 루트 data-composition-id)에 정확히 하나의 gsap.timeline({ paused: true })를 등록하며, 페이지 로드 시 동기적으로 구축됩니다. 렌더링 기간 = 루트 data-duration이며, 타임라인 길이가 아닙니다. 수동으로 서브 타임라인을 호스트에 중첩하지 마십시오. 전체 계약 (비 GSAP 런타임 포함) → references/determinism-rules.md + hyperframes-animation/adapters/.
첫 번째 패스 린트 함정 (보장된 첫 번째 빌드 실패)
lint가 잡아내는 두 가지 규칙이지만, 사후에만 잡힙니다. 처음부터 올바르게 작성하십시오:
- 루트 컴포지션 요소는
data-start="0"을 반드시 포함해야 합니다. (data-composition-id/data-width/data-height와 함께). 생략하면lint가root_composition_missing_data_start오류를 발생시킵니다. - CSS 초기
transform을 동일한 속성에 대한 GSAP 트윈과 절대 짝지어 사용하지 마십시오. CSS 값과 트윈의 시작이 충돌하여lint가gsap_css_transform_conflict로 거부합니다. CSStransform: translateX(-40px)대신gsap.fromTo(el, { x: -40 }, { x: 0 })을 사용하여 트윈 내부에서 초기 상태를 설정하십시오.
불가침 규칙 (자동화 게이트가 놓칠 수 있는 무음 버그)
여기에 표시됨. 전체 근거는 연결된 참조에 있음. 위반하지 마십시오:
- 렌더링 시간 시계 / 시드되지 않은
Math.random/ 네트워크 / 입력 상태 없음;repeat: -1없음 (유한 횟수 사용). →determinism-rules.md - 시각적 속성 허용 목록만 애니메이션;
display또는 원시visibility는 절대 트윈하지 마십시오. GSAPautoAlpha및 길이가 0인 타임라인 경계 설정만이 가시성 예외이며, 클립 요소가 아니거나 클립 내부의 래퍼에서만 가능합니다. 프레임워크만이.clip가시성을 제어합니다. 페이지 로드 시 나중 장면 클립에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-hidden속성은 미리보기와 렌더링 모두에서 요소를 숨기며, 시간 창을 무시합니다. 이는 비파괴적/가역적이며 Studio의 타임라인 눈 아이콘으로 전환됩니다. - 서브 컴포지션 추가: 호스트를 연결하기 전에 내부
data-composition-id를 확인하십시오.
유효성 검사
명령어 세부 사항은 hyperframes-cli 사용
-
npx hyperframes check통과 (린트, 런타임, 레이아웃, 모션 및 대비에서 0개의 발견 사항) - 서브 컴포지션이 있는 프로젝트:
npx hyperframes snapshot --at <중간점>및 각 프레임을 육안으로 확인 - 검토를 위해
npx hyperframes preview(사용자는 Studio의 타임라인에서 무엇이든 편집 가능) - 사용자가 승인한 후에만
npx hyperframes render