topcheer/ggcode

HyperFrames 코어

HyperFrames는 HTML에서 비디오를 렌더링합니다. 컴포지션은 DOM이 data-* 속성으로 타이밍을 선언하고, 애니메이션 런타임을 탐색할 수 있으며, 미디어 재생이 프레임워크에 의해 제어되는 HTML 파일입니다.

이 스킬은 기술 계약입니다 — 하나의 hyperframes 프로젝트를 빌드하는 방법입니다. 아래 본문은 빌드 가이드입니다; 주제별 세부 사항은 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-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/review-loop.md	라이브 보드에서 계획 → 스케치 → 빌드 검토 패스 실행 — 모든 스토리보드 계획 워크플로에서 공유
references/production-loop.md	승인된 계획에서 전달된 비디오로 — 스테이지 종속성(오디오, 프레임, 어셈블리, 전환, 캡션, 확인, 전달) 자유 형식 빌드는 직접 따름
references/brief-contract.md	브리프의 기본 규칙 — 모드 파생(협업/자율), 공유 필드 레지스트리, 질문 불변성(질문 자체는 /hyperframes → 의도 계층에 있음)
references/brief-format.md	BRIEF.md 작성 — 워크플로의 Setup이 작성하고 이후 모든 단계에서 읽는 확인된 의도 문서
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.

루트는 크기가 지정되어야 함(무음 레이아웃 버그)

독립형 루트에는 명시적인 크기 박스(width/height px 단위)가 필요하며, 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/.

양보할 수 없는 규칙(자동화된 게이트가 놓칠 수 있는 무음 버그)

여기에 표시됨; 전체 설명은 연결된 참조에 있습니다. 위반하지 마십시오:

• 렌더링 시간 시계/시드되지 않은 Math.random/네트워크/입력 상태 없음; repeat: -1 없음(유한 횟수 사용). → determinism-rules.md
• 시각적 속성 허용 목록만 애니메이션; display 또는 원시 visibility는 절대 트윈하지 마십시오. GSAP autoAlpha와 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를 확인하십시오.

유효성 검사

CLI 명령어 세부 사항은 hyperframes-cli 사용

• npx hyperframes check 통과(린트, 런타임, 레이아웃, 모션, 대비에서 0개 발견)
• 하위 컴포지션이 있는 프로젝트: npx hyperframes snapshot --at <midpoints> 및 각 프레임 육안 검사
• 검토를 위해 npx hyperframes preview(사용자는 Studio의 타임라인에서 무엇이든 편집 가능)
• 사용자 승인 후에만 npx hyperframes render