create-effect-motion 0.4.0

package/README.md

@@ -0,0 +1,49 @@
+# create-effect-motion
+
+Scaffold a new [effect-motion](https://github.com/julia-script/effect-motion) project:
+
+```sh
+pnpm create effect-motion
+# or: npm create effect-motion / yarn create effect-motion / bun create effect-motion
+```
+
+The prompts ask for a target directory, a package manager, and whether to set up [Biome](https://biomejs.dev) for linting/formatting. The generated project:
+
+```
+my-motion-project/
+├─ src/
+│  ├─ scenes/hello-world.ts   # a scene: a module exporting `scene`
+│  ├─ assets/                 # static files
+│  └─ main.ts                 # the movie — an ordinary scene composing the others
+├─ motion.config.ts           # render targets
+├─ AGENTS.md                  # authoring rules for AI coding agents
+├─ biome.json                 # if Biome was selected
+├─ package.json               # EXACT pins of effect-motion + effect
+└─ tsconfig.json
+```
+
+Answering `.` scaffolds into the current directory and names the project after it. A `git init` runs automatically unless the directory already sits inside a repository. Then:
+
+```sh
+pnpm studio    # preview scenes with hot reload
+pnpm render    # render targets from motion.config.ts to MP4
+```
+
+## Flags
+
+Every prompt has a flag twin, so the scaffolder runs non-interactively in scripts and CI:
+
+```sh
+create-effect-motion my-app --pm pnpm --no-biome --no-install
+create-effect-motion --yes    # accept every default (-y)
+```
+
+- `[directory]` — target directory (`.` for the current one)
+- `--pm <pnpm|npm|yarn|bun>` — package manager (prompt defaults to the one that invoked the scaffolder)
+- `--biome` / `--no-biome` — include or skip the Biome setup (prompt defaults to yes)
+- `--no-install` — skip dependency installation
+- `--yes` / `-y` — accept the default answer for every prompt not answered by a flag
+
+## Version pinning
+
+Dependency versions are pinned **exactly** (no ranges): each release of this package scaffolds the matching versions of `effect-motion`, `@effect-motion/react`, `@effect-motion/export`, `@effect-motion/cli`, and `effect`. The `effect` pin is a determinism invariant — upgrading effect can change seeded random sequences — so upgrade it and effect-motion together, deliberately.

package/dist/MotionCliError.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Every failure mode of the scaffolder, as a `reason` union on a single
+ * tagged error — same pattern as @effect-motion/cli's MotionCliError (a
+ * deliberate small copy; the two packages share no code).
+ */
+export type MotionCliReason = "ScaffoldTargetNotEmpty" | "ScaffoldFailed" | "InstallFailed";
+declare const MotionCliError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "MotionCliError";
+} & Readonly<A>;
+/**
+ * The one error type of `create-effect-motion`: either wraps an upstream
+ * failure (`cause` carries it) or states a custom one. `message` MUST name
+ * the offender — the directory or command that failed — because it is the
+ * only line shown without `--verbose`.
+ */
+export declare class MotionCliError extends MotionCliError_base<{
+    readonly reason: MotionCliReason;
+    readonly message: string;
+    readonly cause?: unknown;
+}> {
+}
+/** Render an error for the terminal: message always, cause chain on verbose. */
+export declare const renderForTerminal: (error: MotionCliError, verbose: boolean) => string;
+export {};

package/dist/MotionCliError.js

