hyperframes-keyframes

HyperFrames Keyframes

키프레임은 포즈 계약입니다: 보이는 상태, 연속적인 주체 정체성, 탐색-안전 런타임, 검증된 픽셀.

광범위한 장면 레시피는 hyperframes-animation을 사용하세요. 전체 명령어 문서는 hyperframes-cli를 사용하세요. 구현 메커니즘(시각적 스타일이 아님)을 선택할 때만 references/keyframe-patterns.md를 참조하세요.

제작자 편집 경계

키프레임은 시각적 움직임을 소유하며, 클립 조립은 소유하지 않습니다. 소스 범위 하드 컷, 트림, 스플라이스 및 재정렬은 /hyperframes-core에 속합니다: 유지된 범위당 하나의 미디어 요소를 작성하고 data-start와 data-duration으로 배치하며, data-media-start로 소스 오프셋을 선택합니다. 인접한 범위는 하드 컷을 만듭니다. 크로스페이드는 서로 다른 트랙에 중첩된 클립과 시각적 불투명도 키프레임을 사용합니다. 사운드 페이드는 /hyperframes-audio를 사용합니다.

제작자 요청	진실된 메커니즘
펀치-인 / 펀치-아웃	클립 내부의 비-시간적 시각적/크롭 래퍼에서 x/y 또는 백분율 변환을 사용한 키프레임 scale. 하드 펀치에는 set/short 트윈을, 부드러운 이동에는 트윈을 사용합니다.
부드러운 다중 상태 확대/재프레임	하나의 주체 래퍼를 유지하고 여러 확대/재프레임 상태를 세그먼트별 이징이 있는 포즈 사다리로 작성합니다.
팬, 재프레임 또는 켄 번스 카메라 이동	래퍼 변환 + 스케일을 애니메이션합니다. 지오메트리가 작성되며, 이는 얼굴 추적이나 자동 의미론적 재프레임이 아닙니다.
연결된 카메라 이동	하나의 등록된 탐색-안전 타임라인에 레이블이 지정된 변환 비트를 연결합니다.
매치 컷 또는 휩 팬	/hyperframes-animation이 시각적 핸드오프를 소유합니다. /hyperframes-registry가 프리미티브를 제공합니다. 키프레임은 작성된 지오메트리, 방향 및 속도를 보존합니다. 자동 매칭 프레임 발견은 없습니다.
크롭 및 마스크 재프레임	소스 시간을 변경하지 않고 크롭/재프레임하기 위해 내부 시각적 래퍼에서 clip-path 또는 마스크를 보간합니다. 폴리곤 키프레임은 폴리곤/마스크 전환을 형성할 수 있습니다.
방향성 와이프 컷 또는 아이리스/리빌 컷	중첩된 시각적 클립을 가로질러 마스크/클립 경계를 애니메이션합니다. /hyperframes-animation이 핸드오프 안무를 소유합니다.
분할 화면 핸드오프	코어가 배치한 두 시각적 클립을 모두 유지한 다음, 내부 크롭/마스크 래퍼와 분할자 지오메트리를 키프레임합니다.
일정한 소스 리타임	/hyperframes-core는 렌더-안전한 그림과 피치-보존된 사운드를 위해 정규화된 data-playback-rate (0.1..5)를 소유합니다. 전체 미디어 요소에 대해 일정합니다.
소스 속도 램프	지원되지 않음: 시간에 따라 변하는 재생 속도 봉투가 없습니다. 파생된 미디어 에셋을 전처리한 다음 코어를 통해 배치합니다.
프리즈 / 홀드	시각적 포즈, 최종 소스 프레임 또는 완성된 하위 합성이 유지될 수 있습니다. 임의의 중간 소스 프리즈는 지원되지 않습니다. 스틸/파생된 세그먼트를 전처리하여 자체 클립으로 배치한 다음 다른 소스 범위로 재개합니다.

그림과 사운드를 함께 편집할 때는 /hyperframes-core, 시각적 움직임을 위한 이 스킬, 그리고 배치된 트랙의 페이드, 크로스페이드, 볼륨 자동화, 덕킹/카브 또는 효과를 위한 /hyperframes-audio를 로드하세요.

