reelkit-cli 0.8.0 → 0.10.2

package/src/hyperframes/frame.tsx

@@ -0,0 +1,46 @@
+import React, { createContext, useContext, useId } from "react";
+export * from "./math";
+export type VideoConfig = { width: number; height: number; fps: number; durationInFrames: number; id?: string };
+export type FrameState = { frame: number; offset: number; duration: number; config: VideoConfig; loop?: number; collecting?: boolean };
+export const FrameContext = createContext<FrameState>({ frame: 0, offset: 0, duration: 1, config: { width: 1080, height: 1920, fps: 30, durationInFrames: 1 } });
+export const useCurrentFrame = () => useContext(FrameContext).frame;
+export const useVideoConfig = () => { const s = useContext(FrameContext); return { ...s.config, durationInFrames: s.duration }; };
+export const AbsoluteFill = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(({ style, ...props }, ref) => <div ref={ref} {...props} style={{ position: "absolute", inset: 0, display: "flex", flexDirection: "column", ...style }} />);
+export const Img = React.forwardRef<HTMLImageElement, React.ImgHTMLAttributes<HTMLImageElement>>((props, ref) => <img {...props} ref={ref} />);
+export const Sequence: React.FC<{ from?: number; durationInFrames?: number; layout?: "none" | "absolute-fill"; children?: React.ReactNode; name?: string; style?: React.CSSProperties; premountFor?: number }> = ({ from = 0, durationInFrames, layout, children, style }) => {
+  const s = useContext(FrameContext), duration = Math.min(durationInFrames ?? s.duration - from, s.duration - from);
+  if (!s.collecting && (s.frame < from || s.frame >= from + duration)) return null;
+  const content = <FrameContext.Provider value={{ ...s, frame: s.frame - from, offset: s.offset + from, duration }}>{children}</FrameContext.Provider>;
+  return layout === "none" ? content : <AbsoluteFill style={style}>{content}</AbsoluteFill>;
+};
+export const Freeze: React.FC<{ frame: number; children?: React.ReactNode }> = ({ frame, children }) => { const s = useContext(FrameContext); return <FrameContext.Provider value={{ ...s, frame }}>{children}</FrameContext.Provider>; };
+export const Loop: React.FC<{ durationInFrames: number; children?: React.ReactNode; times?: number; layout?: "none" | "absolute-fill" }> = ({ durationInFrames, children }) => {
+  const s = useContext(FrameContext); return <FrameContext.Provider value={{ ...s, frame: ((s.frame % durationInFrames) + durationInFrames) % durationInFrames, loop: durationInFrames }}>{children}</FrameContext.Provider>;
+};
+export type AudioRecord = { id: string; src: string; start: number; end: number; mediaStart: number; layer: number; volume: number; volumeKeyframes: { time: number; volume: number }[]; type: "audio" | "video"; loop: boolean };
+export const audioRecords = new Map<string, AudioRecord>();
+type MediaProps = { src: string; volume?: number | ((frame: number) => number); startFrom?: number; endAt?: number; trimBefore?: number; trimAfter?: number; playbackRate?: number; loopVolumeCurveBehavior?: "extend" | "repeat" };
+function recordAudio(id: string, props: MediaProps & { loop?: boolean }, type: "audio" | "video", state: FrameState) {
+  const { config: { fps } } = state;
+  const volume = typeof props.volume === "function" ? props.volume(state.frame) : props.volume ?? 1;
+  const start = state.offset / fps, end = Math.min(state.config.durationInFrames, state.offset + state.duration) / fps;
+  let record = audioRecords.get(id);
+  if (!record) { record = { id, src: props.src, start, end, mediaStart: (props.trimBefore ?? props.startFrom ?? 0) / fps, layer: audioRecords.size, volume, volumeKeyframes: [], type, loop: props.loop ?? false }; audioRecords.set(id, record); }
+  const time = (state.frame + state.offset) / fps;
+  if (time >= start && time < end && typeof props.volume === "function") record.volumeKeyframes.push({ time, volume });
+}
+export const Audio: React.FC<MediaProps & { loop?: boolean }> = (props) => {
+  const s = useContext(FrameContext), id = useId(); recordAudio(id, props, "audio", s);
+  return <audio id={`hf-audio-${id.replace(/[^a-z0-9]/gi, "")}`} src={props.src} preload="none" data-start={s.offset / s.config.fps} data-duration={s.duration / s.config.fps} />;
+};
+export const OffthreadVideo: React.FC<Omit<React.VideoHTMLAttributes<HTMLVideoElement>, "volume"> & MediaProps & { transparent?: boolean; pauseWhenBuffering?: boolean }> = ({ volume, startFrom, endAt, trimBefore, trimAfter, transparent, pauseWhenBuffering, playbackRate = 1, ...props }) => {
+  const s = useContext(FrameContext), id = useId();
+  if (!props.muted) recordAudio(id, { ...props, src: props.src!, volume, startFrom, trimBefore }, "video", s);
+  return <video {...props} muted playsInline preload="auto" data-hf-frame-video="true" data-hf-time={Math.max(0, s.frame / s.config.fps * playbackRate + (trimBefore ?? startFrom ?? 0) / s.config.fps)} data-hf-loop={props.loop || s.loop ? "true" : undefined} />;
+};
+export const Video = OffthreadVideo;
+let nextHandle = 0;
+const pending = new Map<number, { promise: Promise<void>; resolve: () => void }>();
+export function delayRender(_label?: string): number { const id = ++nextHandle; let resolve!: () => void; const promise = new Promise<void>((r) => { resolve = r; }); pending.set(id, { promise, resolve }); return id; }
+export function continueRender(handle: number): void { pending.get(handle)?.resolve(); pending.delete(handle); }
+export async function waitForRender(): Promise<void> { while (pending.size) await Promise.all([...pending.values()].map((p) => p.promise)); }

package/src/hyperframes/host.tsx