@@ -0,0 +1,21 @@
+import * as Data from "effect/Data";
+/**
+ * The one error type of `create-effect-motion`: either wraps an upstream
+ * failure (`cause` carries it) or states a custom one. `message` MUST name
+ * the offender — the directory or command that failed — because it is the
+ * only line shown without `--verbose`.
+ */
+export class MotionCliError extends Data.TaggedError("MotionCliError") {
+}
+/** Render an error for the terminal: message always, cause chain on verbose. */
+export const renderForTerminal = (error, verbose) => {
+    const lines = [`error(${error.reason}): ${error.message}`];
+    if (verbose) {
+        let cause = error.cause;
+        while (cause !== undefined && cause !== null) {
+            lines.push(`caused by: ${cause instanceof Error ? (cause.stack ?? cause.message) : String(cause)}`);
+            cause = cause instanceof Error ? cause.cause : undefined;
+        }
+    }
+    return lines.join("\n");
+};

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { NodeRuntime, NodeServices } from "@effect/platform-node";
+import * as Effect from "effect/Effect";
+import { Command } from "effect/unstable/cli";
+import { CLI_VERSION, reportErrors, rootCommand } from "./create.js";
+// read pre-parse so the reporter works even when parsing itself fails
+const verbose = process.argv.includes("--verbose");
+const program = reportErrors(Command.run(rootCommand, { version: CLI_VERSION }), verbose);
+// every typed failure is handled by reportErrors, so the default reporter
+// only ever fires for defects — bugs in the scaffolder itself
+NodeRuntime.runMain(Effect.provide(program, NodeServices.layer));

package/dist/create.d.ts

@@ -0,0 +1,27 @@
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { CliError, Command, Prompt } from "effect/unstable/cli";
+import { ChildProcessSpawner } from "effect/unstable/process";
+import { MotionCliError } from "./MotionCliError.js";
+/**
+ * `git init` the fresh project, unless it is already inside a work tree
+ * (scaffolding into a subdirectory of an existing repo). Git being absent
+ * or failing is never fatal — the scaffold is complete without it.
+ */
+export declare const gitInit: (dir: string) => Effect.Effect<void, never, ChildProcessSpawner.ChildProcessSpawner>;
+export declare const rootCommand: Command.Command<"create-effect-motion", {
+    readonly directory: Option.Option<string>;
+    readonly pm: Option.Option<"bun" | "npm" | "pnpm" | "yarn">;
+    readonly biome: boolean;
+    readonly noBiome: boolean;
+    readonly noInstall: boolean;
+    readonly yes: boolean;
+}, {}, MotionCliError, ChildProcessSpawner.ChildProcessSpawner | Prompt.Environment>;
+export declare const CLI_VERSION: string;
+/**
+ * The single exhaustive failure boundary: MotionCliError prints its message
+ * (cause chain under --verbose) and sets a non-zero exit; Command API errors
+ * print their diagnostic (help output was already rendered for ShowHelp).
+ * Anything past this boundary is a defect.
+ */
+export declare const reportErrors: <A, R>(program: Effect.Effect<A, MotionCliError | CliError.CliError, R>, verbose: boolean) => Effect.Effect<A | undefined, never, R>;

package/dist/create.js