시각적 전환 또는 크롭 처리는 시간적 소스 트림 또는 스플라이스가 아닙니다. /hyperframes-core가 타임라인, 클립 타이밍 및 소스 범위를 소유합니다. 키프레임은 해당 클립 내부의 래퍼에서 보이는 핸드오프 또는 크롭만 애니메이션합니다. 복사 가능한 결합 그림/사운드 레시피는 /hyperframes-core → references/creator-editing-recipes.md를 사용하세요.

절차

1. 애니메이션 주체, 보이는 상태, 최종 상태 및 런타임을 식별합니다.
2. 프롬프트를 증명하는 가장 작은 메커니즘을 선택합니다. 메커니즘이 명확하지 않은 경우에만 references/keyframe-patterns.md를 읽습니다.
3. 선언된 런타임에서 탐색-안전 키프레임을 작성합니다. 동기적으로 빌드하고 런타임 인스턴스를 등록합니다.
4. hyperframes lint, hyperframes check, hyperframes keyframes, 하나의 집중된 --shot 및 증명 시간의 스냅샷으로 검증합니다.
5. 증명이 실패하면 소스 키프레임을 수정하고 렌더링 전에 가장 작은 실패 진단을 다시 실행합니다.

계약

• 움직이는 주체의 이름을 지정합니다.
• 의도된 움직임을 증명하는 데 필요한 포즈(최종 상태 포함)의 이름을 지정합니다.
• 숨겨진 도우미 상태가 아닌 보이는 채널을 키프레임합니다.
• 연속성이 중요할 때 객체 정체성을 유지합니다.
• 의도된 움직임이 대체 또는 용해인 경우에만 크로스페이드합니다.
• 읽을 수 있거나 의미론적 상태를 볼 수 있을 만큼 충분히 오래 유지합니다.
• 최종 프레임은 애니메이션의 일부이며, 정리가 아닙니다.
• 요청하지 않는 한 휴식 상태로 재설정하지 마십시오.
• 요청하지 않는 한 검은색으로 끝내지 마십시오.
• 스타터 장면을 편집하는 경우, 재설계를 요청하지 않는 한 레이아웃, 사본, 에셋, 색상 및 최종 상태를 유지합니다.

런타임 규칙

GSAP:

• 페이지 로드 시 동기적으로 빌드합니다.
• gsap.timeline({ paused: true })를 사용합니다.
• window.__timelines[compositionId]로 등록합니다.
• 레지스트리 키는 data-composition-id와 일치해야 합니다.
• 렌더-중요한 움직임에 tl.play()를 호출하지 마십시오.
• 반복을 유한하게 유지합니다.

CSS 키프레임:

• 유한한 지속 시간과 반복 횟수.
• 결정론적 지연.
• animation-fill-mode: both.
• 타이밍이 클립에 속할 때 data-start를 사용합니다.

Anime.js:

• 동기적으로 생성합니다.
• autoplay: false.
• 유한한 지속 시간과 루프.
• 모든 인스턴스를 window.__hfAnime에 푸시합니다.

WAAPI:

• 유한한 duration.
• fill: "both".
• 결정론적 구성.
• 텍스트 표면은 WAAPI를 나열하지 않습니다. --shot(WAAPI를 탐색함) 및 스냅샷으로 검증합니다.

렌더-중요한 움직임에 절대 사용하지 마십시오:

• Date.now()
• performance.now()
• 시드되지 않은 Math.random()
• 호버/스크롤 트리거
• 타이머
• 비동기적으로 생성된 타임라인
• 등록되지 않은 requestAnimationFrame
• 무한 루프

GSAP 스켈레톤

const root = document.querySelector("[data-composition-id]");
const compositionId = root.dataset.compositionId;
const tl = gsap.timeline({ paused: true });

