HyperFrames Core
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 | 모놀리식 대 모듈식 중 선택합니다. 모듈식 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.
루트는 크기가 지정되어야 함(무음 레이아웃 버그)
단독형 루트에는 명시적인 크기 상자(width/height in 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/.
첫 번째 패스 린트 주의 사항(보장된 첫 번째 빌드 실패)
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와 제로 지속 시간 타임라인 경계 설정이 유일한 가시성 예외이며, 클립 내부의 비클립 요소 또는 래퍼에서만 가능합니다. 프레임워크만이.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 <midpoints>실행 및 각 프레임을 육안으로 확인 - 검토를 위해
npx hyperframes preview사용(사용자는 Studio의 타임라인에서 무엇이든 편집 가능) - 사용자 승인 후에만
npx hyperframes render실행