@@ -0,0 +1,160 @@
+import * as Console from "effect/Console";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { Path } from "effect/Path";
+import { Argument, CliError, Command, Flag, GlobalFlag, Prompt, } from "effect/unstable/cli";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+import { MotionCliError, renderForTerminal } from "./MotionCliError.js";
+import { VERSION } from "./pins.js";
+import { ensureEmptyDir, resolveProjectDir, scaffoldProject, } from "./scaffold.js";
+const DEFAULT_DIRECTORY = "my-motion-project";
+const PACKAGE_MANAGERS = ["pnpm", "npm", "yarn", "bun"];
+/** The manager that invoked us (`pnpm create …` etc.), if detectable. */
+const detectPackageManager = () => {
+    const agent = process.env.npm_config_user_agent ?? "";
+    return PACKAGE_MANAGERS.find((pm) => agent.startsWith(pm));
+};
+const flags = {
+    directory: Argument.string("directory").pipe(Argument.withDescription('Target directory ("." scaffolds into the current directory)'), Argument.optional),
+    pm: Flag.optional(Flag.choice("pm", PACKAGE_MANAGERS).pipe(Flag.withDescription("Package manager (skips the prompt)"))),
+    biome: Flag.boolean("biome").pipe(Flag.withDescription("Set up Biome for linting/formatting (skips the prompt)")),
+    noBiome: Flag.boolean("no-biome").pipe(Flag.withDescription("Skip the Biome setup (skips the prompt)")),
+    noInstall: Flag.boolean("no-install").pipe(Flag.withDescription("Skip dependency installation")),
+    yes: Flag.boolean("yes").pipe(Flag.withAlias("y"), Flag.withDescription("Accept the default answer for every prompt not answered by a flag")),
+};
+const promptDirectory = Prompt.text({
+    message: 'Where should the project be created? ("." for the current directory)',
+    default: DEFAULT_DIRECTORY,
+});
+const promptPackageManager = Effect.suspend(() => {
+    const detected = detectPackageManager();
+    // detected manager listed first so plain Enter picks it
+    const ordered = [
+        ...(detected ? [detected] : []),
+        ...PACKAGE_MANAGERS.filter((pm) => pm !== detected),
+    ];
+    return Prompt.select({
+        message: "Which package manager?",
+        choices: ordered.map((pm) => ({ title: pm, value: pm })),
+    });
+});
+const promptBiome = Prompt.confirm({
+    message: "Add Biome for linting/formatting?",
+    initial: true,
+});
+const runInstall = (pm, dir) => Effect.gen(function* () {
+    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+    const command = ChildProcess.make(pm, ["install"], {
+        cwd: dir,
+        stdin: "inherit",
+        stdout: "inherit",
+        stderr: "inherit",
+    });
+    yield* Effect.scoped(Effect.gen(function* () {
+        const handle = yield* spawner.spawn(command);
+        const code = yield* handle.exitCode;
+        if (code !== 0) {
+            return yield* new MotionCliError({
+                reason: "InstallFailed",
+                message: `${pm} install exited with code ${code} in ${dir} — run it manually`,
+                cause: code,
+            });
+        }
+    })).pipe(Effect.catchTag("PlatformError", (cause) => Effect.fail(new MotionCliError({
+        reason: "InstallFailed",
+        message: `could not run "${pm} install" in ${dir} — is ${pm} installed?`,
+        cause,
+    }))));
+});
+/** Exit code of a git command in `dir`; fails with PlatformError if git is absent. */
+const gitExitCode = (dir, args) => Effect.scoped(Effect.gen(function* () {
+    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+    const handle = yield* spawner.spawn(ChildProcess.make("git", args, {
+        cwd: dir,
+        stdin: "ignore",
+        stdout: "ignore",
+        stderr: "ignore",
+    }));
+    return yield* handle.exitCode;
+}));
+/**
+ * `git init` the fresh project, unless it is already inside a work tree
+ * (scaffolding into a subdirectory of an existing repo). Git being absent
+ * or failing is never fatal — the scaffold is complete without it.
+ */
+export const gitInit = (dir) => Effect.gen(function* () {
+    const inside = yield* gitExitCode(dir, [
+        "rev-parse",
+        "--is-inside-work-tree",
+    ]);
+    if (inside === 0)
+        return;
+    yield* gitExitCode(dir, ["init"]);
+}).pipe(Effect.ignore);
+const handler = (input) => Effect.gen(function* () {
+    const path = yield* Path;
+    const cwd = process.cwd();
+    const dirInput = Option.getOrUndefined(input.directory) ??
+        (input.yes ? DEFAULT_DIRECTORY : yield* promptDirectory);
+    const { dir, name } = resolveProjectDir(path, cwd, dirInput);
+    yield* ensureEmptyDir(dir);
+    const pm = Option.getOrUndefined(input.pm) ??
+        (input.yes
+            ? (detectPackageManager() ?? "npm")
+            : yield* promptPackageManager);
+    // explicit flags win over --yes; --no-biome beats --biome if both are passed
+    const biome = input.noBiome
+        ? false
+        : input.biome || input.yes || (yield* promptBiome);
+    yield* scaffoldProject(dir, name, { biome });
+    yield* gitInit(dir);
+    yield* Console.log(`Scaffolded ${name} in ${dir}`);
+    if (input.noInstall) {
+        yield* Console.log([
+            "",
+            "Next steps:",
+            dir === cwd ? "" : `  cd ${path.relative(cwd, dir)}`,
+            `  ${pm} install`,
+            `  ${pm === "npm" ? "npm run" : pm} studio`,
+        ]
+            .filter((line) => line !== "")
+            .join("\n"));
+        return;
+    }
+    yield* runInstall(pm, dir);
+    yield* Console.log([
+        "",
+        `${name} is ready.`,
+        dir === cwd ? "" : `  cd ${path.relative(cwd, dir)}`,
+        `  ${pm === "npm" ? "npm run" : pm} studio    # preview scenes with hot reload`,
+        `  ${pm === "npm" ? "npm run" : pm} render    # render targets from motion.config.ts`,
+    ]
+        .filter((line) => line !== "")
+        .join("\n"));
+}).pipe(
+// ctrl-c in a prompt is an interruption, not a failure
+Effect.catchTag("QuitError", () => Effect.interrupt));
+// registered globally so `--verbose` parses anywhere on the command line;
+// the reporter reads argv directly because it sits outside handler context
+const verboseFlag = GlobalFlag.setting("verbose")({
+    flag: Flag.boolean("verbose").pipe(Flag.withDescription("Print full error cause chains")),
+});
+export const rootCommand = Command.make("create-effect-motion", flags, handler).pipe(Command.withDescription("Scaffold a new effect-motion project"), Command.withGlobalFlags([verboseFlag]));
+export const CLI_VERSION = VERSION;
+/**
+ * The single exhaustive failure boundary: MotionCliError prints its message
+ * (cause chain under --verbose) and sets a non-zero exit; Command API errors
+ * print their diagnostic (help output was already rendered for ShowHelp).
+ * Anything past this boundary is a defect.
+ */
+export const reportErrors = (program, verbose) => program.pipe(Effect.catchTag("MotionCliError", (error) => Effect.gen(function* () {
+    yield* Console.error(renderForTerminal(error, verbose));
+    process.exitCode = 1;
+    return undefined;
+})), Effect.catchIf(CliError.isCliError, (error) => error._tag === "ShowHelp"
+    ? Effect.succeed(undefined)
+    : Effect.gen(function* () {
+        yield* Console.error(error.message);
+        process.exitCode = 1;
+        return undefined;
+    })));