tl.addLabel("state-a", 0);
tl.to(".subject", {
  keyframes: [
    { x: 0, opacity: 1, duration: 0.2 },
    { x: 120, opacity: 1, duration: 0.4, ease: "power2.out" },
    { x: 100, opacity: 1, duration: 0.2, ease: "power2.inOut" },
  ],
  ease: "none",
});

window.__timelines = window.__timelines || {};
window.__timelines[compositionId] = tl;

의미론적 상태에 레이블을 사용합니다. 연결된 지연 대신 위치 매개변수를 사용합니다. 동일한 속성을 건드리는 나중 from()/fromTo() 트윈에 대해 immediateRender: false를 사용합니다.

키프레임 형식

• 배열 키프레임: 단계별 지속 시간/이징이 있는 포즈 사다리.
• 백분율 키프레임: 하나의 트윈 내 정확한 타이밍.
• 속성 배열: 간결한 다중 중단 변경.
• 각 중단이 자체 이징을 전달할 때 부모에 ease: "none".
• 모든 세그먼트가 동일한 느낌을 공유해야 할 때 easeEach.

예제에서 숫자 거리나 타이밍을 복사하지 마십시오. 실제 컴포지션 지오메트리와 지속 시간에서 파생하십시오.

두 상자 사이를 이동하는 하나의 주체에 대해 하나의 연속적인 변환 트윈 또는 FLIP을 선호합니다. 시청자가 별개의 비트를 느껴야 하는 경우에만 x/y/scale을 여러 개의 이즈드 키프레임으로 분할하십시오. 모든 세그먼트는 속도를 변경하며 걸림으로 읽힐 수 있습니다.

채널

합성기/시각적 채널을 선호합니다: x/y/z, xPercent/yPercent, scale, rotationX/Y/Z, skew, transformOrigin, svgOrigin, opacity, autoAlpha, clip-path, 마스크, CSS 변수, SVG 경로/대시 값, 카메라 변환, 셰이더 유니폼.

레이아웃/생명주기 채널을 피하십시오: top/left/right/bottom, width/height, margin/padding, display, visibility, 늦은 DOM 생성, 주체 움직임을 수행하는 도우미 오버레이.

가시성 변경을 위해 등록된 탐색 가능한 GSAP 타임라인에서 autoAlpha를 사용하거나 명시적 경계에서 0-지속 시간 tl.set()을 사용합니다. 클립이 아닌 요소 또는 클립 내부의 래퍼만 대상으로 하고 절대 .clip 자체를 대상으로 하지 마십시오. 절대 지속 시간으로 원시 visibility를 트윈하지 말고 display를 트윈하지 마십시오.

메커니즘 선택

프롬프트를 증명하는 가장 작은 메커니즘을 선택하십시오:

필요	메커니즘
동일한 주체가 상자 또는 계층 구조 변경	공유 요소 / FLIP
주체가 보이는 경로를 이동	경로 이동
획이 성장하거나 추적	획 그리기
한 모양이 다른 모양으로 변경	모양 보간
경계 드러내기가 보임	클립, 마스크 또는 셰이더 유니폼
많은 항목이 순서대로 이동	스태거 / 인덱스된 지연
텍스트 자체가 이동	라인, 단어, 문자 또는 밴드 세분화
표면이 구부러지거나 늘어나거나 크롭	부모/자식 카운터-변환
UI에 상태가 있음	명시적 상태 머신
장면에 깊이가 있음	DOM 3D, Three.js 또는 WebGL 카메라/객체 키프레임

메커니즘은 결합될 수 있지만 각각은 아이디어를 명확히 해야 합니다. 장식은 증명이 아닙니다.

타이밍

