reelkit-cli 0.8.0 → 0.10.0

package/skill/reference/styles.md

@@ -5,9 +5,9 @@ description: Use before planning, to choose the video's look with the user - the
 
 # Choosing the look
 
-Pick one look for the whole video before writing the plan, and say it in the first scene's `notes`. A video that mixes looks reads as a template.
+Choose a visual language that fits the material and record it in the first scene's `notes`. Brand films usually benefit from one system; a narration-driven mixed-media film can change worlds by meaning while retaining a thread of type, accent or object. Read `reference/studio-editing.md` when the approach is still open.
 
-If the user already described what they want, match it to a look and confirm in one sentence. Otherwise offer the catalogue below as a short numbered list with one line each, and include "your own: describe it, or send a picture or a link". Ask every open question in one message, each with a default, so the user can answer "defaults".
+Use the user's chosen direction. Otherwise recommend a fitting look with a short reason; use the catalogue as technique references, not a mandatory menu. Offer alternatives when requested. Ask only about consequential missing information.
 
 ## Two modes
 Every look belongs to one mode. The mode decides which rules in `reference/motion-design.md` bend.
@@ -19,8 +19,8 @@ Every look belongs to one mode. The mode decides which rules in `reference/motio
 
 **Showreel** (openers, announcements, anything that must stop the scroll)
 - Hard cuts on the beat between full-colour backgrounds; type that fills the frame. Flat solid colour fields are right here.
-- The camera never stops: a slow push, a slight turn, a short shake on each hit.
-- No frame sits still longer than a third of a second, except the final hold.
+- Camera movement and brief impact shakes can reinforce selected hits. Keep reading moments stable.
+- Pace changes by meaning and musical phrasing, allowing deliberate holds rather than moving every frame.
 - At most three full-screen flashes in any second, and never a red strobe. This is a safety rule, not a taste rule.
 
 ## The catalogue
@@ -57,7 +57,7 @@ Each look is built from what the kit and the shared library already hold, so mos
 **When:** an opener or end card, from the user's own logo file. **How:** build toward the logo from its own shapes and colours and land on it exactly as supplied, held at least 1.5 seconds. **Forbidden:** redrawing, recolouring or stretching the logo; anyone else's logo or trademark.
 
 ### 11. Launch film (restrained)
-**When:** a product, app or feature launch for a tech, software or AI brand: the short film that opens a launch post. **How:** a clean off-white or near-black ground with one soft pool of the hero colour at an edge (search "glow backdrop"); one object in the middle of each shot and a lot of empty space around it. Open on a single line of small, calm type that comes into focus word by word (search "blur reveal"), then one idea per shot, each 1.5 to 2.5 seconds: a field being typed into (search "search bar", "prompt box"), the real screenshot on a card floating at a slight tilt (search "tilt card", "laptop mockup", "phone mockup"), tiles circling a short line (search "orbit"), a feature grid (search "bento"), a pointer that clicks through it (search "cursor click"), the one real number as the payoff (search "statistic counter"), and the logo small and centred to close (search "logo reveal", "brand splash"). Between shots the outgoing object leaves fast with a short directional blur and the next one arrives on a heavy spring; the camera pushes in 2 to 4 percent on every shot. Six to eight shots in 12 to 20 seconds, music without a voice or with very few words. This look opens small on purpose: the first object may fill only a fifth of the frame, as long as the push carries it larger. **Forbidden:** two objects competing in one shot, a busy or textured background, a second accent colour, an invented screen, a shot that holds still, and any brand's mark but the user's own.
+**When:** a product, app or feature launch for a tech, software or AI brand: the short film that opens a launch post. **How:** a clean off-white or near-black ground with one soft pool of the hero colour at an edge (search "glow backdrop"); one object in the middle of each shot and a lot of empty space around it. Open on a single line of small, calm type that comes into focus word by word (search "blur reveal"), then one idea per shot, each 1.5 to 2.5 seconds: a field being typed into (search "search bar", "prompt box"), the real screenshot on a card floating at a slight tilt (search "tilt card", "laptop mockup", "phone mockup"), tiles circling a short line (search "orbit"), a feature grid (search "bento"), a pointer that clicks through it (search "cursor click"), the one real number as the payoff (search "statistic counter"), and the logo small and centred to close (search "logo reveal", "brand splash"). Between shots the outgoing object leaves fast with a short directional blur and the next one arrives on a heavy spring; the camera pushes in 2 to 4 percent on every shot. Six to eight shots in 12 to 20 seconds, music without a voice or with very few words. This look opens small on purpose: the first object may fill only a fifth of the frame, as long as the push carries it larger. **Forbidden:** two objects competing in one shot, a busy or textured background, a second accent colour, an invented screen, an unreadable hold, and a third-party mark unrelated to the material.
 
 ### 12. Social native (showreel)
 **When:** the video should feel like it was made inside the app it is posted to: a reply to a comment, a reaction, proof from the user's own account. **How:** the picture is footage or a generated image and the graphics are the platform's own furniture, used honestly: the comment being answered at the top (search "comment sticker"), a post or a story in its frame (search "post frame", "story frame"), the reel's own buttons over the picture (search "reel overlay"), a profile with a Follow button to close (search "profile card"), reactions floating up on the payoff (search "emoji reactions", "emoji pop"), and words punching in one at a time on the voice (search "punch words"). Emoji are allowed in this look, as reactions and stickers only. **Forbidden:** an invented comment, post, follower count or like count; a platform's logo when the video is not about that platform; emoji standing in for a logo or an icon.
@@ -65,8 +65,11 @@ Each look is built from what the kit and the shared library already hold, so mos
 ### 13. AI at work (restrained)
 **When:** an AI product, an assistant or an automation: the viewer should watch it think and deliver. **How:** near-black ground; the request typed into a glowing field and sent (search "prompt box", "assistant chat window"); the work shown as steps that spin and tick (search "agent steps") or as a placeholder that resolves into the result (search "shimmer skeleton"); the answer streaming in (search "streaming answer"); a calm orb when it listens or speaks (search "glow orb"). One glow, on the field or the orb, never both in one frame. Every answer on screen is the product's real output, supplied by the user. **Forbidden:** an answer the product did not give, a second glowing element, sparkles as decoration, text that streams faster than it can be read.
 
+## Fifteen art styles (14 to 28)
+`reference/art-styles.md` continues this list with fifteen looks whose picture is drawn in code rather than built from interface parts, adapted from the mg-styles-15 films: 14 flat vector, 15 line art, 16 isometric, 17 soft 3D render, 18 hand-drawn cel, 19 collage cut-out, 20 liquid, 21 shape morph, 22 Bauhaus grid, 23 synthwave, 24 aurora glass, 25 variety captions, 26 sticker explainer, 27 pixel art, 28 HUD. Use them as technique references, and read that file when the brief needs a style in that family (a drawn explainer, a line-art logo, an isometric city, "80s", "pixel", "glass", a kinetic poster). Each card there says which motion rules the look is allowed to bend.
+
 ## Your own
-Ask what the message is, what happens on screen, the colours, the length and shape, and for an example if they have one. Choose the nearest look above as the technical base and write a four-line brief in the same shape (when, how, forbidden, structure). Show the brief with the plan at the checkpoint.
+Use the supplied message, actions, colours, duration and format. Ask only for consequential missing details or a reference that the choice depends on. Choose the nearest look above as the technical base and write a four-line brief in the same shape (when, how, forbidden, structure). Show the brief with the plan at the checkpoint.
 
 ## What every look shares
 - The plan checkpoint lists the exact words that will appear on screen and when. Fixing a list takes a minute; fixing a finished animation takes an hour.

package/skill/reference/three-d.md

@@ -5,21 +5,22 @@ description: Use when a shot needs real depth - extruded type, a screen floating
 
 # 3D shots
 
-The kit has a 3D layer on three.js: `Scene3D`, `Text3D`, `Card3D` and `Orbit3D`, and five more elements for the moments in a film that earn them: `Assemble3D`, `Particles3D`, `Hero3D`, `Screen3D` and `Warp3D`. Everything is deterministic and driven by the frame. You import only from `reelkit/kit`; three itself is not importable from the composition.
+The kit has a 3D layer on three.js: `Scene3D`, `Text3D`, `Card3D` and `Orbit3D`, and elements for the moments in a film that earn them: `Assemble3D`, `BrandTransform3D`, `Particles3D`, `Hero3D`, `Screen3D` and `Warp3D`. Everything is deterministic and driven by the frame. You import only from `reelkit/kit`; three itself is not importable from the composition.
 
 ## When 3D earns its place
 
 One hero moment in a film: the product's name landing as thick letters, a screen floating in space and turning to face the viewer, a ring of features that the camera pushes through. That is what the extra depth is for.
 
-It reads as a template when everything spins, when several objects each get their own 3D entrance, or when body text is extruded. Type that is read in a sentence stays 2D. Keep 3D to one or two shots in a film, and let the rest be flat and fast.
+It reads as a template when everything spins, when several objects each get their own 3D entrance, or when body text is extruded. Type that is read in a sentence stays 2D. One or two 3D shots usually provide enough contrast. A requested brand film or showreel can use more when each has a distinct purpose; keep sentences and detailed screens readable.
 
 ## Which element earns its place
 
-One 3D moment per film is usually enough. Choose by what the moment has to say:
+Choose by what the moment has to say. For a brand transformation and its matching sound, read `reference/brand-motion.md`:
 
 | The moment | Reach for | Why |
 |---|---|---|
 | A reveal: the name, a logo, a number of things arriving | `Assemble3D` (`shape="text"` for a word, `"grid"`, `"sphere"`, `"wall"`, `"ring"`) | Hundreds of blocks build into the thing; the piece counter (`assembledCount`) and the lock sound (`assembleEnd`) come with it |
+| A brand or product arriving in its readable pose | `BrandTransform3D` (`mode="turn"`, `"arc"`, `"launch"`) | One deterministic arrival that holds neutral; `brandTransformFrames` gives the exact sound landing |
 | An abstract idea: intelligence, flow, a network, "everything in one place" | `Particles3D` (`from` and `to` shapes, or `"text"`) | Light that changes shape reads as thought, and costs no artwork |
 | The product itself | `Hero3D` (`kind="device"` with a screenshot, `"logo"`, `"coin"`, `"box"`) | A studio-lit object with clearcoat, two coloured rim lights and a soft floor |
 | An interface carried across scenes | `Screen3D` with `poses` | One screen, re-posed at each scene, instead of a new mock each time |
@@ -27,7 +28,7 @@ One 3D moment per film is usually enough. Choose by what the moment has to say:
 
 Set the mood once on the `Scene3D` (`mood="studio"`, `"night"`, `"sunset"` or `"neon"`): it chooses the light colours, their intensities and the fog tint together, so nobody tunes lights by hand. Everything fits a 9:16 frame by default (`fit`, the share of the width at the closest the camera comes), and everything is a pure function of the frame and a `seed`.
 
-Cost, measured on this machine (software GL, as every render here): one second (30 frames) of 9:16 at 1080 by 1920 took about 1.4 to 1.9 seconds to render for each of them at its default size: `Assemble3D` of 600 blocks 1.9 s, 700 blocks 1.7 s, a 900-block word 1.5 s; `Particles3D` of 12000 points 1.5 to 1.8 s; `Hero3D` and `Screen3D` 1.4 to 1.5 s; `Warp3D` of 500 streaks 1.6 s. That includes the start of the renderer, so a longer shot costs less per second; a 3D shot is not what makes a film slow, but keep `count` at what the picture needs (`Assemble3D` up to 4000 pieces, `Particles3D` up to 60000 points, both of which cost more in proportion).
+HyperFrames captures 3D through software GL for consistent output. Render cost depends on the browser, resolution, geometry and other jobs on the machine; measure the actual shot instead of relying on timings from a previous renderer. Start with the count the picture needs and raise it only when the preview improves.
 
 ## How to layer it
 
@@ -47,7 +48,7 @@ So on a phone frame the camera sees about 3 units across at z 6, not 5.5; a card
 
 ## Sizes: leave them out
 
-`Text3D` without `size` is sized from the measured width of its own letters so that it fills `fit` of the frame's width (default 0.8) at the closest the camera comes to it. "Closest" is read from the `Scene3D` camera keys: the key where it sees the least. A word is therefore whole at every moment, on any aspect, and exactly as big as it can be. A line break (`\n`) makes a second line; its height is held to `fit` of the frame's height. Giving `size` turns this off and you are back to doing the arithmetic yourself.
+`Text3D` without `size` is sized from the measured width of its own letters so that it fills `fit` of the frame's width (default 0.8) at the closest the camera comes to it. "Closest" is read from the `Scene3D` camera keys: the key where it sees the least. A word is therefore whole at every moment, on any aspect, and exactly as big as it can be. A line break makes a second line: write `text={"Hyper\nFrames"}` in JSX, since `text="Hyper\nFrames"` passes a literal backslash and n; its height is held to `fit` of the frame's height. Giving `size` turns this off and you are back to doing the arithmetic yourself.
 
 A push-in makes the word smaller at the start in proportion: from z 9 to z 6 it begins at two thirds of its final width. A start at about 25 percent further away than the end (z 7.5 to 6) reads as a gentle push; a larger one begins as a small word. Camera sideways moves (`x`) are not counted, so keep the word near the middle when you orbit.
 
@@ -83,7 +84,7 @@ A word and a ring of labelled cards on a phone frame. Nothing is sized by hand,
 
 ```tsx
 import React from "react";