package/dist/pins.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Exact versions a scaffolded project is pinned to — derived from this
+ * scaffolder build's own package.json so they can never go stale. All
+ * publishable packages release in lockstep (the changesets `fixed` group),
+ * so this package's own version IS the pin for the others. The effect pin
+ * is a determinism invariant (upgrading effect can change seeded random
+ * sequences), so scaffolds never use ranges or `latest`.
+ */
+/** This scaffolder's own version (also the lockstep version of every pin). */
+export declare const VERSION: string;
+export declare const PINS: {
+    readonly effect: string;
+    readonly "effect-motion": string;
+    readonly "@effect-motion/react": string;
+    readonly "@effect-motion/export": string;
+    readonly "@effect-motion/cli": string;
+};
+/** Non-determinism-critical companions; ranges are fine here. */
+export declare const COMPANIONS: {
+    readonly "@biomejs/biome": "^2.5.3";
+    readonly react: "^19.2.0";
+    readonly "react-dom": "^19.2.0";
+    readonly typescript: "^7.0.2";
+    readonly "@types/react": "^19.2.0";
+    readonly "@types/react-dom": "^19.2.0";
+    readonly "@types/node": "^26.1.1";
+};

package/dist/pins.js

@@ -0,0 +1,29 @@
+import { readFileSync } from "node:fs";
+const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+/**
+ * Exact versions a scaffolded project is pinned to — derived from this
+ * scaffolder build's own package.json so they can never go stale. All
+ * publishable packages release in lockstep (the changesets `fixed` group),
+ * so this package's own version IS the pin for the others. The effect pin
+ * is a determinism invariant (upgrading effect can change seeded random
+ * sequences), so scaffolds never use ranges or `latest`.
+ */
+/** This scaffolder's own version (also the lockstep version of every pin). */
+export const VERSION = pkg.version;
+export const PINS = {
+    effect: pkg.dependencies.effect,
+    "effect-motion": pkg.version,
+    "@effect-motion/react": pkg.version,
+    "@effect-motion/export": pkg.version,
+    "@effect-motion/cli": pkg.version,
+};
+/** Non-determinism-critical companions; ranges are fine here. */
+export const COMPANIONS = {
+    "@biomejs/biome": "^2.5.3",
+    react: "^19.2.0",
+    "react-dom": "^19.2.0",
+    typescript: "^7.0.2",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "@types/node": "^26.1.1",
+};