• 기대는 원인이나 방향을 명확히 할 때만.
• 가속은 휴식을 떠납니다.
• 피크 증명은 메커니즘을 명백히 보여줍니다.
• 후속 동작은 에너지와 방향을 판매합니다.
• 오버슈트는 주체가 탄력적이거나 촉각적으로 느껴져야 할 때만.
• 일정한 속도의 경로 이동은 일반적으로 ease: "none"이 필요합니다.
• 이산적인 UI 상태는 일반적으로 날카로운 이즈-아웃이 필요합니다.
• 반복되는 요소는 동일한 타이밍이 아닌 정렬된 오프셋이 필요합니다.
• 최종 잠금은 전환 포즈보다 더 긴 유지가 필요합니다.
• 부드러움은 동일한 주체에 대한 연속적인 속도를 의미합니다.
• 의도적이고 검증되지 않는 한 동일한 변환 속성을 쓰는 트윈을 겹치지 마십시오.
• 동일한 히어로 표면이 동시에 확장/이동하는 동안 큰 clip-path/마스크 변경을 애니메이션하지 마십시오. 주요 이동이 완료된 후 중첩된 드러내기를 사용하십시오.

텍스트

라인 박스, 단어 간격, 가독성 및 최종 맞춤을 유지합니다. 텍스트가 내부적으로 이동하는 경우, 텍스트 주변의 장식만이 아니라 글리프 또는 마스킹된 밴드를 이동합니다. 읽을 수 있는 프레임을 스냅샷합니다.

SVG

획 성장에는 DrawSVGPlugin을 선호하고, 그 다음으로 stroke-dasharray/stroke-dashoffset을 선호합니다. 모양 보간에는 MorphSVGPlugin을 선호합니다. 필요한 경우 프리미티브를 경로로 변환하고 복잡한 실루엣을 더 간단한 부분으로 분할합니다.

3D

스케일만으로는 가짜 깊이입니다. 안정적인 부모에 원근법, transform-style: preserve-3d, z 이동, 회전, 카메라/월드 움직임, 폐색 및 객체가 교차할 때 레이어 순서를 사용합니다.

깊이 관계를 노출하는 하나 또는 두 개의 진단 각도를 사용합니다. 각도 증명이 깊이 교차를 보여주지 않으면 z/카메라/폐색을 개선합니다.

캔버스 / WebGL

키프레임 카메라 위치, 카메라 대상, 객체 변환, 재료 불투명도, 셰이더 유니폼 및 결정론적 상태를 통한 후처리 강도. HyperFrames 시간에서 렌더링합니다. 마커 상자가 내부 캔버스 움직임을 볼 수 없기 때문에 --ghost를 사용합니다.

CLI 증명

npx hyperframes lint
npx hyperframes check
npx hyperframes keyframes .
npx hyperframes keyframes . --json
npx hyperframes keyframes . --runtime all
npx hyperframes keyframes . --selector "<selector>" --shot "<file>" --samples <n>
npx hyperframes keyframes . --selector "<selector>" --shot "<file>" --layout strip --from <t0> --to <t1>
npx hyperframes keyframes . --shot "<file>" --ghost --angle <angle>
npx hyperframes snapshot . --at <times>

실제 애니메이션 주체에 대해 <selector>를 선택합니다. 첫 번째 프레임, 증명 포즈, 최종-마이너스-유지 및 정확한 최종에 대해 <times>를 선택합니다. 깊이를 증명해야 할 때만 <angle>을 선택합니다.

도구	증명
keyframes	대상, 명시적 중단점, 경로, 추적, 구성된 부모/자식 움직임, CSS 중단점, Anime 등록
--shot	고스트, 경로 모양, 시간 간격, DOM 3D 투영, 집중된 선택자 증명
--layout strip	제자리 움직임, 겹침, 접촉, 미묘한 스케일/불투명도, 텍스트 웨이브
--ghost	캔버스, WebGL, 셰이더 움직임, 렌더링된 3D
snapshot --at	마스크, 텍스트 가독성, 전체 상태, 최종 잠금, 검은색/재설정 테일

선택자 증명이 잘못된 경우:

1. --json을 다시 실행합니다.
2. 실제 애니메이션 대상을 찾습니다.
3. 해당 대상을 촬영합니다.
4. 전체 프레임을 스냅샷합니다.
5. 로그보다 칠해진 픽셀을 신뢰합니다.

진단 읽기

flat은 명시적인 중간 포즈가 없음을 의미합니다. keyframes는 명시적인 중단점이 존재함을 의미합니다. m

…

[번역을 위해 잘림]