@@ -0,0 +1,38 @@
+import React from "react";
+import type { HfProtocol } from "@hyperframes/engine";
+import { createRoot } from "react-dom/client";
+import { flushSync } from "react-dom";
+import { audioRecords, FrameContext, waitForRender } from "./frame";
+import { ManifestContext, UrlsContext } from "./kit/media";
+import type { VideoProps } from "./types";
+
+declare global { interface Window { __reelkitProps: VideoProps; __reelkitReady: Promise<void>; __reelkitAudio: typeof audioRecords; __hf?: HfProtocol; } }
+async function settleMedia() {
+  await waitForRender();
+  await document.fonts.ready;
+  await Promise.all([...document.images].map(async (img) => { if (!img.complete) await new Promise<void>((resolve, reject) => { img.addEventListener("load", () => resolve(), { once: true }); img.addEventListener("error", () => reject(new Error(`Image failed: ${img.src}`)), { once: true }); }); if (img.naturalWidth === 0) throw new Error(`Image failed: ${img.src}`); await img.decode(); }));
+  await Promise.all([...document.querySelectorAll<HTMLVideoElement>("video[data-hf-frame-video]")].map(async (video) => {
+    if (video.readyState < 1) await new Promise<void>((resolve, reject) => { video.addEventListener("loadedmetadata", () => resolve(), { once: true }); video.addEventListener("error", () => reject(new Error(`Video failed: ${video.src}`)), { once: true }); });
+    const time = Number(video.dataset.hfTime), duration = video.duration;
+    const target = video.dataset.hfLoop ? time % duration : Math.min(time, Math.max(0, duration - 0.00001));
+    if (video.readyState < 2 || Math.abs(video.currentTime - target) > 0.00001) await new Promise<void>((resolve, reject) => { video.addEventListener("seeked", () => resolve(), { once: true }); video.addEventListener("error", () => reject(new Error(`Video seek failed: ${video.src}`)), { once: true }); video.currentTime = target; });
+    video.pause();
+  }));
+  await new Promise<void>((resolve) => requestAnimationFrame(() => requestAnimationFrame(() => resolve())));
+}
+export function mountVideo(Video: React.ComponentType<VideoProps>, previewProps?: VideoProps) {
+  const props = previewProps ?? window.__reelkitProps, m = props.manifest;
+  const stage = document.getElementById("stage")!;
+  stage.style.width = `${m.width}px`; stage.style.height = `${m.height}px`;
+  stage.dataset.compositionId = "Video"; stage.dataset.noTimeline = "true"; stage.dataset.duration = String(m.totalFrames / m.fps);
+  stage.dataset.width = String(m.width); stage.dataset.height = String(m.height);
+  const root = createRoot(stage);
+  window.__reelkitAudio = audioRecords;
+  const seek = (time: number) => {
+    const frame = Math.min(m.totalFrames - 1, Math.max(0, Math.round(time * m.fps)));
+    flushSync(() => root.render(<FrameContext.Provider value={{ frame, offset: 0, duration: m.totalFrames, config: { width: m.width, height: m.height, fps: m.fps, durationInFrames: m.totalFrames } }}><UrlsContext.Provider value={props.urls}><ManifestContext.Provider value={m}><Video {...props} /></ManifestContext.Provider></UrlsContext.Provider></FrameContext.Provider>));
+    window.__reelkitReady = settleMedia();
+  };
+  window.__hf = { duration: m.totalFrames / m.fps, seek };
+  seek(0);
+}

package/src/{remotion → hyperframes}/kit/Assemble3D.tsx

@@ -1,5 +1,5 @@
 import React from "react";
-import { useCurrentFrame, useVideoConfig } from "remotion";
+import { useCurrentFrame, useVideoConfig } from "../frame";
 import { Color, Object3D, type InstancedMesh } from "three";
 import { CameraKeysContext } from "./scene3d-context";
 import { hash01 } from "./seeded";

package/src/hyperframes/kit/BrandTransform3D.tsx

@@ -0,0 +1,12 @@
+import React from "react";
+import { useCurrentFrame, useVideoConfig } from "../frame";
+import { brandTransformAt, type BrandTransform, type BrandTransformTiming } from "./brand-transform";
+
+// A branded object turning into view, arriving on an arc, or launching from depth. Use inside Scene3D around a Card3D, Hero3D or Text3D.
+// The final pose holds exactly: the real logo or product can be read without a continuous spin. Sound stays outside Scene3D; brandTransformFrames gives its landing frame.
+export const BrandTransform3D: React.FC<BrandTransformTiming & { mode?: BrandTransform; strength?: number; children?: React.ReactNode }> = ({ children, ...options }) => {
+  const frame = useCurrentFrame(), { fps } = useVideoConfig();
+  const pose = brandTransformAt(frame, fps, options);
+  if (!pose.visible) return null;
+  return <group position={pose.position} rotation={pose.rotation} scale={pose.scale}>{children}</group>;
+};

package/src/{remotion → hyperframes}/kit/BrowserFrame.tsx

@@ -1,5 +1,5 @@
 import React from "react";
-import { continueRender, delayRender, interpolate, spring, useCurrentFrame, useVideoConfig } from "remotion";
+import { continueRender, delayRender, interpolate, spring, useCurrentFrame, useVideoConfig } from "../frame";
 import { Place } from "./Place";
 import { useMedia } from "./media";
 import { fonts } from "./theme";

package/src/{remotion → hyperframes}/kit/Camera.tsx

@@ -1,5 +1,5 @@
 import React from "react";
-import { AbsoluteFill, useCurrentFrame, useVideoConfig } from "remotion";
+import { AbsoluteFill, useCurrentFrame, useVideoConfig } from "../frame";
 import { applyPunches, cameraAt, cameraTransform, type CameraKey, type Punch } from "./motion-math";
 
 // Moves the whole picture. Wrap all the scenes in it for one camera that never cuts, or wrap one scene's content.

package/src/{remotion → hyperframes}/kit/Captions.tsx

@@ -1,5 +1,5 @@
 import React from "react";
