@effect-motion/cli 0.1.0

package/studio-app/App.tsx

@@ -0,0 +1,197 @@
+import { Player, type PlayerProps } from "@effect-motion/react";
+import { useEffect, useMemo, useState } from "react";
+import { projectRoot } from "./project";
+
+// minimal local mirror of the CLI's config types — the app deliberately
+// avoids importing @effect-motion/cli so it has zero resolution assumptions
+// beyond the project's own dependencies
+type TargetLike = {
+	readonly name?: string;
+	readonly scene?: string;
+	readonly settings?: Record<string, unknown>;
+};
+type ConfigLike = { readonly targets?: ReadonlyArray<TargetLike> };
+
+type SceneEntry = {
+	/** picker identity: `target:<name>` for config targets, `file:<path>` otherwise */
+	readonly key: string;
+	readonly label: string;
+	/** project-relative module path */
+	readonly path: string;
+	readonly registered: boolean;
+	readonly settings: PlayerProps["settings"] | undefined;
+	readonly load: () => Promise<unknown>;
+};
+
+// every scene in src/scenes is previewable without registration; vite keeps
+// this list current as files appear and disappear
+const globbed = import.meta.glob("../../src/scenes/*.ts");
+
+const normalize = (p: string) => p.replace(/^\.\//, "").replace(/^\//, "");
+const globKey = (p: string) => normalize(p.replace(/^(\.\.\/)+/, ""));
+const fileLabel = (key: string) =>
+	key
+		.split("/")
+		.at(-1)
+		?.replace(/\.(ts|tsx|mts|js|mjs)$/, "") ?? key;
+
+const loadByAbsolutePath = (key: string) => () =>
+	import(/* @vite-ignore */ `/@fs${projectRoot}/${key}`);
+
+const buildEntries = (config: ConfigLike | null): ReadonlyArray<SceneEntry> => {
+	// one entry per config target (a scene file can back several targets with
+	// different settings), plus one per scenes-dir file no target references
+	const globLoaders = new Map(
+		Object.entries(globbed).map(([path, load]) => [globKey(path), load]),
+	);
+	const referenced = new Set<string>();
+	const entries: Array<SceneEntry> = [];
+	for (const target of config?.targets ?? []) {
+		if (typeof target?.scene !== "string" || typeof target.name !== "string")
+			continue;
+		const path = normalize(target.scene);
+		referenced.add(path);
+		entries.push({
+			key: `target:${target.name}`,
+			label: target.name,
+			path,
+			registered: true,
+			// a registered scene previews with its target settings so the
+			// preview aspect matches the export
+			settings: target.settings as PlayerProps["settings"],
+			load: globLoaders.get(path) ?? loadByAbsolutePath(path),
+		});
+	}
+	for (const [path, load] of globLoaders) {
+		if (referenced.has(path)) continue;
+		entries.push({
+			key: `file:${path}`,
+			label: fileLabel(path),
+			path,
+			registered: false,
+			settings: undefined,
+			load,
+		});
+	}
+	return entries.sort((a, b) => a.label.localeCompare(b.label));
+};
+
+// selection survives the full-page reloads that scene edits trigger
+const selectionFromHash = () =>
+	decodeURIComponent(window.location.hash.slice(1)) || null;
+
+type SceneState =
+	| { readonly _tag: "idle" }
+	| { readonly _tag: "loading" }
+	| { readonly _tag: "error"; readonly key: string; readonly message: string }
+	| {
+			readonly _tag: "ready";
+			readonly key: string;
+			readonly scene: PlayerProps["scene"];
+	  };
+
+export const App = () => {
+	const [config, setConfig] = useState<ConfigLike | null>(null);
+	const [configError, setConfigError] = useState<string | null>(null);
+	const [selected, setSelected] = useState<string | null>(selectionFromHash);
+	const [state, setState] = useState<SceneState>({ _tag: "idle" });
+
+	useEffect(() => {
+		// the config is optional for studio — a project without one still
+		// previews everything in src/scenes
+		import(/* @vite-ignore */ `/@fs${projectRoot}/motion.config.ts`).then(
+			(module_) => setConfig((module_.default ?? null) as ConfigLike | null),
+			() => setConfig(null),
+		);
+	}, []);
+
+	const entries = useMemo(() => buildEntries(config), [config]);
+	const entry = entries.find((e) => e.key === selected) ?? entries[0];
+
+	useEffect(() => {
+		if (entry === undefined) return;
+		let cancelled = false;
+		setState({ _tag: "loading" });
+		setConfigError(null);
+		entry.load().then(
+			(module_) => {
+				if (cancelled) return;
+				const scene = (module_ as { scene?: PlayerProps["scene"] }).scene;
+				if (scene === undefined) {
+					setState({
+						_tag: "error",
+						key: entry.key,
+						message: `${entry.path} has no \`scene\` export`,
+					});
+				} else {
+					setState({ _tag: "ready", key: entry.key, scene });
+				}
+			},
+			(error) => {
+				if (cancelled) return;
+				setState({
+					_tag: "error",
+					key: entry.key,
+					message: `failed to load ${entry.path}\n\n${error instanceof Error ? error.message : String(error)}`,
+				});
+			},
+		);
+		return () => {
+			cancelled = true;
+		};
+	}, [entry]);
+
+	return (
+		<>
+			<nav className="studio-sidebar">
+				<h1>Scenes</h1>
+				{entries.map((e) => (
+					<button
+						key={e.key}
+						type="button"
+						className="studio-scene-button"
+						data-active={e.key === entry?.key}
+						onClick={() => {
+							window.location.hash = encodeURIComponent(e.key);
+							setSelected(e.key);
+						}}
+					>
+						{e.label}
+						<small>{e.registered ? e.path : `${e.path} (unregistered)`}</small>
+					</button>
+				))}
+				{entries.length === 0 && (
+					<p className="studio-empty">
+						No scenes found — add one in src/scenes/
+					</p>
+				)}
+				{configError !== null && <p className="studio-empty">{configError}</p>}
+			</nav>
+			<main className="studio-main">
+				{state._tag === "error" && (
+					<div className="studio-error">
+						<h2>Scene failed to load</h2>
+						<pre>{state.message}</pre>
+					</div>
+				)}
+				{state._tag === "ready" && (
+					<Player
+						key={state.key}
+						scene={state.scene}
+						autoPlay
+						defaultRepeatMode
+						{...(entry?.settings !== undefined
+							? { settings: entry.settings }
+							: {})}
+					/>
+				)}
+				{(state._tag === "idle" || state._tag === "loading") &&
+					entries.length === 0 && (
+						<p className="studio-empty">
+							Create src/scenes/my-scene.ts exporting a `scene` to get started.
+						</p>
+					)}
+			</main>
+		</>
+	);
+};

package/studio-app/env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/studio-app/index.html

@@ -0,0 +1,96 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="UTF-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+		<title>motion studio</title>
+		<style>
+			:root {
+				color-scheme: dark;
+			}
+			body {
+				margin: 0;
+				background: #16161d;
+				color: #e8e8ef;
+				font-family:
+					ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+			}
+			#root {
+				display: flex;
+				min-height: 100vh;
+			}
+			.studio-sidebar {
+				width: 220px;
+				flex-shrink: 0;
+				border-right: 1px solid #2a2a35;
+				padding: 12px;
+				box-sizing: border-box;
+			}
+			.studio-sidebar h1 {
+				font-size: 13px;
+				text-transform: uppercase;
+				letter-spacing: 0.08em;
+				color: #8a8a99;
+				margin: 4px 4px 12px;
+			}
+			.studio-scene-button {
+				display: block;
+				width: 100%;
+				text-align: left;
+				background: none;
+				border: none;
+				border-radius: 6px;
+				color: inherit;
+				font: inherit;
+				padding: 7px 10px;
+				cursor: pointer;
+			}
+			.studio-scene-button:hover {
+				background: #23232e;
+			}
+			.studio-scene-button[data-active="true"] {
+				background: #2e2e3d;
+			}
+			.studio-scene-button small {
+				display: block;
+				color: #8a8a99;
+				font-size: 11px;
+			}
+			.studio-main {
+				flex: 1;
+				display: flex;
+				align-items: center;
+				justify-content: center;
+				padding: 24px;
+				box-sizing: border-box;
+				min-width: 0;
+			}
+			.studio-error {
+				max-width: 640px;
+				background: #2b1d22;
+				border: 1px solid #6e2f3f;
+				border-radius: 8px;
+				padding: 16px 20px;
+			}
+			.studio-error h2 {
+				margin: 0 0 8px;
+				font-size: 15px;
+				color: #ff7d9c;
+			}
+			.studio-error pre {
+				margin: 0;
+				white-space: pre-wrap;
+				word-break: break-word;
+				font-size: 12px;
+				color: #d8b4bf;
+			}
+			.studio-empty {
+				color: #8a8a99;
+			}
+		</style>
+	</head>
+	<body>
+		<div id="root"></div>
+		<script type="module" src="./main.tsx"></script>
+	</body>
+</html>