-import { AbsoluteFill } from "remotion";
+import { AbsoluteFill } from "reelkit/frame";
 import { Card3D, Orbit3D, Scene3D, SceneFrame, Text3D, palettes } from "reelkit/kit";
 import type { VideoProps } from "reelkit/kit";
 
@@ -114,7 +115,7 @@ The name arrives as blocks that fly out of a cloud and settle into the letters,
 
 ```tsx
 import React from "react";
-import { AbsoluteFill } from "remotion";
+import { AbsoluteFill } from "reelkit/frame";
 import { Assemble3D, Scene3D, SceneFrame, palettes } from "reelkit/kit";
 import type { VideoProps } from "reelkit/kit";
 

package/skill/reference/voice-sync.md

@@ -52,7 +52,7 @@ The composition. The number finishes counting as "thousand" is said, and each ro
 
 ```tsx
 import React from "react";
-import { AbsoluteFill, Sequence, useVideoConfig } from "remotion";
+import { AbsoluteFill, Sequence, useVideoConfig } from "reelkit/frame";
 import { Captions, Counter, Entrance, Music, onWord, SceneFrame, sceneById, Sfx, Voiceover, wordFrame } from "reelkit/kit";
 import type { VideoProps } from "reelkit/kit";
 

package/src/commands/assets.ts