-import { AbsoluteFill, interpolate, spring, useCurrentFrame, useVideoConfig } from "remotion";
+import { AbsoluteFill, interpolate, spring, useCurrentFrame, useVideoConfig } from "../frame";
 import type { WordTiming } from "../../pipeline/schema";
 import { captionGroups, DEFAULT_GROUP_WORDS, groupAt, type CaptionGroup } from "./caption-groups";
 import { inkOnAccent, legibleAccent, PLATE_COLOR } from "./caption-style";

package/src/{remotion → hyperframes}/kit/Card3D.tsx

@@ -1,8 +1,8 @@
 import React from "react";
-import { useCurrentFrame, useVideoConfig } from "remotion";
+import { useCurrentFrame, useVideoConfig } from "../frame";
 import { useLoader } from "@react-three/fiber";
 import { CanvasTexture, FrontSide, Shape, ShapeGeometry, SRGBColorSpace, TextureLoader, type Texture } from "three";
-import { delayRender, continueRender } from "remotion";
+import { delayRender, continueRender } from "../frame";
 import { useMedia } from "./media";
 import { fonts } from "./theme";
 import { degToRad, floatAt, inkOn, mixHex, type Vec3 } from "./three-math";

package/src/{remotion → hyperframes}/kit/Carry.tsx

@@ -1,5 +1,5 @@
 import React from "react";
-import { useCurrentFrame, useVideoConfig } from "remotion";
+import { useCurrentFrame, useVideoConfig } from "../frame";
 import { boxAt, type Box, type BoxKey } from "./motion-math";
 
 // What a function child is given: the box now, as fractions of the frame, and its size in pixels.

package/src/{remotion → hyperframes}/kit/ChapterFrame.tsx

@@ -1,5 +1,5 @@
 import React from "react";
-import { AbsoluteFill, interpolate, spring, useCurrentFrame, useVideoConfig } from "remotion";
+import { AbsoluteFill, interpolate, spring, useCurrentFrame, useVideoConfig } from "../frame";
 import { font as loadFont, fonts, springs } from "./theme";
 import { inkOn, mixHex } from "./three-math";
 import { chapterFrames, clamp01 } from "./ui-math";

package/src/{remotion → hyperframes}/kit/ClipLayer.tsx

@@ -1,6 +1,6 @@
 import React from "react";
 import { useMedia } from "./media";
-import { AbsoluteFill, OffthreadVideo } from "remotion";
+import { AbsoluteFill, OffthreadVideo } from "../frame";
 
 // A generated or library video clip as a scene's picture. Place it inside the scene's SceneFrame, as the bottom layer, so it starts with the scene.
 // When the scene runs longer than the clip, the clip holds its last frame (it does not loop: a looped person or animal jumps back and shows the seam).

package/src/{remotion → hyperframes}/kit/Counter.tsx

@@ -1,6 +1,6 @@
 import React from "react";
 import { fonts } from "./theme";
