AntlersSam/saas-launch-video-kit

플러그인 설치: 설정 또는 새로고침 명령 전에 이 스킬이 HyperFrames 플러그인 내에 있을 경우 플러그인 실행 규칙을 따르십시오. 독립형 설치는 아래 업데이트 지침을 유지합니다.

HyperFrames Core

에이전트 주의사항 (먼저 읽으십시오):

• CSS transform: translate(-50%,-50%)를 사용하지 않고 flex/inset으로 중앙 정렬하십시오. GSAP x/y를 적용할 노드에 사용하지 마십시오. 린트: gsap_css_transform_conflict. fromTo 또는 xPercent/yPercent를 사용하십시오.
• 장면 종료 tl.set(..., {visibility:"hidden"})을 추가하지 마십시오. 런타임이 이미 타임드 클립을 숨깁니다. 내부 노드의 불투명도 페이드(또는 .clip의 opacity)만으로 충분합니다. 캡션 하드킬은 별도 규칙입니다.
• window.__timelines["id"]는 루트 data-composition-id와 일치해야 합니다.
• render 후, 요약의 두 번째 줄(beginframe vs screenshot, GPU 모드, 단계 타이밍)을 읽으십시오. Linux에서 screenshot + software gpu는 느린 경로입니다.

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

이 스킬은 기술 계약 — 하나의 hyperframes 프로젝트를 구축하는 방법입니다. 본문은 빌드 가이드이며; 주제별 세부 사항은 references/ (다음 인덱스 참조)에 있으며, 필요 시 읽으십시오. 프로세스 문서 (개요, 스토리보드, 검토, 제작, 디스패치, 프레임-워커)는 /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, 다른 클립에 대한 상대적 시간 이해; npx hyperframes timeline으로 모든 트랙과 클립 나열
references/creator-editing-recipes.md	정확한 잘라내기/트림/재정렬/재시간/프리즈/카메라/마스크/크로스페이드/오디오 편집 레시피와 그 제한사항 복사
references/sub-compositions.md	하위 컴포지션 연결 (호스트 속성, <template>, 인스턴스별 변수) 및 내부 애니메이션
references/variables-and-media.md	변수 선언; <video>/<audio> 배치, 볼륨 설정, 트림
references/determinism-rules.md	탐색 가능한 타임라인 구축; 결정론 금지 사항; 레이아웃 / 텍스트 맞춤
references/full-screen-motion.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> 래퍼가 없습니다. 독립형 루트를 래핑하면 모든 콘텐츠가 숨겨지고 lint가 이를 거부합니다 (standalone_composition_wrapped_in_template, 오류).
• 하위 컴포지션 (data-composition-src를 통해 로드됨): 루트를 <template>으로 감쌉니다. 이것이 작성할 형태입니다: 로더는 일반 전체 문서도 허용하고 <body>로 폴백하지만, 템플릿 형태가 예제와 도구에서 가정하는 형태입니다.

⚠ 전송 규칙: 템플릿화된 하위 컴포지션의 경우 어셈블러가 파일 자체의 <head> <style>/<script>를 삭제합니다 (packages/core/src/compiler/compositionAssembly.ts, hasTemplate 게이트). 따라서 <style>/<script>를 템플릿 내부에 넣으십시오. <link>는 어느 쪽이든 호이스트됩니다. ⚠ 호스트-ID 규칙: 호스트 슬롯, 내부 템플릿, 그리고 window.__timelines["<id>"] 키에 동일한 id를 부여하십시오. 다른 로컬 id도 지원되지만 (어셈블러가 파일의 첫 번째 루트로 폴백), 불일치는 조용히 처리되므로, 특별한 이유가 없다면 일치시키십시오.

파일 형태, 호스트 연결, 사전 렌더링 체크리스트 → references/sub-compositions.md.

루트 크기 지정 필수 (무음 레이아웃 버그)

독립형 루트는 width/height: 100%를 사용합니다. 캔버스 크기는 data-width/data-height입니다. 런타임이 해당 픽셀을 컴포지션 루트에 적용합니다. #root에 1920px/1080px을 하드코딩하지 마십시오. 스켈레톤 → references/minimal-composition.md.

하나의 일시 정지된 타임라인