package/dist/scaffold.d.ts

@@ -0,0 +1,23 @@
+import * as Effect from "effect/Effect";
+import { FileSystem } from "effect/FileSystem";
+import { Path } from "effect/Path";
+import { MotionCliError } from "./MotionCliError.js";
+/**
+ * The non-interactive core of the scaffolder: everything except the prompts,
+ * so tests can drive it directly. Copies templates/default into the target
+ * directory and generates package.json from the pinned versions.
+ */
+/** Directory of the shipped templates (dist/scaffold.js → ../templates). */
+export declare const templatesDir: (path: Path) => string;
+/** `.` means "here"; the project is named after the resolved directory. */
+export declare const resolveProjectDir: (path: Path, cwd: string, input: string) => {
+    dir: string;
+    name: string;
+};
+/** Non-empty means anything but dotfiles (a fresh `git init` is fine). */
+export declare const ensureEmptyDir: (dir: string) => Effect.Effect<undefined, MotionCliError, FileSystem>;
+export type ScaffoldOptions = {
+    readonly biome: boolean;
+};
+/** Copy the template tree + write the generated package.json (+ biome.json). */
+export declare const scaffoldProject: (dir: string, name: string, options: ScaffoldOptions) => Effect.Effect<void, MotionCliError, FileSystem | Path>;

package/dist/scaffold.js