-import { AbsoluteFill, interpolate, useCurrentFrame, useVideoConfig } from "remotion";
+import { AbsoluteFill, interpolate, useCurrentFrame, useVideoConfig } from "../frame";
 
 export const Counter: React.FC<{ from?: number; to: number; durationFrames?: number; prefix?: string; suffix?: string; color?: string }> = ({
   from = 0, to, durationFrames = 30, prefix = "", suffix = "", color = "#ffffff",

package/src/{remotion → hyperframes}/kit/CounterRoll.tsx

@@ -1,5 +1,5 @@
 import React from "react";
-import { interpolate, useCurrentFrame, useVideoConfig } from "remotion";
+import { interpolate, useCurrentFrame, useVideoConfig } from "../frame";
 import { Place } from "./Place";
 import { fonts } from "./theme";
 import { DEFAULT_HERO } from "./ui-theme";

package/src/{remotion → hyperframes}/kit/Entrance.tsx

@@ -1,5 +1,5 @@
 import React from "react";
-import { interpolate, spring, useCurrentFrame, useVideoConfig } from "remotion";
+import { interpolate, spring, useCurrentFrame, useVideoConfig } from "../frame";
 import { ease, springs } from "./theme";
 
 // The workhorse entrance: fade + rise + scale together, with an optional faster exit and a slow idle "breathe".

package/src/{remotion → hyperframes}/kit/FootageLayer.tsx

@@ -1,6 +1,6 @@
 import React from "react";
 import { useMedia } from "./media";
-import { AbsoluteFill, OffthreadVideo } from "remotion";
+import { AbsoluteFill, OffthreadVideo } from "../frame";
 
 export const FootageLayer: React.FC<{ src: string; muted?: boolean; dim?: number }> = ({ src, muted = true, dim = 0 }) => (
   <AbsoluteFill>

package/src/{remotion → hyperframes}/kit/GlassPanel.tsx

@@ -1,5 +1,5 @@
 import React from "react";
-import { spring, useCurrentFrame, useVideoConfig } from "remotion";
+import { spring, useCurrentFrame, useVideoConfig } from "../frame";
 import { Place } from "./Place";
 import { DEFAULT_HERO, rgba, uiColors, type UiTheme } from "./ui-theme";
 import { PANEL_SPRING } from "./ui-math";

package/src/{remotion → hyperframes}/kit/Grounds.tsx

@@ -1,5 +1,5 @@
 import React from "react";
-import { AbsoluteFill, Img, OffthreadVideo, Sequence, useCurrentFrame, useVideoConfig } from "remotion";
+import { AbsoluteFill, Img, OffthreadVideo, Sequence, useCurrentFrame, useVideoConfig } from "../frame";
 import { auroraBlobs, beamStates, breath, checkItems, grainSeed, gridOffset, gridRows, groundStrength, hueShift, mixHex, plateView, withAlpha, sequenceLayers, videoLayers, type Drift, type SequenceItem, type SequenceTransition } from "./bg-math";
 import { useMedia } from "./media";
 

package/src/{remotion → hyperframes}/kit/Headline.tsx

@@ -1,5 +1,5 @@
 import React from "react";
-import { continueRender, delayRender, spring, useCurrentFrame, useVideoConfig } from "remotion";
+import { continueRender, delayRender, spring, useCurrentFrame, useVideoConfig } from "../frame";
 import { Place } from "./Place";
 import { fonts, springs } from "./theme";
 import { inkOn } from "./three-math";

package/src/{remotion → hyperframes}/kit/Hero3D.tsx

@@ -1,5 +1,5 @@
 import React from "react";
-import { continueRender, delayRender, useCurrentFrame, useVideoConfig } from "remotion";
+import { continueRender, delayRender, useCurrentFrame, useVideoConfig } from "../frame";
 import { useThree } from "@react-three/fiber";
 import { CanvasTexture, DoubleSide, ExtrudeGeometry, Shape, ShapeGeometry, SRGBColorSpace, TextureLoader, type BufferGeometry, type Texture } from "three";
 import { RoundedBoxGeometry } from "three/examples/jsm/geometries/RoundedBoxGeometry.js";

package/src/{remotion → hyperframes}/kit/HudOverlay.tsx

@@ -1,5 +1,5 @@
 import React from "react";
-import { AbsoluteFill, useCurrentFrame, useVideoConfig } from "remotion";
+import { AbsoluteFill, useCurrentFrame, useVideoConfig } from "../frame";
 import { font as loadFont } from "./theme";
 import { rgba } from "./ui-theme";
 import { timecode } from "./ui-math";

package/src/{remotion → hyperframes}/kit/ImageLayers.tsx

@@ -1,5 +1,5 @@
 import React from "react";
-import { AbsoluteFill, useCurrentFrame, useVideoConfig } from "remotion";
+import { AbsoluteFill, useCurrentFrame, useVideoConfig } from "../frame";
 import { useMedia } from "./media";
 import { layerMoves, type ImageLayersRecord } from "./image-layers-math";
 

package/src/{remotion → hyperframes}/kit/KenBurnsImage.tsx

@@ -1,7 +1,7 @@
 import React from "react";
 import { useMedia } from "./media";
 import { ease } from "./theme";
-import { AbsoluteFill, Img, interpolate, useCurrentFrame, useVideoConfig } from "remotion";
+import { AbsoluteFill, Img, interpolate, useCurrentFrame, useVideoConfig } from "../frame";
 
 // direction "out" starts zoomed and pulls back; alternate between consecutive image scenes.
 export const KenBurnsImage: React.FC<{ src: string; zoom?: number; direction?: "in" | "out" }> = ({ src, zoom = 1.1, direction = "in" }) => {

package/src/{remotion → hyperframes}/kit/KeyedClip.tsx

@@ -1,6 +1,6 @@
 import React from "react";
 import { useMedia } from "./media";
-import { AbsoluteFill, OffthreadVideo } from "remotion";
+import { AbsoluteFill, OffthreadVideo } from "../frame";
 
 // A green-screen clip with its green keyed out (the transparent .webm that `--green` makes), laid over whatever is beneath it.
 // x and y are where the clip's bottom-centre sits, as fractions of the frame (x 0 is the left edge, y 1 the bottom edge); scale is the clip's

package/src/{remotion → hyperframes}/kit/Layers.tsx

@@ -1,5 +1,5 @@
 import React from "react";
-import { AbsoluteFill, useCurrentFrame, useVideoConfig } from "remotion";
+import { AbsoluteFill, useCurrentFrame, useVideoConfig } from "../frame";
 
 // The bottom layer of every scene: the base colour with two slow-drifting soft colour fields. Never a flat fill.
 export const BgMesh: React.FC<{ bg: string; hero: string; accent?: string }> = ({ bg, hero, accent = hero }) => {

package/src/{remotion → hyperframes}/kit/LowerThird.tsx

@@ -1,6 +1,6 @@
 import React from "react";
 import { fonts } from "./theme";
-import { AbsoluteFill, spring, useCurrentFrame, useVideoConfig } from "remotion";
+import { AbsoluteFill, spring, useCurrentFrame, useVideoConfig } from "../frame";
 
 export const LowerThird: React.FC<{ title: string; subtitle?: string; accent?: string }> = ({ title, subtitle, accent = "#5b8cff" }) => {
   const frame = useCurrentFrame();

package/src/{remotion → hyperframes}/kit/Music.tsx

@@ -1,5 +1,5 @@
 import React from "react";
-import { Audio, useVideoConfig } from "remotion";
+import { Audio, useVideoConfig } from "../frame";
 import { DEFAULT_DUCK_TO, DEFAULT_MUSIC_VOLUME, musicVolume, speechSpans, type MusicDip, type SpeechScene } from "./music-math";
 import { useGain, useManifest, useMedia } from "./media";
 

package/src/{remotion → hyperframes}/kit/NamedCursor.tsx

@@ -1,5 +1,5 @@
 import React from "react";
-import { AbsoluteFill, interpolate, useCurrentFrame, useVideoConfig } from "remotion";
+import { AbsoluteFill, interpolate, useCurrentFrame, useVideoConfig } from "../frame";
 import { fonts } from "./theme";
 import { inkOn } from "./three-math";
 import { DEFAULT_HERO, rgba } from "./ui-theme";

package/src/{remotion → hyperframes}/kit/Orbit3D.tsx

@@ -1,5 +1,5 @@
 import React from "react";
-import { useCurrentFrame, useVideoConfig } from "remotion";
+import { useCurrentFrame, useVideoConfig } from "../frame";
 import { CameraKeysContext } from "./scene3d-context";
 import { naturalRingRadius, ringFitScale, ringPosition, type Vec3 } from "./three-math";
 

package/src/{remotion → hyperframes}/kit/Particles3D.tsx

@@ -1,5 +1,5 @@
 import React from "react";
-import { useCurrentFrame, useVideoConfig } from "remotion";
+import { useCurrentFrame, useVideoConfig } from "../frame";
 import { AdditiveBlending, BufferAttribute, CanvasTexture, Color, SRGBColorSpace } from "three";
 import { CameraKeysContext } from "./scene3d-context";
 import { textPoints } from "./sample-text";

package/src/{remotion → hyperframes}/kit/Place.tsx

@@ -1,5 +1,5 @@
 import React from "react";
-import { AbsoluteFill, useVideoConfig } from "remotion";
+import { AbsoluteFill, useVideoConfig } from "../frame";
 
 // Centres a product-surface component in the frame, at fraction `y` of the height (0.5 is the middle). Used inside the components themselves.
 export const Place: React.FC<{ y?: number; children: React.ReactNode }> = ({ y = 0.5, children }) => {

package/src/{remotion → hyperframes}/kit/PromptBox.tsx

@@ -1,5 +1,5 @@
 import React from "react";
-import { interpolate, spring, useCurrentFrame, useVideoConfig } from "remotion";
+import { interpolate, spring, useCurrentFrame, useVideoConfig } from "../frame";
 import { Place } from "./Place";
 import { fonts, springs } from "./theme";
 import { DEFAULT_HERO, rgba, uiColors, type UiTheme } from "./ui-theme";

package/src/{remotion → hyperframes}/kit/Scene3D.tsx

@@ -1,6 +1,6 @@
 import React from "react";
-import { useCurrentFrame, useVideoConfig } from "remotion";
-import { ThreeCanvas } from "@remotion/three";
+import { useCurrentFrame, useVideoConfig } from "../frame";
+import { ThreeCanvas } from "../three";
 import { useThree } from "@react-three/fiber";
 import { ManifestContext, UrlsContext } from "./media";
 import { camera3DAt, type Camera3DKey } from "./three-math";

package/src/{remotion → hyperframes}/kit/SceneFrame.tsx

@@ -1,5 +1,5 @@
 import React from "react";
-import { AbsoluteFill, Sequence, useCurrentFrame, useVideoConfig } from "remotion";
+import { AbsoluteFill, Sequence, useCurrentFrame, useVideoConfig } from "../frame";
 import { transitionAt, transitionCss, type TransitionKind } from "./transition-math";
 
 export type SceneTransition = {

package/src/{remotion → hyperframes}/kit/ScreenOverlay.tsx

@@ -1,6 +1,6 @@
 import React from "react";
 import { useMedia } from "./media";
-import { AbsoluteFill, Loop, OffthreadVideo, useVideoConfig } from "remotion";
+import { AbsoluteFill, Loop, OffthreadVideo, useVideoConfig } from "../frame";
 
 // Lays a white-on-black overlay clip (film marks, HUD frames) over the video. The "screen" blend drops the black.
 // Pass durationSec from the overlay's record to loop it for the whole video; without it the clip plays once.

package/src/{remotion → hyperframes}/kit/Sfx.tsx

@@ -1,6 +1,6 @@
 import React from "react";
 import { useGain, useMedia } from "./media";
-import { Audio, Sequence } from "remotion";
+import { Audio, Sequence } from "../frame";
 
 // Plays one sound effect starting at a frame. at is counted from the start of the enclosing scene, or of the video
 // when placed outside the scenes. Keep volume well under the voiceover.

package/src/{remotion → hyperframes}/kit/SoundCues.tsx

@@ -1,5 +1,5 @@
 import React, { useContext } from "react";
-import { Audio, Sequence } from "remotion";
+import { Audio, Sequence } from "../frame";
 import { gainFor, ManifestContext, UrlsContext } from "./media";
 import { resolveCues, type SoundCue } from "./sound-cues";
 

package/src/{remotion → hyperframes}/kit/TerminalLog.tsx

@@ -1,5 +1,5 @@
 import React from "react";
-import { interpolate, spring, useCurrentFrame, useVideoConfig } from "remotion";
+import { interpolate, spring, useCurrentFrame, useVideoConfig } from "../frame";
 import { Place } from "./Place";
 import { font as loadFont, fonts, springs } from "./theme";
 import { DEFAULT_HERO, rgba, uiColors, type UiTheme } from "./ui-theme";

package/src/{remotion → hyperframes}/kit/Text3D.tsx

@@ -1,5 +1,5 @@
 import React from "react";
-import { useCurrentFrame, useVideoConfig } from "remotion";
+import { useCurrentFrame, useVideoConfig } from "../frame";
 import { FontLoader } from "three/examples/jsm/loaders/FontLoader.js";
 import { TextGeometry } from "three/examples/jsm/geometries/TextGeometry.js";
 import { interBoldTypeface } from "./inter-bold-typeface";

package/src/{remotion → hyperframes}/kit/TextOnImage.tsx

@@ -1,6 +1,6 @@
 import React from "react";
 import { createPortal } from "react-dom";
-import { AbsoluteFill, useVideoConfig } from "remotion";
+import { AbsoluteFill, useVideoConfig } from "../frame";
 import { ImageLayersContext, TextInkContext } from "./ImageLayers";
 import { inkFor, placementOf, REGIONS, zoneRect, type ImageLayersRecord, type Rect, type Region } from "./image-layers-math";
 

package/src/{remotion → hyperframes}/kit/TitleCard.tsx

@@ -1,6 +1,6 @@
 import React from "react";
 import { fonts } from "./theme";
-import { AbsoluteFill, spring, useCurrentFrame, useVideoConfig } from "remotion";
+import { AbsoluteFill, spring, useCurrentFrame, useVideoConfig } from "../frame";
 
 export const TitleCard: React.FC<{ text: string; subtitle?: string; color?: string; background?: string }> = ({
   text, subtitle, color = "#ffffff", background = "transparent",

package/src/{remotion → hyperframes}/kit/Voiceover.tsx

@@ -1,5 +1,5 @@
 import React from "react";
 import { useMedia } from "./media";
-import { Audio } from "remotion";
+import { Audio } from "../frame";
 
 export const Voiceover: React.FC<{ src: string; volume?: number }> = ({ src, volume = 1 }) => <Audio src={useMedia(src)} volume={volume} />;

package/src/{remotion → hyperframes}/kit/Warp3D.tsx

@@ -1,5 +1,5 @@
 import React from "react";
-import { useCurrentFrame, useVideoConfig } from "remotion";
+import { useCurrentFrame, useVideoConfig } from "../frame";
 import { AdditiveBlending, BufferAttribute, Color, DoubleSide, type BufferGeometry } from "three";
 import { warpSpeed, warpStreaks, warpTravel, type SpeedKey } from "./three-fx-math";
 import type { Vec3 } from "./three-math";

package/src/hyperframes/kit/brand-transform.ts

@@ -0,0 +1,25 @@
+import { spring } from "../math";
+import type { Vec3 } from "./three-math";
+
+export const BRAND_TRANSFORMS = ["turn", "arc", "launch"] as const;
+export type BrandTransform = (typeof BRAND_TRANSFORMS)[number];
+export type BrandTransformTiming = { from?: number; frames?: number };
+export function brandTransformFrames({ from = 0, frames = 32 }: BrandTransformTiming = {}) {
+  const start = Math.max(0, Math.round(from));
+  return { start, settle: start + Math.max(2, Math.round(frames)) };
+}
+
+// A pose for any frame, including a seek straight to the hold. The final pose is exactly neutral.
+export function brandTransformAt(frame: number, fps: number, options: BrandTransformTiming & { mode?: BrandTransform; strength?: number } = {}): { visible: boolean; position: Vec3; rotation: Vec3; scale: number } {
+  const { start, settle } = brandTransformFrames(options);
+  const strength = Math.max(0, Math.min(1, options.strength ?? 1));
+  const p = spring({ frame: frame - start, fps, durationInFrames: settle - start, config: { stiffness: 120, damping: 24, overshootClamping: true } });
+  if (p >= 1) return { visible: true, position: [0, 0, 0], rotation: [0, 0, 0], scale: 1 };
+  const rest = (1 - p) * strength;
+  if (options.mode === "arc") {
+    const angle = (1 - p) * Math.PI * 0.75;
+    return { visible: frame >= start, position: [Math.sin(angle) * 0.65 * strength, Math.sin(angle / 2) * 0.22 * strength, -rest * 1.2], rotation: [rest * 0.06, -rest * 0.95, rest * 0.04], scale: 1 - rest * 0.28 };
+  }
+  if (options.mode === "launch") return { visible: frame >= start, position: [0, -rest * 0.28, -rest * 3], rotation: [0, rest * 0.2, rest * 0.08], scale: 1 - rest * 0.55 };
+  return { visible: frame >= start, position: [-rest * 0.35, -rest * 0.12, -rest * 0.5], rotation: [rest * 0.1, -rest * 1.2, rest * 0.03], scale: 1 - rest * 0.2 };
+}

package/src/{remotion → hyperframes}/kit/docs.ts

@@ -123,6 +123,10 @@ Scene3D { camera?: { keys: { frame: number; x?: number; y?: number; z?: number;
   A three.js scene at the size of the frame, for real depth. Transparent unless background is set, so it lays over a 2D ground; a soft three-point light is placed for you (lights={false} to place your own); mood ("studio", "night", "sunset" or "neon") chooses the light colours, their intensities and the fog tint together instead, so lights are never hand-tuned. Put it inside a SceneFrame, with captions and small labels in 2D above it. camera.keys move the camera with the same timing as Camera (a spring that starts 12 frames before the key's frame and lands on it); the default camera is at z 6, looking at the origin, fov 50, and a key that leaves a value out keeps the one before. What it sees: at fov 50 the height is 0.93 times the distance to the object and the width that times width over height, so 3.1 units across at z 6 on 9:16 (4.7 at z 9), 5.6 on 1:1 and 9.9 on 16:9 (not "5.5"). Text3D and Orbit3D read the camera keys and size themselves to fit at the key where the camera is closest: leave their sizes out. visibleWidth(distance, aspect, fov?) and visibleHeight(distance, fov?) give the same numbers. No GL context is made unless a Scene3D is on screen. A 3D scene renders slower: use it only for the shots that need it. See reference/three-d.md.
   <Scene3D camera={{ keys: [{ frame: 0, z: 7.5 }, { frame: 40, z: 6 }] }}><Text3D text="Reelkit" color={palette.hero} enter="rise" /></Scene3D>
 
+BrandTransform3D { mode?: "turn" | "arc" | "launch"; from?: number (0); frames?: number (32); strength?: number (0 to 1, default 1); children }
+  A deterministic arrival for a branded object inside Scene3D: turn exposes its face, arc carries it on a curved path, launch approaches from depth. Wrap Text3D, Card3D or Hero3D; the final pose is neutral and holds exactly. Keep the supplied identity intact and allow a readable hold after landing. A transformation has no built-in audio. brandTransformFrames({ from, frames }) returns { start, settle } in the same local clock; cuesFor([start, settle], "transform", { offset: scene.startFrame, voice, sweepFrames }) places the transform-sweep role before the landing and transform-lock on it. Map both roles to pulled sound files. sweepFrames is the chosen sound's attack in frames (default 10). brandTransformAt(frame, fps, options) returns { visible, position, rotation, scale }; BRAND_TRANSFORMS lists the modes. See reference/brand-motion.md for when and why to choose each.
+  <BrandTransform3D mode="turn" from={6} frames={32}><Text3D text="Reelkit" fit={0.72} /></BrandTransform3D>
+
 Text3D { text: string; fit?: number (0.8); size?: number; depth?: number; color?: string; position?: [x, y, z]; rotation?: [x, y, z] (degrees); enter?: "rise" | "turn" | "fly" | "none"; delay?: number }
   Extruded text, centred on its position, inside a Scene3D. Latin letters, digits and common punctuation only (one bundled typeface, Inter Bold): Hebrew and other scripts stay 2D. Leave size out: the word is measured on its own letters and sized to fill fit (default 0.8) of the frame's width at the closest the Scene3D camera comes, so it is whole at every moment on any aspect; a line break in the text makes a second line, and the height is held to fit of the frame's height. A size you give wins (scene units, the height of a capital-ish line). A push-in starts the word smaller in proportion: z 7.5 to 6 is a gentle one. depth is how far it is extruded (default a quarter of the size). enter is how it arrives, starting delay frames into the scene; "none" is there from the start. Keep type that must be read facing the camera and held at least 1.5 seconds.
   <Text3D text="Meet Reelkit" color="#ffffff" position={[0, 1, 0]} enter="turn" delay={6} />
@@ -223,8 +227,8 @@ cuesOnChanges(scenes, { impact?: { sound, volume? }, whoosh?: { sound, volume?,
   Sounds for the scene changes, placed where the eye sees them. A SceneFrame transition is complete on the boundary but the picture changes most half the transition's frames before it (4 for the default 8, 3 for transitionFrames={6}; none for "cut"), and a hit on the boundary lands after the change. scenes are the manifest's scenes, each with the exit and transitionFrames its SceneFrame has: cuesOnChanges gives an impact on that peak and a whoosh (frames long, from the search line's duration times 30) that ENDS on it, for every change but the one after the last scene; skip lists scene indices to leave silent. changeFrame(scene) is the peak for one scene. A camera zoom, zoomTo or punch is a picture change too: cueOnCamera(frame) is the frame where the Camera move to the key at "frame" is fastest (about 9 frames before it); with punch: true, the fastest frame of a punch (just after its frame). The Camera counts frames from the scene's start when it is inside a SceneFrame, so add the scene's startFrame for an absolute cue.
   const exits = [{ exit: "zoom-through" as const }, { exit: "whip-left" as const, transitionFrames: 6 }, {}];  const cues = cuesOnChanges(manifest.scenes.map((s, i) => ({ ...s, ...exits[i] })), { impact: { sound: "thud", volume: 0.55 }, whoosh: { sound: "whoosh", frames: 24, volume: 0.3 } });
 
-cuesFor(events, kind, { offset?, fps?, voice?, volume?, seed?, riserFrames? }): { at, sound, volume }[]    clearBefore(cues, frame, { seconds?, fps?, riserFrames? }): cues
-  Turns the event frames a component reports into SoundCues with a sensible sound role, level and density for the kind: "type" (promptFrames(...).type: a tick on every 2nd or 3rd character, at most 12 a second, a little different in level each, and a thock one frame after the last), "click" (clickFrames), "snap" (panelSettleFrame: a card or panel landing), "pop" (chapterFrames(...).badges), "count" ([start, settleFrame]: a train of ticks that speeds up and ends on a chime ON settleFrame), "stream" (terminalFrames(...).lines: one soft tick per line, at most 6 a second), "assemble" ([start, lockFrame]: a rising run that gets louder and a lock hit on lockFrame) and "resolve" ([frame] the logo or end card lands: a riser that ends on the chime, which is on the frame). offset is the scene's startFrame when the events are in the scene's own clock. voice: true gives the quieter levels for a film with a narrator (never over 0.3). Each cue's sound is a role: type-tick, type-return, click, snap, pop, count-tick, count-settle, stream, assemble-run, assemble-lock, resolve-riser, resolve-chime. Map each role to a pulled file in sounds, searching with: type-tick "mouse click"; type-return "glass tap"; click "mouse click"; snap "soft impact"; pop "bubble pop"; count-tick "counter ticks"; count-settle "success chime"; stream "glass tap"; assemble-run "counter ticks"; assemble-lock "soft impact"; resolve-riser "whoosh buildup"; resolve-chime "sparkle shimmer" (reelkit assets search "<words>" --kind sfx; the interface pack's names begin with sfx-ui-). clearBefore(cues, chimeFrame) removes every other cue in the second before the riser so the end card has a clear second of nothing; give the music a dip there (Music dips).
+cuesFor(events, kind, { offset?, fps?, voice?, volume?, seed?, sweepFrames?, riserFrames? }): { at, sound, volume }[]    clearBefore(cues, frame, { seconds?, fps?, riserFrames? }): cues
+  Turns the event frames a component reports into SoundCues with a sensible sound role, level and density for the kind: "type" (promptFrames(...).type: a tick on every 2nd or 3rd character, at most 12 a second, a little different in level each, and a thock one frame after the last), "click" (clickFrames), "snap" (panelSettleFrame: a card or panel landing), "pop" (chapterFrames(...).badges), "count" ([start, settleFrame]: a train of ticks that speeds up and ends on a chime ON settleFrame), "stream" (terminalFrames(...).lines: one soft tick per line, at most 6 a second), "assemble" ([start, lockFrame]: a rising run that gets louder and a lock hit on lockFrame), "transform" ([start, settle]: transform-sweep begins sweepFrames before settle, never before start, and transform-lock lands on settle) and "resolve" ([frame] the logo or end card lands: a riser that ends on the chime, which is on the frame). offset is the scene's startFrame when the events are in the scene's own clock. voice: true gives the quieter levels for a film with a narrator (never over 0.3). Each cue's sound is a role: type-tick, type-return, click, snap, pop, count-tick, count-settle, stream, assemble-run, assemble-lock, transform-sweep, transform-lock, resolve-riser, resolve-chime. Map each role to a pulled file in sounds, searching with: type-tick "mouse click"; type-return "glass tap"; click "mouse click"; snap "soft impact"; pop "bubble pop"; count-tick "counter ticks"; count-settle "success chime"; stream "glass tap"; assemble-run "counter ticks"; assemble-lock "soft impact"; transform-sweep "soft ui whoosh"; transform-lock "soft impact"; resolve-riser "whoosh buildup"; resolve-chime "sparkle shimmer" (reelkit assets search "<words>" --kind sfx; the interface pack's names begin with sfx-ui-). clearBefore(cues, chimeFrame) removes every other cue in the second before the riser so the end card has a clear second of nothing; give the music a dip there (Music dips).
   const p = promptFrames({ text, reply }, fps);  const cues = [...cuesFor(p.type, "type", { offset: s.startFrame }), ...cuesFor([p.send], "click", { offset: s.startFrame }), ...cuesFor([settleFrame({ delay: 20 })], "snap", { offset: s.startFrame })];
 
 Music { src: string; volume?: number; duckTo?: number; dips?: { from: number; to: number; volume: number }[] }

package/src/{remotion → hyperframes}/kit/index.ts

@@ -8,6 +8,9 @@ export type { CarryBox } from "./Carry";
 export { ClipLayer } from "./ClipLayer";
 export { Card3D } from "./Card3D";
 export { Assemble3D } from "./Assemble3D";
+export { BrandTransform3D } from "./BrandTransform3D";
+export { BRAND_TRANSFORMS, brandTransformAt, brandTransformFrames } from "./brand-transform";
+export type { BrandTransform, BrandTransformTiming } from "./brand-transform";
 export { Hero3D, Screen3D } from "./Hero3D";
 export { Particles3D } from "./Particles3D";
 export { Warp3D } from "./Warp3D";

package/src/{remotion → hyperframes}/kit/sound-cues.ts

@@ -1,4 +1,4 @@
-// The pure parts of SoundCues: nothing here needs React or Remotion, so it can be tested and used in a composition's own timing code.
+// The pure parts of SoundCues: nothing here needs React or HyperFrames, so it can be tested and used in a composition's own timing code.
 import { travel } from "./motion-math";
 import { PEAKS_ON_BOUNDARY, transitionSpan, type TransitionKind } from "./transition-math";
 import { punchEnvelope, type Punch } from "./motion-math";

package/src/{remotion → hyperframes}/kit/sound-kinds.ts

@@ -4,7 +4,7 @@
 import { hash01 } from "./seeded";
 import type { SoundCue } from "./sound-cues";
 
-export const CUE_KINDS = ["type", "click", "snap", "pop", "count", "stream", "assemble", "resolve"] as const;
+export const CUE_KINDS = ["type", "click", "snap", "pop", "count", "stream", "assemble", "transform", "resolve"] as const;
 export type CueKind = (typeof CUE_KINDS)[number];
 
 // `volume` is [without a narrator, under a narrator]: films with no voice use 0.35 to 0.6 for the main hits and less for small ticks; under a voice nothing is over 0.3.
@@ -32,6 +32,11 @@ export const CUE_TABLE: Record<CueKind, { about: string; per10s: string; roles:
     per10s: "0 to 1",
     roles: { "assemble-run": { search: "counter ticks", seconds: 0.1, volume: [0.25, 0.12] }, "assemble-lock": { search: "soft impact", seconds: 0.7, volume: [0.55, 0.3] } },
   },
+  transform: {
+    about: "a brand or product moving into its readable pose: one sweep into the landing, then one lock hit",
+    per10s: "0 to 2, on changes that explain the product or reveal the brand",
+    roles: { "transform-sweep": { search: "soft ui whoosh", seconds: 0.5, volume: [0.3, 0.16] }, "transform-lock": { search: "soft impact", seconds: 0.7, volume: [0.45, 0.25] } },
+  },
   resolve: {
     about: "the logo or the end card: a riser that ends on a chime, with a clear second of nothing before the riser",
     per10s: "1 per film, at the end",
@@ -54,6 +59,8 @@ export type CueOptions = {
   seed?: number;
   // "resolve" only: how long the riser is in frames (default 36: it ends on the chime).
   riserFrames?: number;
+  // "transform" only: frames from the sweep's start to its audible landing (default 10). Measure the chosen sound's attack.
+  sweepFrames?: number;
 };
 
 const level = (kind: CueKind, role: string, o: CueOptions) => CUE_TABLE[kind].roles[role]!.volume[o.voice ? 1 : 0] * (o.volume ?? 1);
@@ -74,6 +81,7 @@ const spaced = (frames: number[], gap: number): number[] => { const out: number[
 //   "count": [startFrame, settleFrame] (rollStart and settleFrame of CounterRoll): a speeding tick train, then the chime ON settleFrame
 //   "stream": the frame of every line (terminalFrames(...).lines): one soft tick per line, at most 6 a second
 //   "assemble": [startFrame, lockFrame] (assembleProgress start and the frame the last piece lands): a rising run, then the lock ON lockFrame
+//   "transform": [startFrame, settleFrame]: a sweep leading by sweepFrames, then a lock ON settleFrame
 //   "resolve": [frame] the frame the logo lands: the riser ends on it and the chime is ON it (use clearBefore to keep the second before the riser silent)
 export function cuesFor(events: readonly number[], kind: CueKind, o: CueOptions = {}): SoundCue[] {
   if (!CUE_KINDS.includes(kind)) throw new Error(`cuesFor: unknown kind "${kind}". The kinds are: ${CUE_KINDS.join(", ")}.`);
@@ -107,6 +115,11 @@ export function cuesFor(events: readonly number[], kind: CueKind, o: CueOptions
       const run = frames.map((fr, i) => cue(fr, role[0]!, kind === "assemble" ? base * (0.5 + 1.0 * (i / Math.max(1, frames.length - 1))) : base * (0.85 + 0.3 * hash01(i, seed))));
       return unique([...run, cue(end, role[1]!, level(kind, role[1]!, o))]);
     }
+    case "transform": {
+      const start = f[0]!, end = f[f.length - 1]!;
+      const sweep = Math.max(0, Math.round(o.sweepFrames ?? 10));
+      return unique([cue(Math.max(start, end - sweep), "transform-sweep", level("transform", "transform-sweep", o)), cue(end, "transform-lock", level("transform", "transform-lock", o))]);
+    }
     case "resolve": {
       const end = f[0]!, rise = o.riserFrames ?? 36;
       return unique([cue(Math.max(0, end - rise), "resolve-riser", level("resolve", "resolve-riser", o)), cue(end, "resolve-chime", level("resolve", "resolve-chime", o))]);