각 컴포지션은 window.__timelines["<id>"]에 정확히 하나의 gsap.timeline({ paused: true })를 등록합니다 (키 = 루트 data-composition-id). 비동기 콜백 내에서 (document.fonts.ready) 타임라인을 구축하는 것은 지원됩니다. 중요한 것은 구축 완료 후에만 등록하는 것입니다. 렌더링 길이는 루트의 data-duration이며, 타임라인의 길이가 아닙니다: 타임라인이 이를 초과하면 잘리고, 조기 종료되면 마지막 프레임을 유지합니다. 루트 data-duration을 생략하면 길이가 대신 추론됩니다 (타임라인, 미디어 윈도우 또는 어댑터). window.__timelines = window.__timelines || {}가 필요하지 않습니다: 런타임이 인라인 스크립트 실행 전에 레지스트리를 생성하며, lint가 더 이상 요청하지 않습니다. 하위 타임라인을 호스트에 수동으로 중첩하지 마십시오; 런타임이 등록된 하위 타임라인을 자동으로 중첩합니다. 전체 계약 (비 GSAP 런타임 포함) → references/determinism-rules.md + hyperframes-animation/adapters/.

첫 번째 패스 린트 주의사항 (첫 번째 빌드 실패 보장)

lint가 잡아내지만 사후에만 잡는 규칙입니다. 처음부터 올바르게 작성하십시오:

• CSS 초기 transform을 동일한 속성에 GSAP 트윈과 함께 사용하지 마십시오 — CSS 값과 트윈의 시작이 충돌하여 lint가 gsap_css_transform_conflict로 거부합니다. CSS transform: translateX(-40px) 대신 gsap.fromTo(el, { x: -40 }, { x: 0 })를 사용하여 초기 상태를 트윈 내부에 설정하십시오.
• <video>/<audio>에 crossorigin을 절대 사용하지 마십시오. lint가 media_crossorigin_breaks_preview (오류)로 무조건 거부합니다. 캔버스/WebGL/WebAudio 읽기백에도 포함됩니다. 억제할 방법이 없습니다.
• data-start가 있는 <video>의 조상이 data-start를 함께 가지도록 하지 마십시오. lint가 video_nested_in_timed_element (오류)로 거부합니다. 래퍼 또는 비디오에 타이밍을 지정하고, 둘 다에는 지정하지 마십시오.
• 모든 <audio>는 id가 필요합니다. lint가 media_missing_id로 거부하며, id가 없는 <audio>는 믹서에서 절대 선택되지 않으므로 렌더링이 무음이 됩니다.
• .clip을 autoAlpha 또는 visibility로 트위닝하지 마십시오 — lint가 gsap_animates_clip_element로 거부합니다. 대신 자식을 애니메이션하십시오.
• 명명된 CSS font-family는 제공된 로컬 파일에 대한 파일 내 @font-face가 필요하며, 그렇지 않으면 lint가 font_family_without_font_face를 발생시킵니다.
• 하위 컴포지션 #root는 하드코딩된 1920px/1080px이 아닌 width/height: 100% (또는 inset: 0)를 사용합니다. 캔버스 크기는 data-width/data-height입니다.

린트 오류는 레이아웃 및 대비 감사도 비활성화합니다: check는 0 sample(s) 및 0/0 text checks를 보고하며, 이는 깨끗한 파일처럼 보이지만 아무것도 실행되지 않았음을 의미합니다. 해당 숫자를 신뢰하기 전에 린트 오류를 해결하십시오.

불가침 규칙 (자동 게이트가 놓칠 수 있는 무음 버그)

여기에 표시되며, 전체 근거는 링크된 참조에 있습니다. 위반하지 마십시오:

