HyperFrames 레지스트리에 기여하기
사용자의 아이디어에서 병합된 PR까지 새 레지스트리 블록 또는 컴포넌트를 안내합니다.
워크플로우
1. 명확화 → 2. 구조 생성 → 3. 빌드 → 4. 검증 → 5. 미리보기 → 6. 배포
1단계: 명확화
사용자가 무엇을 만들고 있는지 물어보세요. 레지스트리에는 두 가지 항목 유형이 있습니다:
- 블록 (
registry/blocks/, 유형hyperframes:block) — 고정된 크기와 지속 시간을 가진 완전한 독립형 합성물입니다. 캡션 스타일, VFX 효과, 타이틀 카드, 하단 자막. - 컴포넌트 (
registry/components/, 유형hyperframes:component) — 고정된 크기나 지속 시간이 없는 재사용 가능한 스니펫입니다. 모든 합성물 크기에 적응하는 CSS 효과, 텍스트 처리, 오버레이.
그런 다음 물어보세요:
- 효과에 대한 한 문장 설명
- 시각적 참고 자료 (URL, 스크린샷, 또는 설명)
- 누가 언제 이것을 사용하나요?
2단계: 구조 생성
레지스트리 구조를 만듭니다:
블록의 경우:
registry/blocks/{블록-이름}/
{블록-이름}.html
registry-item.json
컴포넌트의 경우:
registry/components/{컴포넌트-이름}/
{컴포넌트-이름}.html
registry-item.json
명명 규칙:
| 항목 이름 | ID 접두사 | 예시 ID |
|---|---|---|
cap-hormozi | hz | hz-cg-0, hz-cw-3 |
cap-typewriter | tw | tw-cg-0, tw-ch-0-5 |
vfx-chrome | vc | vc-canvas |
2-3글자 접두사를 사용하세요. 모든 요소 ID는 하위 합성물에서 충돌을 방지하기 위해 이 접두사를 사용해야 합니다.
블록용 registry-item.json:
{
"$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
"name": "{블록-이름}",
"type": "hyperframes:block",
"title": "{사람이 읽을 수 있는 제목}",
"description": "{한 문장}",
"dimensions": { "width": 1920, "height": 1080 }, // 조정: 세로/소셜용 1080x1920
"duration": 10, // 합성물에 맞게 조정
"tags": ["{카테고리}", "{서브카테고리}"],
"files": [
{
"path": "{블록-이름}.html",
"target": "compositions/{블록-이름}.html",
"type": "hyperframes:composition"
}
]
}
컴포넌트용 registry-item.json (dimensions 또는 duration 없음):
{
"$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
"name": "{컴포넌트-이름}",
"type": "hyperframes:component",
"title": "{사람이 읽을 수 있는 제목}",
"description": "{한 문장}",
"tags": ["{카테고리}"],
"files": [
{
"path": "{컴포넌트-이름}.html",
"target": "compositions/components/{컴포넌트-이름}.html",
"type": "hyperframes:snippet"
}
]
}
3단계: 빌드
유형에 따라 올바른 템플릿을 적용하세요. 복사-붙여넣기 시작점은 templates.md를 참조하세요.
캡션 블록
절대적인 캡션 규칙:
- 글꼴: 비례 글꼴의 경우 최소 96px. 고정폭 글꼴의 경우 64-72px 허용 (더 넓은 문자는 크기가 덜 필요함).
- 가독성:
-webkit-text-stroke: 2-3px또는 다중 레이어text-shadow - 오버플로: 모든 그룹에서
window.__hyperframes.fitTextFontSize()호출 - 노래방:
tl.to(wordEl, { color/scale }, WORDS[wi].start)로 활성 단어 강조 - 하드 종료: 모든 그룹에서
tl.set(groupEl, { opacity: 0, visibility: "hidden" }, g.end) tl.set(el, { opacity: 1 })과 같은 위치에tl.from(el, { opacity: 0 })절대 사용 금지 — from이 set을 덮어씁니다. 대신tl.to를 사용하세요.
문자별 애니메이션 (타자기, 스크램블):
- 각 문자를 ID
{접두사}-ch-{그룹}-{문자}로<span>에 감쌉니다. - 단어 타임스탬프에서 계산된 간격으로
tl.set을 사용하여 순차 적용 - 커서/장식 요소: CSS 애니메이션이 아닌
tl.set을 간격으로 사용 (탐색 불가능)
위치 지정 변형:
- 중앙:
display: flex; align-items: center; justify-content: center; - 하단 자막:
position: absolute; bottom: 100px; left: 0; width: 100%; text-align: center; - 왼쪽 정렬:
position: absolute; bottom: 100px; left: 120px; text-align: left;
VFX 블록 (Three.js)
- CDN에서
[email protected]사용 (전역 스크립트) tl.eventCallback("onUpdate", renderScene); renderScene();— requestAnimationFrame 없음- 상태 프록시 패턴: GSAP이 일반 JS 객체를 애니메이션화하고, 렌더 함수가 이를 읽음
- 시드된 PRNG (
mulberry32)를 사용한 무작위성
모든 유형
data-composition-id는 반드시window.__timelines["id"]와 일치해야 함- 모든 요소 ID는 블록 약어로 접두사 사용
gsap.timeline({ paused: true })— 항상 일시 정지 상태Math.random(),Date.now()사용 금지
4단계: 검증
hyperframes lint # 오류 0 필요
hyperframes validate --no-contrast # 콘솔 오류 0 필요
5단계: 미리보기
# 미리보기 비디오 렌더링
hyperframes render -o preview.mp4
# 시각적 QA를 위한 스냅샷
hyperframes snapshot --at "1.0,3.0,5.0,7.0"
# 검토를 위해 hyperframes.dev에 게시
npx hyperframes publish
카탈로그 미리보기 이미지 — 카탈로그 카드는 docs/images/catalog/{종류}/{이름}.png의 PNG를 사용합니다 ({종류}는 blocks 또는 components). 스냅샷에서 생성한 후:
- HeyGen 내부 기여자:
scripts/upload-docs-images.sh실행 (AWS 프로필engineering-767398024897필요) - 외부 기여자: PR 설명에 미리보기 MP4를 첨부하세요. 병합 전에 관리자가 카탈로그 이미지를 생성하고 업로드합니다.
6단계: 배포
모든 단계가 필수입니다. 하나라도 빠지면 깨진 카탈로그 항목이 생성됩니다.
{종류}는 1단계에서 만든 항목에 따라 blocks 또는 components입니다.
# 1. 브랜치 생성
git checkout -b feat/registry-{이름}
# 2. HTML 포맷팅
npx oxfmt registry/{종류}/{이름}/*.html
# 3. registry/registry.json 업데이트 — "items" 배열에 항목 추가:
# { "name": "{이름}", "type": "hyperframes:block" } (또는 "hyperframes:component")
# 4. 카탈로그 문서 페이지 생성
npx tsx scripts/generate-catalog-pages.ts
# 5. 검토자가 미리볼 수 있도록 hyperframes.dev에 게시
npx hyperframes publish
# 6. 모든 파일 스테이징
git add registry/{종류}/{이름}/ registry/registry.json docs/catalog/
# 7. 커밋
git commit -m "feat(registry): add {이름} — {한 문장}"
# 8. 푸시 및 hyperframes.dev 링크와 함께 PR 열기
git push origin feat/registry-{이름}
gh pr create --title "feat(registry): {이름}" --body "preview: {hyperframes.dev-url}"
GitHub 계정이 없는 경우: PR을 열려면 계정이 필요합니다. https://github.com/signup에서 가입한 후 gh auth login을 실행하세요.
품질 게이트
-
hyperframes lint→ 오류 0 -
hyperframes validate→ 콘솔 오류 0 -
npx oxfmt --check통과 -
registry/registry.json에 새 항목이 업데이트됨 -
scripts/generate-catalog-pages.ts실행 (문서 페이지 생성됨) -
npx hyperframes publish실행 (프로젝트 URL 확보) - 미리보기 MP4가 PR에 첨부됨 (외부) 또는 카탈로그 PNG가 업로드됨 (내부)
- 모든 ID가 고유하고 접두사가 사용됨