@vfrey/vfrey 0.0.1 → 1.0.0-beta.0

package/src/scene/runtime/react.tsx

@@ -0,0 +1,115 @@
+/**
+ * `@vfrey/scene`: what a Remotion scene imports. `useTiming()` is the timing file, `<Captions/>` draws the
+ * word-highlighted captions, `<AtLine/>` shows its children while a line is spoken. vfrey wraps the scene in the
+ * provider and plays the voice, so the scene never does either.
+ */
+import { createContext, useContext, useLayoutEffect, useState, type CSSProperties, type ReactNode } from "react";
+import { continueRender, delayRender, staticFile, useCurrentFrame, useVideoConfig } from "remotion";
+import { captionCss, captionGroups, captionStateAt, lineAt, type CaptionOptions, type CaptionStyle, type SceneTiming } from "./core.js";
+
+export type { CaptionOptions, CaptionStyle, SceneTiming };
+export type { TimingBeat, TimingLine, TimingWord } from "../timing.js";
+
+const TimingContext = createContext<SceneTiming | null>(null);
+
+const FONTS = [
+  { family: "Titan One", file: "titan-one.woff2", weight: 400 },
+  { family: "JetBrains Mono", file: "jetbrains-mono-medium.woff2", weight: 500 },
+  { family: "Google Sans Flex", file: "google-sans-flex-latin.woff2", weight: 400 },
+] as const;
+
+/** The scene's timing: words, lines and beats with start and end times in seconds, and `durationSec`. */
+export function useTiming(): SceneTiming {
+  const timing = useContext(TimingContext);
+  if (!timing) throw new Error("@vfrey/scene: useTiming() ran outside a vfrey scene. Render it with `npx vfrey render --scene DIR`.");
+  return timing;
+}
+
+/** The time of the current frame, in seconds. */
+export function useTime(): number {
+  const frame = useCurrentFrame();
+  return frame / useVideoConfig().fps;
+}
+
+/** Wraps the scene: provides the timing and loads the vfrey fonts before the first frame. vfrey adds this itself. */
+export function VfreyProvider(props: { timing: SceneTiming; children: ReactNode }) {
+  const [handle] = useState(() => delayRender("vfrey fonts"));
+  useLayoutEffect(() => {
+    let cancelled = false;
+    Promise.all(FONTS.map((f) => document.fonts.load(`40px "${f.family}"`)))
+      .catch(() => undefined)
+      .finally(() => {
+        if (!cancelled) continueRender(handle);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [handle]);
+  const css = FONTS.map(
+    (f) => `@font-face { font-family: "${f.family}"; src: url("${staticFile(`vfrey/fonts/${f.file}`)}") format("woff2"); font-weight: ${f.weight}; font-style: normal; }`,
+  ).join("\n");
+  return (
+    <TimingContext.Provider value={props.timing}>
+      <style>{css}</style>
+      {props.children}
+    </TimingContext.Provider>
+  );
+}
+
+export interface CaptionsProps extends Omit<CaptionOptions, "style"> {
+  /** `box` (default), `color`, `underline`, `pop` or `plain`. */
+  captionStyle?: CaptionStyle;
+  /** CSS for the caption block: position it anywhere, for example `{ position: "absolute", left: 50, right: 50, bottom: 200, height: 250 }`. */
+  style?: CSSProperties;
+}
+
+/** Word-highlighted captions: groups of a few words, the spoken word marked. */
+export function Captions(props: CaptionsProps) {
+  const timing = useTiming();
+  const t = useTime();
+  const { captionStyle, style, ...options } = props;
+  const opts: CaptionOptions = { ...options, style: captionStyle };
+  const groups = captionGroups(timing, opts);
+  const state = captionStateAt(groups, t);
+  const group = state.group >= 0 ? groups[state.group] : undefined;
+  return (
+    <div className="vf-captions vf-cap-r" style={style} data-vfrey-captions="true">
+      <style>{captionCss(opts, ".vf-cap-r")}</style>
+      {group ? (
+        <div className="vf-grp on">
+          {group.words.map((word, k) => (
+            <span key={word.index} className={k === state.word ? "vf-w on" : "vf-w"}>
+              {word.text}
+            </span>
+          ))}
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+export interface AtLineProps {
+  /** The line to show during. */
+  i: number;
+  /** Show through the end of this later line instead. */
+  to?: number;
+  /** Seconds to keep showing after the line ends. Default: until the next line starts (or the video ends). */
+  hold?: number;
+  /** Children, or a function that gets how far through the window we are (0 to 1) and the seconds since it began. */
+  children: ReactNode | ((progress: number, seconds: number) => ReactNode);
+}
+
+/** Shows its children while line `i` (through line `to`) is spoken. */
+export function AtLine(props: AtLineProps) {
+  const timing = useTiming();
+  const t = useTime();
+  const first = lineAt(timing, props.i);
+  const last = lineAt(timing, props.to ?? props.i);
+  const next = timing.lines[last.i + 1];
+  const end = props.hold !== undefined ? last.end + props.hold : next ? next.start : timing.durationSec;
+  // The first line is shown from the start of the video, not from its first word.
+  const start = props.i === 0 ? 0 : first.start;
+  if (t < start || t >= end) return null;
+  const progress = (t - start) / Math.max(1e-6, end - start);
+  return <>{typeof props.children === "function" ? props.children(progress, t - start) : props.children}</>;
+}

package/src/scene/runtime/transitions.ts

@@ -0,0 +1,133 @@
+/**
+ * The pure half of `vfrey.transition`: which transition types exist, and the plan that turns the calls a scene made
+ * into the chain Framey's shader runtime wants. No DOM, no clock. The browser helper (browser.ts) and the
+ * `scene transitions` command share it.
+ */
+
+export interface TransitionType {
+  name: string;
+  /** What it looks like, in a few words. */
+  look: string;
+  /** Needs WebGL while rendering (`crossfade` does not: it is two opacity tweens). */
+  gpu: boolean;
+}
+
+/** The shader names are Framey's (src/scene/transitions/SOURCE.json lists them; a test keeps the two in step). */
+export const TRANSITION_TYPES: readonly TransitionType[] = [
+  { name: "crossfade", look: "plain dissolve, no shader", gpu: false },
+  { name: "cross-warp-morph", look: "noise-driven morph that blends both shots", gpu: true },
+  { name: "domain-warp", look: "organic noise warp with a glowing edge", gpu: true },
+  { name: "ridged-burn", look: "ridged-noise burn with sparks and heat glow", gpu: true },
+  { name: "whip-pan", look: "horizontal motion blur, a fast camera pan", gpu: true },
+  { name: "sdf-iris", look: "circular iris wipe with a glowing ring", gpu: true },
+  { name: "ripple-waves", look: "concentric ripples from the center", gpu: true },
+  { name: "gravitational-lens", look: "gravity-well warp with chromatic aberration", gpu: true },
+  { name: "cinematic-zoom", look: "radial zoom blur with colored fringing", gpu: true },
+  { name: "chromatic-split", look: "RGB channels separate from the center", gpu: true },
+  { name: "glitch", look: "digital glitch: block displacement and scanlines", gpu: true },
+  { name: "swirl-vortex", look: "spiral rotation with a noisy warp", gpu: true },
+  { name: "thermal-distortion", look: "heat shimmer rising from the bottom", gpu: true },
+  { name: "flash-through-white", look: "flash to white, then the next shot", gpu: true },
+  { name: "light-leak", look: "warm light leak with a lens flare", gpu: true },
+];
+
+export const DEFAULT_TRANSITION = "cross-warp-morph";
+export const DEFAULT_TRANSITION_SECONDS = 0.7;
+export const DEFAULT_TRANSITION_EASE = "power2.inOut";
+
+export interface TransitionSpec {
+  /** Anything that names a shot: a selector, an id, an element. Compared with `===`. */
+  from: unknown;
+  to: unknown;
+  type?: string;
+  /** Start, in seconds. */
+  at: number;
+  duration?: number;
+  ease?: string;
+}
+
+export interface PlannedTransition {
+  time: number;
+  /** Undefined for `crossfade`. */
+  shader: string | undefined;
+  duration: number;
+  ease: string;
+}
+
+export interface TransitionPlan<T> {
+  /** The shots in order: `transitions.length + 1` of them. */
+  scenes: T[];
+  transitions: PlannedTransition[];
+}
+
+const round = (n: number) => Math.round(n * 1000) / 1000;
+
+function closest(name: string): string | null {
+  const lower = name.toLowerCase();
+  const hit = TRANSITION_TYPES.find((t) => t.name.includes(lower) || lower.includes(t.name));
+  return hit?.name ?? null;
+}
+
+/** Throws a plain Error that says what is wrong and what to write instead. */
+export function plan<T>(specs: ReadonlyArray<TransitionSpec & { from: T; to: T }>, label: (shot: T) => string = String): TransitionPlan<T> {
+  if (specs.length === 0) throw new Error("vfrey.transition: no transitions to plan.");
+  const names = TRANSITION_TYPES.map((t) => t.name);
+  const sorted = specs
+    .map((spec, index) => {
+      const type = spec.type ?? DEFAULT_TRANSITION;
+      if (!names.includes(type)) {
+        const near = closest(type);
+        throw new Error(`vfrey.transition: "${type}" is not a transition type.${near ? ` Did you mean "${near}"?` : ""} Types: ${names.join(", ")} (npx vfrey scene transitions).`);
+      }
+      if (!Number.isFinite(spec.at) || spec.at < 0) throw new Error(`vfrey.transition: at must be a time in seconds, not ${String(spec.at)}.`);
+      const duration = spec.duration ?? DEFAULT_TRANSITION_SECONDS;
+      if (!Number.isFinite(duration) || duration <= 0) throw new Error(`vfrey.transition: duration must be more than 0 seconds, not ${String(spec.duration)}.`);
+      if (spec.from === spec.to) throw new Error(`vfrey.transition: a transition needs two different shots, and both are ${label(spec.from)}.`);
+      return { spec, index, type, duration };
+    })
+    .sort((a, b) => a.spec.at - b.spec.at || a.index - b.index);
+  const scenes: T[] = [sorted[0]!.spec.from];
+  const transitions: PlannedTransition[] = [];
+  for (const [i, item] of sorted.entries()) {
+    const prev = sorted[i - 1];
+    if (prev) {
+      if (prev.spec.to !== item.spec.from) {
+        throw new Error(`vfrey.transition: transitions run in a chain. The one at ${round(item.spec.at)} s leaves ${label(item.spec.from)}, but the one before it arrives at ${label(prev.spec.to)}.`);
+      }
+      if (item.spec.at < prev.spec.at + prev.duration - 1e-9) {
+        throw new Error(`vfrey.transition: the transition at ${round(item.spec.at)} s starts before the one at ${round(prev.spec.at)} s ends (${round(prev.spec.at + prev.duration)} s). Start it later, or shorten the first.`);
+      }
+    }
+    if (scenes.includes(item.spec.to)) throw new Error(`vfrey.transition: ${label(item.spec.to)} is shown twice in the chain; each shot appears once.`);
+    scenes.push(item.spec.to);
+    transitions.push({ time: round(item.spec.at), shader: item.type === "crossfade" ? undefined : item.type, duration: round(item.duration), ease: item.spec.ease ?? DEFAULT_TRANSITION_EASE });
+  }
+  return { scenes, transitions };
+}
+
+export interface TransitionState {
+  /** Indexes into `plan.scenes` that are on screen at `t`: one, or two inside a transition. */
+  visible: number[];
+  /** The transition running at `t`, or -1. */
+  index: number;
+  /** 0 to 1 through that transition, before the ease. 0 when none is running. */
+  progress: number;
+}
+
+/**
+ * What is on screen at time `t`. Framey's runtime shows shot i+1 from `time`, and removes shot i at `time + duration`,
+ * so both are on screen in between. A pure function of `t`, so a seek gives the same answer every time.
+ */
+export function stateAt(p: TransitionPlan<unknown>, t: number): TransitionState {
+  let current = 0;
+  let index = -1;
+  let progress = 0;
+  for (const [i, tr] of p.transitions.entries()) {
+    if (t >= tr.time) current = i + 1;
+    if (t >= tr.time && t < tr.time + tr.duration) {
+      index = i;
+      progress = (t - tr.time) / tr.duration;
+    }
+  }
+  return { visible: index === -1 ? [current] : [index, index + 1], index, progress };
+}

package/src/scene/sanitize.ts

@@ -0,0 +1,181 @@
+/**
+ * SVG sanitizing for the pictures an agent supplies. The picture is only ever shown through an <img> data URI
+ * (which cannot run scripts or load anything), and it is cleaned here as well, so a bad file is never carried
+ * through the job payload or the composition.
+ */
+
+const ALLOWED_ELEMENTS = new Set([
+  "svg", "g", "defs", "path", "circle", "ellipse", "rect", "line", "polyline", "polygon", "text", "tspan", "title", "desc",
+  "lineargradient", "radialgradient", "stop", "clippath", "mask", "pattern", "symbol", "use", "marker", "style",
+  "filter", "fegaussianblur", "feoffset", "feblend", "fecolormatrix", "femerge", "femergenode", "fecomposite", "feflood", "fedropshadow",
+]);
+
+/** Elements that are dropped together with everything inside them. */
+const DROPPED_WITH_CONTENT = new Set(["script", "foreignobject", "iframe", "object", "embed", "audio", "video", "canvas", "animate", "set", "animatetransform", "animatemotion", "image", "a", "switch"]);
+
+export interface SvgResult {
+  ok: true;
+  svg: string;
+  /** What was removed, for a warning. */
+  removed: string[];
+}
+
+export type SvgCheck = SvgResult | { ok: false; message: string };
+
+const TAG = /<!--[\s\S]*?-->|<!\[CDATA\[[\s\S]*?\]\]>|<[?!][^>]*>|<\/?[A-Za-z][^\s/>]*(?:\s+(?:[^>"']|"[^"]*"|'[^']*')*)?\/?>/g;
+const ATTR = /([^\s=/"'<>]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+)))?/g;
+
+function safeValue(name: string, value: string): boolean {
+  const v = value.replace(/[\s\u0000-\u001f]+/g, "").toLowerCase();
+  if (v.includes("javascript:") || v.includes("vbscript:") || v.includes("data:text/html") || v.includes("expression(") || v.includes("@import")) return false;
+  // Any url() must point inside the file.
+  for (const match of value.matchAll(/url\(\s*(['"]?)([^'")]*)\1\s*\)/gi)) {
+    if (!match[2]!.trim().startsWith("#")) return false;
+  }
+  if ((name === "href" || name === "xlink:href") && !value.trim().startsWith("#")) return false;
+  return true;
+}
+
+function safeStyle(css: string): boolean {
+  const lower = css.toLowerCase();
+  if (lower.includes("@import") || lower.includes("expression(") || lower.includes("javascript:") || lower.includes("behavior")) return false;
+  for (const match of css.matchAll(/url\(\s*(['"]?)([^'")]*)\1\s*\)/gi)) {
+    if (!match[2]!.trim().startsWith("#")) return false;
+  }
+  return true;
+}
+
+function cleanAttributes(raw: string, removed: string[], tag: string): string {
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const match of raw.matchAll(ATTR)) {
+    const name = match[1]!;
+    const lower = name.toLowerCase();
+    const value = match[2] ?? match[3] ?? match[4] ?? "";
+    if (seen.has(lower)) continue;
+    seen.add(lower);
+    if (lower.startsWith("on")) {
+      removed.push(`${tag}@${name}`);
+      continue;
+    }
+    if (lower === "style" && !safeStyle(value)) {
+      removed.push(`${tag}@style`);
+      continue;
+    }
+    if (lower !== "style" && !safeValue(lower, value)) {
+      removed.push(`${tag}@${name}`);
+      continue;
+    }
+    out.push(`${name}="${value.replace(/"/g, "&quot;")}"`);
+  }
+  return out.length ? " " + out.join(" ") : "";
+}
+
+/** Returns the cleaned SVG text. It fails only when the file is not an SVG at all. */
+export function sanitizeSvg(input: string): SvgCheck {
+  const text = input.replace(/^/, "");
+  if (/<!ENTITY/i.test(text)) return { ok: false, message: "the SVG declares an XML entity, which is not allowed" };
+  const removed: string[] = [];
+  const out: string[] = [];
+  const stack: string[] = [];
+  let skipDepth = 0;
+  let skipName = "";
+  let last = 0;
+  let sawRoot = false;
+  let rootClosed = false;
+  let inStyle = false;
+  const emitText = (chunk: string) => {
+    if (skipDepth > 0 || !chunk) return;
+    if (inStyle) {
+      out.push(safeStyle(chunk) ? chunk : "");
+      if (!safeStyle(chunk)) removed.push("style");
+      return;
+    }
+    if (stack.length > 0) out.push(chunk.replace(/<(?![/A-Za-z])/g, "&lt;"));
+  };
+  for (const match of text.matchAll(TAG)) {
+    emitText(text.slice(last, match.index));
+    last = match.index! + match[0].length;
+    const token = match[0];
+    if (token.startsWith("<!--") || token.startsWith("<?") || token.startsWith("<!")) {
+      if (token.startsWith("<![CDATA[")) emitText(token);
+      continue;
+    }
+    const closing = token.startsWith("</");
+    const selfClosing = token.endsWith("/>");
+    const nameMatch = token.match(/^<\/?([^\s/>]+)/);
+    const rawName = nameMatch![1]!;
+    const name = rawName.replace(/^svg:/i, "");
+    const lower = name.toLowerCase();
+    if (skipDepth > 0) {
+      if (lower === skipName) {
+        if (closing) skipDepth -= 1;
+        else if (!selfClosing) skipDepth += 1;
+      }
+      continue;
+    }
+    if (closing) {
+      if (stack.length === 0) continue;
+      const top = stack.pop()!;
+      if (top.toLowerCase() === "style") inStyle = false;
+      out.push(`</${top}>`);
+      if (stack.length === 0) rootClosed = true;
+      continue;
+    }
+    if (DROPPED_WITH_CONTENT.has(lower)) {
+      removed.push(lower);
+      if (!selfClosing) {
+        skipDepth = 1;
+        skipName = lower;
+      }
+      continue;
+    }
+    if (!ALLOWED_ELEMENTS.has(lower)) {
+      removed.push(lower);
+      if (!selfClosing) {
+        skipDepth = 1;
+        skipName = lower;
+      }
+      continue;
+    }
+    if (rootClosed) continue;
+    if (!sawRoot) {
+      if (lower !== "svg") return { ok: false, message: "the file does not start with an <svg> element" };
+      sawRoot = true;
+    }
+    const attrs = cleanAttributes(token.slice(1 + rawName.length).replace(/\/?>$/, ""), removed, lower);
+    let finalAttrs = attrs;
+    if (lower === "svg" && stack.length === 0 && !/\sxmlns=/.test(finalAttrs)) finalAttrs += ' xmlns="http://www.w3.org/2000/svg"';
+    if (selfClosing) {
+      out.push(`<${name}${finalAttrs}/>`);
+      if (stack.length === 0) rootClosed = true;
+    } else {
+      out.push(`<${name}${finalAttrs}>`);
+      stack.push(name);
+      if (lower === "style") inStyle = true;
+    }
+  }
+  if (!sawRoot) return { ok: false, message: "the file has no <svg> element" };
+  while (stack.length) out.push(`</${stack.pop()!}>`);
+  return { ok: true, svg: out.join(""), removed };
+}
+
+/** The SVG's width and height ratio from its viewBox, or from width and height; null when it has neither. */
+export function svgBox(svg: string): { width: number; height: number } | null {
+  const root = svg.match(/<svg\b[^>]*>/i)?.[0] ?? "";
+  const vb = root.match(/viewBox="\s*[-\d.eE]+[ ,]+[-\d.eE]+[ ,]+([\d.eE]+)[ ,]+([\d.eE]+)\s*"/i);
+  if (vb && Number(vb[1]) > 0 && Number(vb[2]) > 0) return { width: Number(vb[1]), height: Number(vb[2]) };
+  const w = root.match(/\swidth="([\d.]+)(?:px)?"/i);
+  const h = root.match(/\sheight="([\d.]+)(?:px)?"/i);
+  if (w && h && Number(w[1]) > 0 && Number(h[1]) > 0) return { width: Number(w[1]), height: Number(h[1]) };
+  return null;
+}
+
+/** Gives the root a viewBox when only width and height were set, so it scales inside any box. */
+export function withViewBox(svg: string): string {
+  const root = svg.match(/<svg\b[^>]*>/i)?.[0] ?? "";
+  if (/viewBox=/i.test(root)) return svg;
+  const box = svgBox(svg);
+  if (!box) return svg;
+  return svg.replace(/<svg\b/i, `<svg viewBox="0 0 ${box.width} ${box.height}"`);
+}

package/src/scene/scene.ts

@@ -0,0 +1,152 @@
+import { copyFile, lstat, mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { sanitizeSvg } from "./sanitize.js";
+import { REMOTION_TRANSITIONS_FIX } from "./transitions.js";
+
+/** The most a scene folder may hold, in bytes. */
+export const SCENE_MAX_BYTES = 50 * 1024 * 1024;
+
+export type SceneKind = "html" | "tsx";
+
+/** The engines that render each kind of scene, in the order the Fix line offers them. */
+export const KIND_ENGINES: Record<SceneKind, string[]> = {
+  html: ["vfrey-framey", "hyperframes"],
+  tsx: ["remotion"],
+};
+
+export const KIND_ENTRY: Record<SceneKind, string> = { html: "index.html", tsx: "index.tsx" };
+
+/** A scene that cannot be rendered as given. `message` says what is wrong and `fix` how to fix it. */
+export class SceneError extends Error {
+  constructor(
+    message: string,
+    readonly fix: string,
+    readonly code: string = "scene_invalid",
+  ) {
+    super(message);
+    this.name = "SceneError";
+  }
+}
+
+export function kindForEngine(engineId: string): SceneKind | null {
+  if (engineId === "remotion") return "tsx";
+  if (engineId === "vfrey-framey" || engineId === "hyperframes") return "html";
+  return null;
+}
+
+async function exists(file: string): Promise<boolean> {
+  return stat(file).then(
+    () => true,
+    () => false,
+  );
+}
+
+/** Every file under `dir`, relative, skipping vfrey's own folder (it is rewritten at render time), node_modules, and the studio's `.hyperframes` history. */
+async function listFiles(dir: string, base = dir): Promise<Array<{ rel: string; abs: string; link: boolean; size: number }>> {
+  const out: Array<{ rel: string; abs: string; link: boolean; size: number }> = [];
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    const abs = path.join(dir, entry.name);
+    const rel = path.relative(base, abs).split(path.sep).join("/");
+    if (entry.name === ".DS_Store" || entry.name === "node_modules" || entry.name === ".git" || entry.name === ".hyperframes") continue;
+    if (dir === base && entry.name === "vfrey") continue;
+    if (entry.isSymbolicLink()) {
+      out.push({ rel, abs, link: true, size: 0 });
+    } else if (entry.isDirectory()) {
+      out.push(...(await listFiles(abs, base)));
+    } else if (entry.isFile()) {
+      out.push({ rel, abs, link: false, size: (await lstat(abs)).size });
+    }
+  }
+  return out;
+}
+
+/** Checks that the folder is a scene this engine can render. Throws a SceneError with the Fix line otherwise. */
+export async function checkScene(dir: string, engineId: string): Promise<{ kind: SceneKind; bytes: number; files: number }> {
+  const kind = kindForEngine(engineId);
+  if (!kind) {
+    throw new SceneError(`A scene needs a render engine, and ${engineId} does not render scenes.`, "choose --engine vfrey-framey or --engine remotion.", "scene_engine_mismatch");
+  }
+  const info = await stat(dir).catch(() => null);
+  if (!info?.isDirectory()) {
+    throw new SceneError(
+      `The scene folder ${dir} does not exist.`,
+      `write ${path.join(dir, KIND_ENTRY[kind])} yourself, or run \`npx vfrey scene init ${dir}${kind === "tsx" ? " --engine remotion" : ""}\` for a starting point.`,
+      "scene_missing",
+    );
+  }
+  const hasHtml = await exists(path.join(dir, "index.html"));
+  const hasTsx = await exists(path.join(dir, "index.tsx"));
+  if (!(kind === "html" ? hasHtml : hasTsx)) {
+    const other: SceneKind = kind === "html" ? "tsx" : "html";
+    const found = other === "html" ? hasHtml : hasTsx;
+    const engine = engineName(engineId);
+    if (found) {
+      const fits = KIND_ENGINES[other];
+      throw new SceneError(
+        `The scene in ${dir} is ${other === "html" ? "an HTML composition (index.html)" : "a React component (index.tsx)"}, and ${engine} renders ${kind === "html" ? "HTML (index.html)" : "React (index.tsx)"}.`,
+        `render it with --engine ${fits[0]}${fits[1] ? ` (or ${fits[1]})` : ""}, or write ${KIND_ENTRY[kind]} for ${engine}.`,
+        "scene_engine_mismatch",
+      );
+    }
+    throw new SceneError(
+      `The scene folder ${dir} has no ${KIND_ENTRY[kind]}, which ${engine} needs.`,
+      `write ${path.join(dir, KIND_ENTRY[kind])}, or run \`npx vfrey scene init ${dir}${kind === "tsx" ? " --engine remotion" : ""}\` for a starting point.`,
+      "scene_missing",
+    );
+  }
+  if (kind === "tsx") {
+    const source = await readFile(path.join(dir, "index.tsx"), "utf8").catch(() => "");
+    if (/\bvfrey\.transition\s*\(|vfrey\/transitions\.js|\bHyperShader\b/.test(source)) {
+      throw new SceneError("Shader transitions are not supported in Remotion scenes; they are HTML-scene features (vfrey.transition with vfrey-framey or hyperframes).", REMOTION_TRANSITIONS_FIX, "scene_transitions_unsupported");
+    }
+  }
+  const files = await listFiles(dir);
+  const bytes = files.reduce((sum, f) => sum + f.size, 0);
+  if (bytes > SCENE_MAX_BYTES) {
+    throw new SceneError(
+      `The scene folder is ${(bytes / 1024 / 1024).toFixed(1)} MB; the limit is ${SCENE_MAX_BYTES / 1024 / 1024} MB.`,
+      "remove large images or videos from the scene folder; draw with SVG and CSS instead.",
+      "scene_too_large",
+    );
+  }
+  return { kind, bytes, files: files.length };
+}
+
+function engineName(id: string): string {
+  return id === "remotion" ? "Remotion" : id === "hyperframes" ? "HyperFrames" : "vfrey Framey";
+}
+
+/**
+ * Copies a scene folder to `dest`, the way vfrey keeps it with the run. Every SVG is sanitized, links that leave
+ * the folder are not followed, and vfrey's own `vfrey/` folder is left out (it is written fresh at render time).
+ * Returns what was dropped, as warnings for the run.
+ */
+export async function storeScene(src: string, dest: string): Promise<{ warnings: string[]; bytes: number; files: number }> {
+  const warnings: string[] = [];
+  await rm(dest, { recursive: true, force: true });
+  await mkdir(dest, { recursive: true });
+  let bytes = 0;
+  let count = 0;
+  for (const file of await listFiles(src)) {
+    const target = path.join(dest, file.rel);
+    if (file.link) {
+      warnings.push(`${file.rel} is a symbolic link; it was not copied into the scene.`);
+      continue;
+    }
+    await mkdir(path.dirname(target), { recursive: true });
+    if (file.rel.toLowerCase().endsWith(".svg")) {
+      const checked = sanitizeSvg(await readFile(file.abs, "utf8"));
+      if (!checked.ok) {
+        warnings.push(`${file.rel} was left out: ${checked.message}.`);
+        continue;
+      }
+      if (checked.removed.length > 0) warnings.push(`${file.rel}: removed ${[...new Set(checked.removed)].join(", ")} while sanitizing.`);
+      await writeFile(target, checked.svg);
+    } else {
+      await copyFile(file.abs, target);
+    }
+    bytes += file.size;
+    count += 1;
+  }
+  return { warnings, bytes, files: count };
+}

package/src/scene/studio-command.ts

@@ -0,0 +1,48 @@
+import path from "node:path";
+import { browserDisabled, openBrowser } from "../dashboard-start.js";
+import { SceneError } from "./scene.js";
+import { parseStudioArgs, startStudio, type StudioHandle } from "./studio.js";
+
+interface Io {
+  env: NodeJS.ProcessEnv;
+  stdout: (text: string) => void;
+  stderr: (text: string) => void;
+  /** Test hooks. The CLI omits them. */
+  open?: (url: string) => void;
+  /** Resolves when the studio should stop. The CLI waits for Ctrl+C or SIGTERM. */
+  stopped?: Promise<void>;
+}
+
+function untilSignal(): Promise<void> {
+  return new Promise((resolve) => {
+    const done = () => resolve();
+    process.once("SIGINT", done);
+    process.once("SIGTERM", done);
+  });
+}
+
+/** `vfrey scene studio DIR [--port N] [--no-browser]`: edit an HTML scene in Framey's studio until Ctrl+C. */
+export async function runSceneStudio(argv: string[], io: Io): Promise<number> {
+  const parsed = parseStudioArgs(argv);
+  if (!parsed.ok) {
+    io.stderr(`✗ ${parsed.message}\nFix: ${parsed.fix}\n`);
+    return 1;
+  }
+  const { dir, port, noBrowser } = parsed.args;
+  let studio: StudioHandle;
+  try {
+    studio = await startStudio({ dir, port, env: io.env });
+  } catch (error) {
+    if (error instanceof SceneError) {
+      io.stderr(`✗ ${error.message}\nFix: ${error.fix}\n`);
+      return 1;
+    }
+    throw error;
+  }
+  io.stdout(`vfrey studio ${studio.url}\n`);
+  io.stderr(`Editing ${studio.dir}. Saves go to that folder. Render it as usual: npx vfrey render --scene ${path.relative(process.cwd(), studio.dir) || "."} --engine vfrey-framey\nPress Ctrl+C to stop the studio.\n`);
+  if (!noBrowser && !browserDisabled([], io.env)) (io.open ?? openBrowser)(studio.url);
+  await (io.stopped ?? untilSignal());
+  await studio.close();
+  return 0;
+}