package/studio-app/main.tsx

@@ -0,0 +1,11 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { App } from "./App";
+
+const container = document.getElementById("root");
+if (container === null) throw new Error("studio: #root not found");
+createRoot(container).render(
+	<StrictMode>
+		<App />
+	</StrictMode>,
+);

package/studio-app/project.ts

@@ -0,0 +1,3 @@
+// placeholder for typechecking — `motion studio` overwrites this file with
+// the absolute project root when it copies the app into .motion/studio
+export const projectRoot = "";

package/templates/default/AGENTS.md

@@ -0,0 +1,59 @@
+# Working in this project
+
+This is an [effect-motion](https://github.com/julia-script/effect-motion) project: motion graphics written as deterministic, frame-exact scenes in TypeScript, rendered to video. Read this before writing or editing scenes.
+
+## Layout and commands
+
+- `src/scenes/*.ts` — one scene per module, each exporting `scene`. Any file here is previewable without registration.
+- `src/main.ts` — the movie: an ordinary scene that sequences the others (`Scene.play` + `handle.finished`). Nothing is special about it.
+- `motion.config.ts` — render targets. Output is always `<output>/<name>.mp4`; never write output paths by hand.
+- `src/assets/` — static files (images, fonts).
+- `motion studio` — browser preview with hot reload (scene picker lists config targets plus unregistered scenes).
+- `motion render [name...]` — render targets; `motion render ./src/scenes/foo.ts` renders one file with defaults. Flags beat config beat library defaults. `--verbose` prints full error cause chains.
+
+Verify a scene change by rendering it (`motion render <target>`) or checking it in the running studio — not by reading code alone.
+
+## Writing scenes
+
+A scene is an Effect generator: instantiate entities, then yield animations.
+
+```ts
+import { Color, Motion, Physics, Scene, Shapes } from "effect-motion";
+
+export const scene = Scene.make(function* () {
+	const dot = yield* Scene.instantiate(Shapes.Circle, {
+		x: 300, y: 540, radius: 80, fill: Color.hex("#7f5af0"),
+	});
+	yield* Motion.tweenTo(dot, { x: 1620 }, "1200 millis", "easeInOutCubic");
+	yield* Physics.springTo(dot, { y: 300 }, Physics.springs.wobbly);
+});
+```
+
+- **Animators come in pairs**: `verb(instance, from, to, …)` (explicit origin) and `verbTo(instance, to, …)` (origin read from the instance). Prefer the `To` form unless you need a fixed origin.
+- **Prefer semantic helpers** (`Motion.moveTo`, `Motion.fadeTo`, `Physics.springTo`) over raw `tweenTo` when one exists — they carry per-entity meaning (moving a Line translates both endpoints; moving a Group carries its subtree). Use `tweenTo` for fields without a trait (`radius`, `width`, custom fields).
+- **Springs have no duration** — length emerges from the simulation (presets in `Physics.springs`). Springy motion on raw fields uses elastic/bounce *easings*, not physics.
+- **Every animator is a dual**: `Motion.tweenTo(dot, …)` or `dot.pipe(Motion.tweenTo(…))` — both are idiomatic.
+- **Composition**: sequence by yielding one animation after another; `Scene.all([...])` runs them together; `Scene.chain`/`Scene.stagger` sequence with schedules; `Scene.fork` starts a branch you can join later; `Scene.play(otherScene)` mounts a whole scene (await `handle.finished`). `Scene.finish` marks a scene's semantic end — anything after it is a tail that keeps playing without being waited on.
+
+## Determinism rules (non-negotiable)
+
+- **Never** use `Math.random()`, `Date.now()`, or any wall-clock/OS state in a scene — every run must be byte-identical. Use the provided seeded random (`Effect.random`, seeded from `settings.seed`).
+- Durations land exactly on target on the final frame; springs snap on settle. Don't add "fudge" frames.
+- Scene coordinates are the `settings.width`/`height` of the target that renders them (this template: 1920×1080). `dpr` scales output pixels, not coordinates.
+- The `effect` dependency is pinned **exactly** — upgrading it can change seeded-random sequences. Never bump it casually; upgrade `effect` and `effect-motion` together, deliberately.
+
+## Config
+
+```ts
+export default defineConfig({
+	targets: [{
+		name: "intro",                    // unique — doubles as the output basename
+		scene: "./src/scenes/intro.ts",
+		settings: { width: 1920, height: 1080, frameRate: 60, dpr: 1 },
+		output: "./output",               // a DIRECTORY; file name is derived
+		// frames: 600                    // REQUIRED if the scene is infinite
+	}],
+});
+```
+
+A scene used by several targets renders once per target (e.g. different resolutions). An infinite scene (one that never finishes) must set `frames`, or rendering would never end.

package/templates/default/_gitignore

@@ -0,0 +1,3 @@
+node_modules/
+output/
+.motion/

package/templates/default/motion.config.ts

@@ -0,0 +1,20 @@
+import { defineConfig } from "@effect-motion/cli";
+
+// Each target is one rendered video: <output>/<name>.mp4
+// `motion render` renders all of them; `motion render <name>` picks one.
+export default defineConfig({
+	targets: [
+		{
+			name: "hello-world",
+			scene: "./src/scenes/hello-world.ts",
+			settings: { width: 1920, height: 1080, frameRate: 60 },
+			output: "./output",
+		},
+		{
+			name: "main",
+			scene: "./src/main.ts",
+			settings: { width: 1920, height: 1080, frameRate: 60 },
+			output: "./output",
+		},
+	],
+});

package/templates/default/src/main.ts

@@ -0,0 +1,12 @@
+import { Scene } from "effect-motion";
+import { scene as helloWorld } from "./scenes/hello-world";
+
+// The movie: an ordinary scene that sequences the scenes in src/scenes.
+// Nothing is special about this file — it is one more target in
+// motion.config.ts. Add scenes and chain them here.
+export const scene = Scene.make(function* () {
+	const hello = yield* Scene.play(helloWorld);
+	yield* hello.finished;
+	// const next = yield* Scene.play(anotherScene);
+	// yield* next.finished;
+});

package/templates/default/src/scenes/hello-world.ts

@@ -0,0 +1,15 @@
+import { Color, Motion, Scene, Shapes } from "effect-motion";
+
+// A scene is a generator: instantiate entities, then yield animations.
+// Preview it with `motion studio`, render it with `motion render`.
+export const scene = Scene.make(function* () {
+	const circle = yield* Scene.instantiate(Shapes.Circle, {
+		x: 300,
+		y: 540,
+		radius: 80,
+		fill: Color.hex("#7f5af0"),
+	});
+
+	yield* Motion.tweenTo(circle, { x: 1620 }, "1200 millis", "easeInOutCubic");
+	yield* Motion.fadeTo(circle, 0, "400 millis");
+});

package/templates/default/tsconfig.json

@@ -0,0 +1,15 @@
+{
+	"compilerOptions": {
+		"target": "ES2022",
+		"module": "ESNext",
+		"moduleResolution": "bundler",
+		"strict": true,
+		"exactOptionalPropertyTypes": true,
+		"noUncheckedIndexedAccess": true,
+		"skipLibCheck": true,
+		"noEmit": true,
+		"lib": ["ES2022"],
+		"types": ["node"]
+	},
+	"include": ["src", "motion.config.ts"]
+}