• 렌더링 시간 시계 / 시드되지 않은 Math.random / 네트워크 / 입력 상태 없음; repeat: -1 사용 금지 (유한 횟수 사용). → determinism-rules.md
• .clip 요소에서 display, visibility 또는 autoAlpha를 절대 트위닝하지 마십시오. 프레임워크가 클립 가시성을 소유하며, lint가 이를 거부합니다 (gsap_animates_clip_element). 대신 자식을 애니메이션하십시오. → determinism-rules.md
• 본문 텍스트에 <br> 사용 금지; 변환된 요소는 블록 수준 + 크기 지정 필요; 펄스하는 절대 위치 장식 요소는 피크 여유 공간 필요. → determinism-rules.md
• <video>/<audio>는 평면 문서 쿼리로 찾으므로, 프레임워크가 모든 중첩 깊이에서 이를 탐색하고 디코딩합니다 (하위 컴포지션 <template> 또는 래퍼 내부 포함). 하나의 하드 제한: lint는 data-start가 있는 <video>가 data-start도 있는 다른 일반 요소 내부에 있으면 오류를 발생시키며, 실패는 실제입니다 (잘못된 소스 프레임, 클립이 슬롯 중간에 사라짐). 따라서 타이밍을 래퍼 또는 비디오 중 하나에만 지정하고, 둘 다에는 절대 지정하지 마십시오. 하위 컴포지션 호스트는 면제됩니다: 하위 컴포지션 내부의 미디어는 올바르게 렌더링됩니다. 다른 주의사항은 타임라인 관련이며 배치가 아닙니다: 하위 컴포지션 타임라인은 호스트 루트 요소를 애니메이션할 수 없습니다. → variables-and-media.md
• 조립된 페이지 전체에서 모든 id를 고유하게 유지하십시오 (하위 컴포지션 id에 컴포지션 id 접두사 #<id>-hero를 사용) 그래야 자신의 #id CSS 및 getElementById 호출이 해결됩니다. 프레임 주입은 더 이상 이것에 의존하지 않습니다: 컴파일러가 모든 video[src]/audio[src]/img[src]에 문서 고유의 data-hf-render-id를 스탬프합니다. src 속성 대신 <source> 자식을 사용하는 미디어는 스탬프되지 않으므로, 여전히 고유 id가 중요합니다. → composition-patterns.md
• 컴포지션 루트의 전체 화면 채움은 일반 렌더링에서 괜찮습니다. 레이어드 컴포지트 경로 (HDR 콘텐츠 또는 셰이더 전환을 사용하는 컴포지션)에서만 드롭되며, 엔진이 모든 컴포지션 루트를 투명하게 강제하여 아래 레이어가 보이게 합니다. 컴포지션이 셰이더 전환이나 HDR 미디어를 사용하는 경우, 전체 블리드 자식 (position:absolute; inset:0)에 채움을 넣으십시오. → composition-patterns.md

기존 컴포지션 편집

• 먼저 파일을 읽으십시오. 관련 없는 타이밍, 트랙, ID, 변수, 미디어 경로를 유지하십시오.
• 프로젝트의 타임라인에 무엇이 있는지 (트랙, 클립, 시작, 종료, 재생되는 항목) 알려면 npx hyperframes timeline [--json]을 실행하십시오. index.html 및 모든 하위 컴포지션 파일을 읽지 마십시오.
• 기존 컴포지션 ID 및 타임라인 키와 일치시키십시오.
• 클립 추가: data-start/data-duration을 주변 클립과 의도적으로 설정하십시오. data-track-index는 Studio 표시 레인이며 타이밍 제약이 아니므로 비어 있을 필요가 없습니다.
• 루트 data-duration을 지나 종료되는 클립은 잘립니다: 동일한 편집에서 루트 data-duration을 클립 종료까지 연장하십시오 (lint가 clip_ends_past_root_duration 경고).
• 컴포지션 요소의 data-hidden은 미리보기와 렌더링 모두에서 해당 요소를 숨기고, 시간 윈도우를 재정의합니다; 비파괴적/가역적이며 Studio 타임라인의 눈 아이콘으로 전환됩니다.
• 하위 컴포지션 추가: 호스트를 연결하기 전에 내부 data-composition-id를 확인하십시오.

검증

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

• npx hyperframes check 통과 (린트, 런타임, 레이아웃, 모션 및 대비에서 0개의 발견 사항)
• 하위 컴포지션이 있는 프로젝트: npx hyperframes snapshot --at <midpoints> 및 각 프레임 육안 확인
• 검토를 위한 npx hyperframes preview --background (사용자는 Studio의 타임라인에서 무엇이든 편집할 수 있으며, 서버는 호출 명령을 유지)
• 사용자 승인 후에만 npx hyperframes render