@@ -0,0 +1,116 @@
+import * as Effect from "effect/Effect";
+import { FileSystem } from "effect/FileSystem";
+import { Path } from "effect/Path";
+import { MotionCliError } from "./MotionCliError.js";
+import { COMPANIONS, PINS } from "./pins.js";
+/**
+ * The non-interactive core of the scaffolder: everything except the prompts,
+ * so tests can drive it directly. Copies templates/default into the target
+ * directory and generates package.json from the pinned versions.
+ */
+/** Directory of the shipped templates (dist/scaffold.js → ../templates). */
+export const templatesDir = (path) => path.join(path.dirname(new URL(import.meta.url).pathname), "..", "templates", "default");
+/** `.` means "here"; the project is named after the resolved directory. */
+export const resolveProjectDir = (path, cwd, input) => {
+    const dir = path.resolve(cwd, input);
+    return { dir, name: path.basename(dir) };
+};
+/** Non-empty means anything but dotfiles (a fresh `git init` is fine). */
+export const ensureEmptyDir = (dir) => Effect.gen(function* () {
+    const fs = yield* FileSystem;
+    if (!(yield* fs.exists(dir)))
+        return;
+    const entries = yield* fs.readDirectory(dir);
+    const meaningful = entries.filter((entry) => !entry.startsWith("."));
+    if (meaningful.length > 0) {
+        return yield* new MotionCliError({
+            reason: "ScaffoldTargetNotEmpty",
+            message: `${dir} is not empty (found ${meaningful.slice(0, 3).join(", ")}${meaningful.length > 3 ? ", …" : ""}) — choose an empty or new directory`,
+        });
+    }
+}).pipe(wrapFsError("ScaffoldFailed", `could not inspect ${dir}`));
+const wrapFsError = (reason, message) => (effect) => Effect.mapError(effect, (cause) => cause instanceof MotionCliError
+    ? cause
+    : new MotionCliError({ reason, message, cause }));
+const packageJson = (name, options) => `${JSON.stringify({
+    name,
+    private: true,
+    version: "0.0.0",
+    type: "module",
+    scripts: {
+        studio: "motion studio",
+        render: "motion render",
+        ...(options.biome
+            ? { lint: "biome check .", "lint:fix": "biome check --fix ." }
+            : {}),
+    },
+    dependencies: {
+        "@effect-motion/export": PINS["@effect-motion/export"],
+        "@effect-motion/react": PINS["@effect-motion/react"],
+        effect: PINS.effect,
+        "effect-motion": PINS["effect-motion"],
+        react: COMPANIONS.react,
+        "react-dom": COMPANIONS["react-dom"],
+    },
+    devDependencies: {
+        ...(options.biome
+            ? { "@biomejs/biome": COMPANIONS["@biomejs/biome"] }
+            : {}),
+        "@effect-motion/cli": PINS["@effect-motion/cli"],
+        "@types/node": COMPANIONS["@types/node"],
+        "@types/react": COMPANIONS["@types/react"],
+        "@types/react-dom": COMPANIONS["@types/react-dom"],
+        typescript: COMPANIONS.typescript,
+    },
+}, null, "\t")}\n`;
+// Formatter settings must match how the template files are formatted (tabs,
+// double quotes) so a fresh scaffold passes `biome check` with no diagnostics.
+const biomeJson = `${JSON.stringify({
+    $schema: "https://biomejs.dev/schemas/2.5.3/schema.json",
+    vcs: { enabled: true, clientKind: "git", useIgnoreFile: true },
+    files: { ignoreUnknown: true },
+    formatter: { enabled: true, indentStyle: "tab" },
+    linter: {
+        enabled: true,
+        rules: {
+            preset: "recommended",
+            // a scene with no animation yet is a generator without yield
+            correctness: { useYield: "off" },
+        },
+    },
+    javascript: { formatter: { quoteStyle: "double" } },
+    assist: {
+        enabled: true,
+        actions: { source: { organizeImports: "on" } },
+    },
+}, null, "\t")}\n`;
+/** Copy the template tree + write the generated package.json (+ biome.json). */
+export const scaffoldProject = (dir, name, options) => Effect.gen(function* () {
+    const fs = yield* FileSystem;
+    const path = yield* Path;
+    const templates = templatesDir(path);
+    yield* fs.makeDirectory(dir, { recursive: true });
+    yield* copyTree(fs, path, templates, dir);
+    // npm mangles nested .gitignore/package.json files in published
+    // tarballs, so both ship outside the template tree
+    yield* fs.writeFileString(path.join(dir, "package.json"), packageJson(name, options));
+    if (options.biome) {
+        yield* fs.writeFileString(path.join(dir, "biome.json"), biomeJson);
+    }
+    yield* fs.rename(path.join(dir, "_gitignore"), path.join(dir, ".gitignore"));
+}).pipe(wrapFsError("ScaffoldFailed", `could not scaffold ${dir}`));
+const copyTree = (fs, path, from, to) => Effect.gen(function* () {
+    const entries = yield* fs.readDirectory(from);
+    for (const entry of entries) {
+        const src = path.join(from, entry);
+        const dst = path.join(to, entry);
+        const info = yield* fs.stat(src);
+        if (info.type === "Directory") {
+            yield* fs.makeDirectory(dst, { recursive: true });
+            yield* copyTree(fs, path, src, dst);
+        }
+        else {
+            yield* fs.copyFile(src, dst);
+        }
+    }
+});

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "create-effect-motion",
+  "version": "0.4.0",
+  "description": "Scaffold a new effect-motion project — run with `pnpm create effect-motion` (or npm/yarn/bun create)",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/julia-script/effect-motion.git",
+    "directory": "packages/create-effect-motion"
+  },
+  "homepage": "https://github.com/julia-script/effect-motion#readme",
+  "bugs": "https://github.com/julia-script/effect-motion/issues",
+  "keywords": [
+    "effect",
+    "motion",
+    "create",
+    "scaffold",
+    "template",
+    "motion-graphics"
+  ],
+  "bin": {
+    "create-effect-motion": "./dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "dependencies": {
+    "@effect/platform-node": "4.0.0-beta.98",
+    "effect": "4.0.0-beta.98"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.3",
+    "@types/node": "^26.1.1",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch --preserveWatchOutput",
+    "test": "vitest run",
+    "check": "tsc --noEmit"
+  }
+}

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"]
+}