@@ -9,13 +9,14 @@ import { GreenTooDullError, keyGreen } from "../project/chromakey";
 import { buildManifest, sentenceGaps, voiceoverStale, type ClipRecord, type Voiceover } from "../project/manifest";
 import { loadPlan } from "./plan";
 import { FILE_NAME } from "../render/validate";
+import { migrateFrameImports } from "../render/static-check";
 import { levelOf } from "../project/loudness";
 import { beatReport, measureMusic, type MusicRecord } from "../project/music";
 import { audioDuration } from "../project/refmeasure";
 import { BACKGROUND_CLIP_SENTENCE, BACKGROUND_IMAGE_SENTENCE, isVideoPath, lookFromNotes, readBackground, setBackground } from "../project/background";
 import { probeFile } from "../project/probe";
 import { frameWithAlpha, measureTextZone, stillToVideo, tempDir, type LayerEntry } from "../project/layers";
-import { coverageVerdict } from "../remotion/kit/image-layers-math";
+import { coverageVerdict } from "../hyperframes/kit/image-layers-math";
 import { svgProblem } from "../project/svgcheck";
 import { FILES, isPrivateProject, openProject, type Project } from "../project/project";
 
@@ -296,6 +297,9 @@ export async function assetsPull(ctx: Ctx, id: string, opts: { scene?: string; f
     const path = `src/${pulled.filename}`;
     if (project.exists(path) && !opts.force) return { ok: false, summary: `${path} already exists. Use --force to replace it with the library version.` };
     await download(pulled.url, project.path(path));
+    const source = readFileSync(project.path(path), "utf8");
+    const migrated = migrateFrameImports(source);
+    if (migrated !== source) writeFileSync(project.path(path), migrated);
     recordPull(project, id, { path, kind: "component", title: pulled.item.title, meta: pulled.item.meta });
     const name = pulled.filename.replace(/\.tsx$/, "");
     const example = typeof pulled.item.meta.example === "string" ? `\nExample: ${pulled.item.meta.example}` : "";

package/src/contract/index.ts

@@ -14,7 +14,7 @@
 // - A library item `id` (pull, commit) matches `^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$`; a `deviceCode` is 1 to 200 characters of plain text.
 // - A `voiceId` is 1 to 64 letters and digits and must be one of the voices the server lists (`voices`), otherwise 400 invalid_request.
 // - A user's component is uploaded for review through the same two calls as any other file (`kind: "component"`). The server checks its source
-//   at commit with the same static check a pulled component gets (only react, remotion and reelkit/kit imports, no network, no globals that reach
+//   at commit with the same static check a pulled component gets (only react, reelkit/frame and reelkit/kit imports, no network, no globals that reach
 //   outside the video) and refuses a source that fails it with 400 `invalid_request` and the first problem. It stays in `review`, is never found
 //   by search or the public listing, and is published only by the owner. A component upload is: `contentType` `text/plain`, `bytes` up to 65,536,
 //   `shareable` true, `filename` matching `^[A-Z][A-Za-z0-9]*\.tsx$`, a `description` of at least 20 characters, and `meta.example` a string of at most

package/src/hyperframes/Root.tsx

@@ -0,0 +1 @@
+export { mountVideo, mountVideo as makeRoot } from "./host";

package/src/hyperframes/fonts.ts

@@ -0,0 +1,54 @@
+import { delayRender, continueRender } from "./frame";
+const loaded = new Set<string>();
+export function loadFont(family: string, slug: string) {
+  if (typeof document !== "undefined" && !loaded.has(slug)) {
+    loaded.add(slug);
+    const handle = delayRender(`font ${family}`);
+    const link = document.createElement("link");
+    link.onload = () => continueRender(handle);
+    link.onerror = () => { continueRender(handle); throw new Error(`Font stylesheet failed: ${slug}`); };
+    link.rel = "stylesheet"; link.href = `./fonts/${slug}.css`; document.head.appendChild(link);
+  }
+  return { fontFamily: `"${family}"` };
+}
+export const fontFamilies = {
+  "Inter": "inter",
+  "Sora": "sora",
+  "ArchivoBlack": "archivo-black",
+  "BebasNeue": "bebas-neue",
+  "GreatVibes": "great-vibes",
+  "JetBrainsMono": "jetbrains-mono",
+  "Kanit": "kanit",
+  "Modak": "modak",
+  "Montserrat": "montserrat",
+  "Roboto": "roboto",
+  "RobotoSlab": "roboto-slab",
+  "Sacramento": "sacramento",
+  "Unbounded": "unbounded",
+  "BungeeShade": "bungee-shade",
+  "Cinzel": "cinzel",
+  "Creepster": "creepster",
+  "Heebo": "heebo",
+  "KaushanScript": "kaushan-script",
+  "LilitaOne": "lilita-one",
+  "MrsSaintDelafield": "mrs-saint-delafield",
+  "Orbitron": "orbitron",
+  "Outfit": "outfit",
+  "PermanentMarker": "permanent-marker",
+  "PlayfairDisplay": "playfair-display",
+  "Rubik": "rubik",
+  "Rye": "rye",
+  "Syne": "syne",
+  "Yellowtail": "yellowtail",
+  "Alef": "alef",
+  "AmaticSC": "amatic-sc",
+  "Assistant": "assistant",
+  "DavidLibre": "david-libre",
+  "FrankRuhlLibre": "frank-ruhl-libre",
+  "Fredoka": "fredoka",
+  "Karantina": "karantina",
+  "NotoSansHebrew": "noto-sans-hebrew",
+  "SecularOne": "secular-one",
+  "SuezOne": "suez-one",
+  "VarelaRound": "varela-round"
+} as const;

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 = {