@effect-motion/cli 0.3.2 → 0.5.0

package/README.md

@@ -1,32 +1,14 @@
 # @effect-motion/cli
 
-Command line for [effect-motion](https://github.com/julia-script/effect-motion): scaffold a project, preview scenes in the browser, render videos — all driven by one `motion.config.ts`.
+Command line for [effect-motion](https://github.com/julia-script/effect-motion): preview scenes in the browser and render videos — all driven by one `motion.config.ts`.
 
 ```sh
-npx @effect-motion/cli init    # scaffold a project
+pnpm create effect-motion      # scaffold a project (npm/yarn/bun create work too)
 motion studio                  # preview scenes with hot reload
 motion render                  # render every target to MP4
 ```
 
-## init
-
-`motion init [directory]` scaffolds a single-project workspace:
-
-```
-my-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
-├─ package.json               # EXACT pins of effect-motion + effect
-└─ tsconfig.json
-```
-
-Answering `.` scaffolds into the current directory and names the project after it. The package-manager prompt defaults to whichever manager invoked the CLI; `--pm <pnpm|npm|yarn|bun>` and `--no-install` skip prompts/install.
-
-Dependency versions are pinned **exactly** — the `effect` pin is a determinism invariant (upgrading effect can change seeded random sequences), so upgrade both together, deliberately.
+Scaffolding lives in the [`create-effect-motion`](https://www.npmjs.com/package/create-effect-motion) package — this CLI is installed as a devDependency of the projects it creates.
 
 ## motion.config.ts
 

package/dist/MotionCliError.d.ts

@@ -4,7 +4,7 @@
  * signature; adding a failure mode is a union-member addition handled
  * exhaustively at exactly one place (the top-level reporter in bin.ts).
  */
-export type MotionCliReason = "ConfigNotFound" | "ConfigInvalid" | "SceneLoadFailed" | "UnknownTarget" | "ScaffoldTargetNotEmpty" | "ScaffoldFailed" | "InstallFailed" | "RenderFailed" | "StudioFailed";
+export type MotionCliReason = "ConfigNotFound" | "ConfigInvalid" | "SceneLoadFailed" | "UnknownTarget" | "RenderFailed" | "StudioFailed";
 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>;

package/dist/StudioConfig.d.ts

@@ -0,0 +1,71 @@
+import type { PlayerProps } from "@effect-motion/react";
+import type * as Layer from "effect/Layer";
+import * as Scene from "effect-motion/Scene";
+/**
+ * The `studio.ts` contract. This module is intentionally browser-safe (the
+ * studio app imports the user's entrypoint — and this module's helpers —
+ * directly), so it must stay free of Node-only imports.
+ *
+ * A studio entrypoint default-exports `studioConfig({ scenes, layers })`:
+ * a RECORD of scenes (keys are the unique picker identifiers) and ONE
+ * `layers` covering the union of every registered scene's resource
+ * requirements. The record is the registration — there is no glob; every
+ * scene lives in this file's import graph, which is what makes plain Vite
+ * HMR cover scene add/edit/remove.
+ */
+export declare const StudioConfigTypeId: "~effect-motion/cli/StudioConfig";
+/**
+ * The `PlayerProps` preview subset a studio entry may set — typed against
+ * the REAL props (no hand-copied mirror): drift in the Player's API is a
+ * compile error here, not a silent mismatch.
+ */
+export type PlayerOptions = Pick<PlayerProps, "fps" | "autoPlay" | "defaultRepeatMode" | "isInfinite" | "prebufferedFrames" | "bufferCapacity" | "settings">;
+/** A registration: a bare scene, or a scene with per-entry player options. */
+export type StudioEntry = Scene.AnyScene | ({
+    readonly scene: Scene.AnyScene;
+} & PlayerOptions);
+type EntryScene<V> = V extends {
+    readonly scene: infer S;
+} ? S : V;
+/**
+ * The union of loader requirements across every registered scene —
+ * `Scene.Resources` distributes over the record's value union, so one
+ * `layers` field covers the whole studio (preload-all-provided,
+ * studio-wide: switching scenes never waits on a fetch).
+ */
+export type EntriesResources<Entries extends Record<string, StudioEntry>> = Scene.Resources<Extract<EntryScene<Entries[keyof Entries]>, Scene.AnyScene>>;
+export interface StudioConfig {
+    readonly [StudioConfigTypeId]: typeof StudioConfigTypeId;
+    readonly scenes: Record<string, StudioEntry>;
+    readonly layers?: Layer.Layer<never, unknown, never>;
+}
+/**
+ * Identity helper that types (and brands) a `studio.ts` default export.
+ * `layers` is REQUIRED when any registered scene carries loader
+ * requirements — a registered scene whose loader is missing from `layers`
+ * fails compilation naming the loader — and FORBIDDEN when none do.
+ */
+export declare const studioConfig: <const Entries extends Record<string, StudioEntry>>(config: {
+    readonly scenes: Entries;
+} & ([EntriesResources<Entries>] extends [never] ? {
+    readonly layers?: never;
+} : {
+    readonly layers: Layer.Layer<EntriesResources<Entries>, unknown, never>;
+})) => StudioConfig;
+/** A normalized entry, ready for the studio picker. */
+export interface ResolvedEntry {
+    /** the record key — the entry's unique identity */
+    readonly key: string;
+    /** picker label: the scene's display name, else the key */
+    readonly label: string;
+    readonly scene: Scene.AnyScene;
+    readonly options: PlayerOptions;
+}
+export declare const isStudioConfig: (value: unknown) => value is StudioConfig;
+/**
+ * Validate a loaded entrypoint's default export and normalize its entries.
+ * Guards the untyped escape hatches (JS entrypoints, `as any`) — errors
+ * name the file and the offending key.
+ */
+export declare const resolveEntries: (value: unknown, filePath: string) => ReadonlyArray<ResolvedEntry>;
+export {};

package/dist/StudioConfig.js

@@ -0,0 +1,76 @@
+import * as Scene from "effect-motion/Scene";
+import { MotionCliError } from "./MotionCliError.js";
+/**
+ * The `studio.ts` contract. This module is intentionally browser-safe (the
+ * studio app imports the user's entrypoint — and this module's helpers —
+ * directly), so it must stay free of Node-only imports.
+ *
+ * A studio entrypoint default-exports `studioConfig({ scenes, layers })`:
+ * a RECORD of scenes (keys are the unique picker identifiers) and ONE
+ * `layers` covering the union of every registered scene's resource
+ * requirements. The record is the registration — there is no glob; every
+ * scene lives in this file's import graph, which is what makes plain Vite
+ * HMR cover scene add/edit/remove.
+ */
+export const StudioConfigTypeId = "~effect-motion/cli/StudioConfig";
+/**
+ * Identity helper that types (and brands) a `studio.ts` default export.
+ * `layers` is REQUIRED when any registered scene carries loader
+ * requirements — a registered scene whose loader is missing from `layers`
+ * fails compilation naming the loader — and FORBIDDEN when none do.
+ */
+export const studioConfig = (config) => ({
+    [StudioConfigTypeId]: StudioConfigTypeId,
+    ...config,
+});
+const isScene = (value) => typeof value === "object" && value !== null && Scene.TypeId in value;
+export const isStudioConfig = (value) => typeof value === "object" && value !== null && StudioConfigTypeId in value;
+/**
+ * Validate a loaded entrypoint's default export and normalize its entries.
+ * Guards the untyped escape hatches (JS entrypoints, `as any`) — errors
+ * name the file and the offending key.
+ */
+export const resolveEntries = (value, filePath) => {
+    const fail = (problem) => {
+        throw new MotionCliError({
+            reason: "ConfigInvalid",
+            message: `${filePath}: ${problem}`,
+        });
+    };
+    if (!isStudioConfig(value)) {
+        return fail("default export is not a studio config (did you forget `export default studioConfig({ scenes: { ... } })`?)");
+    }
+    if (typeof value.scenes !== "object" || value.scenes === null) {
+        return fail("studio config has no `scenes` record");
+    }
+    const entries = [];
+    for (const [key, entry] of Object.entries(value.scenes)) {
+        if (isScene(entry)) {
+            entries.push({
+                key,
+                label: entry.name ?? key,
+                scene: entry,
+                options: {},
+            });
+            continue;
+        }
+        if (typeof entry === "object" &&
+            entry !== null &&
+            "scene" in entry &&
+            isScene(entry.scene)) {
+            const { scene, ...options } = entry;
+            entries.push({
+                key,
+                label: scene.name ?? key,
+                scene,
+                options: options,
+            });
+            continue;
+        }
+        return fail(`scenes["${key}"] is neither a scene nor a \`{ scene, ...playerOptions }\` entry`);
+    }
+    if (entries.length === 0) {
+        return fail("studio config registers no scenes");
+    }
+    return entries;
+};

package/dist/cli.d.ts

@@ -2,7 +2,7 @@ import * as Effect from "effect/Effect";
 import { CliError, Command } from "effect/unstable/cli";
 import { type MotionCliError } from "./MotionCliError.js";
 export declare const rootCommand: Command.Command<"motion", {}, {}, MotionCliError, never>;
-export declare const CLI_VERSION: "0.1.0";
+export declare const CLI_VERSION: string;
 /**
  * The single exhaustive failure boundary (design D3a): MotionCliError
  * prints its message (cause chain under --verbose) and sets a non-zero

package/dist/cli.js

@@ -1,18 +1,17 @@
+import { readFileSync } from "node:fs";
 import * as Console from "effect/Console";
 import * as Effect from "effect/Effect";
 import { CliError, Command, Flag, GlobalFlag } from "effect/unstable/cli";
-import { initCommand } from "./commands/init.js";
 import { renderCommand } from "./commands/render.js";
 import { studioCommand } from "./commands/studio.js";
 import { renderForTerminal } from "./MotionCliError.js";
-import { PINS } from "./pins.js";
 // 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("motion").pipe(Command.withDescription("effect-motion: scaffold projects, preview scenes, render videos"), Command.withSubcommands([initCommand, studioCommand, renderCommand]), Command.withGlobalFlags([verboseFlag]));
-export const CLI_VERSION = PINS["@effect-motion/cli"];
+export const rootCommand = Command.make("motion").pipe(Command.withDescription("effect-motion: preview scenes and render videos (scaffold new projects with `pnpm create effect-motion`)"), Command.withSubcommands([studioCommand, renderCommand]), Command.withGlobalFlags([verboseFlag]));
+export const CLI_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 /**
  * The single exhaustive failure boundary (design D3a): MotionCliError
  * prints its message (cause chain under --verbose) and sets a non-zero

package/dist/commands/render.d.ts

@@ -4,15 +4,5 @@ import { Path } from "effect/Path";
 import { Command } from "effect/unstable/cli";
 import { MotionCliError } from "../MotionCliError.js";
 export declare const renderCommand: Command.Command<"render", {
-    readonly config: Option.Option<string>;
-    readonly width: Option.Option<number>;
-    readonly height: Option.Option<number>;
-    readonly fps: Option.Option<number>;
-    readonly dpr: Option.Option<number>;
-    readonly seed: Option.Option<string>;
-    readonly maxFrames: Option.Option<number>;
-    readonly frames: Option.Option<number>;
-    readonly outDir: Option.Option<string>;
-    readonly format: Option.Option<"mp4">;
-    readonly targets: readonly string[];
-}, {}, MotionCliError, import("effect/unstable/process/ChildProcessSpawner").ChildProcessSpawner | FileSystem | Path>;
+    readonly file: Option.Option<string>;
+}, {}, MotionCliError, FileSystem | Path>;

package/dist/commands/render.js

@@ -1,159 +1,61 @@
-import { Video } from "@effect-motion/export";
 import * as Console from "effect/Console";
 import * as Effect from "effect/Effect";
 import { FileSystem } from "effect/FileSystem";
 import * as Option from "effect/Option";
 import { Path } from "effect/Path";
-import * as Result from "effect/Result";
-import { Argument, Command, Flag } from "effect/unstable/cli";
-import { DEFAULT_OUTPUT_DIR, resolveTarget, } from "../Config.js";
-import { findConfig, loadConfig } from "../ConfigLoader.js";
+import { Argument, Command } from "effect/unstable/cli";
 import { MotionCliError } from "../MotionCliError.js";
 import { makeViteLoader } from "../ViteLoader.js";
-const opt = (o) => Option.getOrUndefined(o);
-const renderFlags = {
-    config: Flag.optional(Flag.string("config").pipe(Flag.withDescription("Path to a motion.config.ts (tsc -p style)"))),
-    width: Flag.optional(Flag.integer("width")),
-    height: Flag.optional(Flag.integer("height")),
-    fps: Flag.optional(Flag.integer("fps").pipe(Flag.withDescription("Frame rate override"))),
-    dpr: Flag.optional(Flag.float("dpr").pipe(Flag.withDescription("Supersampling factor (output pixels = scene × dpr)"))),
-    seed: Flag.optional(Flag.string("seed")),
-    maxFrames: Flag.optional(Flag.integer("max-frames")),
-    frames: Flag.optional(Flag.integer("frames").pipe(Flag.withDescription("Cap encoded frames (required for infinite scenes)"))),
-    outDir: Flag.optional(Flag.string("out-dir").pipe(Flag.withDescription("Output directory override"))),
-    format: Flag.optional(Flag.choice("format", ["mp4"])),
-    targets: Argument.string("targets").pipe(Argument.withDescription("Target names from the config, or one scene file path"), Argument.variadic()),
+/**
+ * `motion render [file]` — execute a render entrypoint.
+ *
+ * The entrypoint is an ordinary program: it calls `Video.render(scene, out,
+ * options)` and provides the scene's loader layers itself, so loader
+ * coverage is a compile-time property of the USER's file (`Video.render`'s
+ * own signature demands it). The CLI's job is thin: load the module through
+ * the shared Vite pipeline, run its default-exported Effect against the
+ * platform services bin.ts provides (ChildProcessSpawner included), and
+ * render failures as CLI errors. The same file runs without the CLI by
+ * self-providing `NodeServices` (documented in `@effect-motion/export`).
+ */
+const renderArgs = {
+    file: Argument.optional(Argument.string("file").pipe(Argument.withDescription("Render entrypoint (default ./render.ts) — a module default-exporting an Effect"))),
 };
-const overridesFrom = (input) => {
-    const raw = {
-        width: opt(input.width),
-        height: opt(input.height),
-        frameRate: opt(input.fps),
-        dpr: opt(input.dpr),
-        seed: opt(input.seed),
-        maxFrames: opt(input.maxFrames),
-        frames: opt(input.frames),
-        outDir: opt(input.outDir),
-        format: opt(input.format),
-    };
-    return Object.fromEntries(Object.entries(raw).filter(([, v]) => v !== undefined));
-};
-// a positional is a scene file (configless mode) iff it looks like a module
-// path — target names never carry an extension
-const isSceneFile = (arg) => /\.(ts|tsx|mts|js|mjs)$/.test(arg);
-const sceneBasename = (file) => {
-    const base = file.split("/").at(-1) ?? file;
-    return base.replace(/\.(ts|tsx|mts|js|mjs)$/, "");
-};
-/** Map a resolved target onto the export package's options shape. */
-const toVideoOptions = (target) => {
-    const { dpr, ...settings } = target.settings;
-    return {
-        // ponytail: VideoSceneSettings doesn't name seed/backgroundColor, but
-        // Video.render passes settings straight through to Scene.stream — the
-        // cast is the CLI-side adaptation decided in design D2; collapse it if
-        // the export package ever widens its settings type
-        settings: settings,
-        ...(dpr !== undefined ? { dpr } : {}),
-        ...(target.frames !== undefined ? { frames: target.frames } : {}),
-    };
-};
-const renderOne = (loader, baseDir, target) => Effect.gen(function* () {
+const handler = (input) => Effect.gen(function* () {
     const path = yield* Path;
     const fs = yield* FileSystem;
-    const sceneAbs = path.isAbsolute(target.scene)
-        ? target.scene
-        : path.resolve(baseDir, target.scene);
-    const module_ = yield* loader.load(sceneAbs);
-    const scene = module_.scene;
-    if (scene === undefined) {
+    const cwd = process.cwd();
+    const requested = Option.getOrElse(input.file, () => "./render.ts");
+    const entryAbs = path.isAbsolute(requested)
+        ? requested
+        : path.resolve(cwd, requested);
+    if (!(yield* Effect.orDie(fs.exists(entryAbs)))) {
         return yield* new MotionCliError({
-            reason: "SceneLoadFailed",
-            message: `${sceneAbs} has no \`scene\` export`,
+            reason: "ConfigNotFound",
+            message: `no render entrypoint at ${requested} — create a render.ts that ` +
+                "default-exports a `Video.render(...)` effect (loader layers provided), " +
+                "or pass a path: `motion render ./my.render.ts`",
         });
     }
-    const outDirAbs = path.resolve(baseDir, target.outDir);
-    yield* fs.makeDirectory(outDirAbs, { recursive: true }).pipe(Effect.mapError((cause) => new MotionCliError({
-        reason: "RenderFailed",
-        message: `could not create output directory ${outDirAbs}`,
-        cause,
-    })));
-    const outFile = path.join(outDirAbs, target.fileName);
-    yield* Video.render(scene, outFile, toVideoOptions(target)).pipe(Effect.mapError((cause) => new MotionCliError({
+    const loader = yield* makeViteLoader(path.dirname(entryAbs));
+    const module_ = yield* loader.load(entryAbs);
+    const program = module_.default;
+    if (!Effect.isEffect(program)) {
+        return yield* new MotionCliError({
+            reason: "ConfigInvalid",
+            message: `${entryAbs}: default export is not an Effect — a render entrypoint ` +
+                'default-exports its render program (e.g. `export default Video.render(scene, "output/out.mp4").pipe(Effect.provide(layers))`)',
+        });
+    }
+    // run against the handler's own context (bin.ts provides the Node
+    // platform services). An effect requiring anything beyond them fails
+    // here with Effect's named missing-service defect — the loader half of
+    // the contract was already enforced in the user's file at compile time.
+    yield* program.pipe(Effect.mapError((cause) => new MotionCliError({
         reason: "RenderFailed",
-        message: `target "${target.name}" failed to render (${sceneAbs})`,
+        message: `render entrypoint failed (${entryAbs})`,
         cause,
     })));
-    return outFile;
-});
-const handler = (input) => Effect.gen(function* () {
-    const path = yield* Path;
-    const cwd = process.cwd();
-    const overrides = overridesFrom(input);
-    // resolve the target list and the directory paths are relative to
-    let baseDir;
-    let resolved;
-    const [first] = input.targets;
-    if (first !== undefined &&
-        input.targets.length === 1 &&
-        isSceneFile(first)) {
-        // configless mode: one scene file, library defaults + flags
-        baseDir = cwd;
-        resolved = [
-            resolveTarget({
-                name: sceneBasename(first),
-                scene: path.resolve(cwd, first),
-                output: DEFAULT_OUTPUT_DIR,
-            }, overrides),
-        ];
-    }
-    else {
-        const configPath = yield* findConfig(cwd, opt(input.config));
-        baseDir = path.dirname(configPath);
-        const loader = yield* makeViteLoader(baseDir);
-        const config = yield* loadConfig(loader, configPath);
-        if (input.targets.length === 0) {
-            resolved = config.targets.map((t) => resolveTarget(t, overrides));
-        }
-        else {
-            const known = new Map(config.targets.map((t) => [t.name, t]));
-            const unknown = input.targets.filter((name) => !known.has(name));
-            if (unknown.length > 0) {
-                return yield* new MotionCliError({
-                    reason: "UnknownTarget",
-                    message: `unknown target${unknown.length > 1 ? "s" : ""} ${unknown.join(", ")} — ` +
-                        `known targets: ${[...known.keys()].join(", ") || "(none)"}`,
-                });
-            }
-            resolved = input.targets.map((name) => 
-            // biome-ignore lint/style/noNonNullAssertion: membership checked above
-            resolveTarget(known.get(name), overrides));
-        }
-        return yield* execute(loader, baseDir, resolved);
-    }
-    const loader = yield* makeViteLoader(baseDir);
-    return yield* execute(loader, baseDir, resolved);
+    yield* Console.log(`rendered ${requested}`);
 }).pipe(Effect.scoped);
-// render sequentially: ffmpeg already saturates the CPU per target
-// (ponytail: parallelize only if profiling ever says otherwise)
-const execute = (loader, baseDir, targets) => Effect.gen(function* () {
-    const failures = [];
-    for (const target of targets) {
-        const result = yield* Effect.result(renderOne(loader, baseDir, target));
-        if (Result.isSuccess(result)) {
-            yield* Console.log(`✓ ${target.name} → ${result.success}`);
-        }
-        else {
-            failures.push(result.failure);
-            yield* Console.error(`✗ ${target.name}: ${result.failure.message}`);
-        }
-    }
-    if (failures.length > 0) {
-        return yield* new MotionCliError({
-            reason: "RenderFailed",
-            message: `${failures.length} of ${targets.length} target${targets.length > 1 ? "s" : ""} failed`,
-            cause: failures[0],
-        });
-    }
-});
-export const renderCommand = Command.make("render", renderFlags, handler).pipe(Command.withDescription("Render targets from motion.config.ts (or one scene file) to video"));
+export const renderCommand = Command.make("render", renderArgs, handler).pipe(Command.withDescription("Execute a render entrypoint (default ./render.ts) with the platform provided"));

package/dist/commands/studio.d.ts

@@ -4,7 +4,7 @@ import { Path } from "effect/Path";
 import { Command } from "effect/unstable/cli";
 import { MotionCliError } from "../MotionCliError.js";
 export declare const studioCommand: Command.Command<"studio", {
-    readonly config: Option.Option<string>;
+    readonly file: Option.Option<string>;
     readonly port: Option.Option<number>;
     readonly host: Option.Option<string>;
 }, {}, MotionCliError, FileSystem | Path>;

package/dist/commands/studio.js

@@ -3,31 +3,52 @@ import * as Effect from "effect/Effect";
 import { FileSystem } from "effect/FileSystem";
 import * as Option from "effect/Option";
 import { Path } from "effect/Path";
-import * as Result from "effect/Result";
-import { Command, Flag } from "effect/unstable/cli";
-import { findConfig } from "../ConfigLoader.js";
+import { Argument, Command, Flag } from "effect/unstable/cli";
 import { MotionCliError } from "../MotionCliError.js";
-const studioFlags = {
-    config: Flag.optional(Flag.string("config")),
+const studioArgs = {
+    file: Argument.optional(Argument.string("file").pipe(Argument.withDescription("Studio entrypoint (default ./studio.ts) — a module default-exporting studioConfig({ scenes, layers })"))),
     port: Flag.optional(Flag.integer("port")),
     host: Flag.optional(Flag.string("host")),
 };
 /** Shipped studio app source (dist/commands/studio.js → ../../studio-app). */
 const studioAppSource = (path) => path.join(path.dirname(new URL(import.meta.url).pathname), "..", "..", "studio-app");
+/** Built CLI modules the app imports at runtime (dist/commands → dist). */
+const distSource = (path) => path.join(path.dirname(new URL(import.meta.url).pathname), "..");
 // The studio app is copied INTO the project (.motion/studio) so its bare
-// imports (react, @effect-motion/react, the config's own imports) resolve
-// against the project's node_modules — the same graph render uses. The
-// generated project.ts pins the project root for /@fs imports.
-const prepareStudioDir = (projectRoot) => Effect.gen(function* () {
+// imports (react, @effect-motion/react, the entrypoint's own imports)
+// resolve against the project's node_modules — the same graph render uses.
+// The StudioConfig contract module (and its error dependency) are copied
+// from the CLI's own build so the app and the CLI share ONE brand and one
+// entry-normalization implementation. The generated entry.ts STATICALLY
+// imports the user's entrypoint through /@fs, which places the entire
+// scene graph inside Vite's module graph — ordinary HMR then covers scene
+// edits, additions, and removals with no bespoke watchers.
+const prepareStudioDir = (projectRoot, entryAbs) => Effect.gen(function* () {
     const fs = yield* FileSystem;
     const path = yield* Path;
     const source = studioAppSource(path);
+    const dist = distSource(path);
     const studioDir = path.join(projectRoot, ".motion", "studio");
     yield* fs.makeDirectory(studioDir, { recursive: true });
     for (const entry of yield* fs.readDirectory(source)) {
+        // the in-repo StudioConfig.ts is a typecheck stub re-exporting the
+        // CLI source; the built dist module replaces it below (a copied
+        // stub would shadow the .js in vite's resolution)
+        if (entry === "StudioConfig.ts") {
+            continue;
+        }
         yield* fs.copyFile(path.join(source, entry), path.join(studioDir, entry));
     }
-    yield* fs.writeFileString(path.join(studioDir, "project.ts"), `// generated by \`motion studio\` — do not edit\nexport const projectRoot = ${JSON.stringify(projectRoot)};\n`);
+    for (const module of ["StudioConfig.js", "MotionCliError.js"]) {
+        yield* fs.copyFile(path.join(dist, module), path.join(studioDir, module));
+    }
+    yield* fs.writeFileString(path.join(studioDir, "entry.ts"), [
+        "// generated by `motion studio` — do not edit",
+        `import config from "/@fs${entryAbs}";`,
+        `export const studioPath = ${JSON.stringify(entryAbs)};`,
+        "export default config;",
+        "",
+    ].join("\n"));
     return studioDir;
 }).pipe(Effect.mapError((cause) => cause instanceof MotionCliError
     ? cause
@@ -38,14 +59,23 @@ const prepareStudioDir = (projectRoot) => Effect.gen(function* () {
     })));
 const handler = (input) => Effect.gen(function* () {
     const path = yield* Path;
+    const fs = yield* FileSystem;
     const cwd = process.cwd();
-    // a config is optional for studio: unregistered scenes are previewable,
-    // so "no config" just means "project root = cwd"
-    const found = yield* Effect.result(findConfig(cwd, Option.getOrUndefined(input.config)));
-    const projectRoot = Result.isSuccess(found)
-        ? path.dirname(found.success)
-        : cwd;
-    const studioDir = yield* prepareStudioDir(projectRoot);
+    // no discovery walk: the entrypoint is an explicit (or default) path
+    const requested = Option.getOrElse(input.file, () => "./studio.ts");
+    const entryAbs = path.isAbsolute(requested)
+        ? requested
+        : path.resolve(cwd, requested);
+    if (!(yield* Effect.orDie(fs.exists(entryAbs)))) {
+        return yield* new MotionCliError({
+            reason: "ConfigNotFound",
+            message: `no studio entrypoint at ${requested} — create a studio.ts that ` +
+                "default-exports `studioConfig({ scenes: { ... } })`, or pass a path: " +
+                "`motion studio ./my.studio.ts`",
+        });
+    }
+    const projectRoot = path.dirname(entryAbs);
+    const studioDir = yield* prepareStudioDir(projectRoot, entryAbs);
     const server = yield* Effect.acquireRelease(Effect.tryPromise({
         try: async () => {
             const { createServer } = await import("vite");
@@ -61,35 +91,17 @@ const handler = (input) => Effect.gen(function* () {
                 resolve: {
                     dedupe: ["react", "react-dom", "effect", "effect-motion"],
                 },
-                plugins: [
-                    {
-                        name: "motion:project-watch",
-                        configureServer(server) {
-                            // the project lives OUTSIDE the vite root
-                            // (.motion/studio); vite's own add/unlink → glob
-                            // invalidation doesn't reach out-of-root dirs, so
-                            // scene add/remove refreshes the picker here
-                            // (ponytail: invalidateAll + full reload — coarse,
-                            // but studio-sized; narrow it if it ever matters)
-                            const onAddUnlink = (file) => {
-                                if (!file.startsWith(projectRoot))
-                                    return;
-                                server.moduleGraph.invalidateAll();
-                                server.ws.send({ type: "full-reload" });
-                            };
-                            server.watcher.on("add", onAddUnlink);
-                            server.watcher.on("unlink", onAddUnlink);
-                        },
-                    },
-                ],
+                // the studio app's JSX must not depend on the project's
+                // tsconfig — scaffolded projects set no `jsx`, and esbuild's
+                // fallback is the classic transform, which crashes with
+                // "React is not defined" before anything mounts
+                esbuild: { jsx: "automatic" },
             });
             await server.listen();
-            // out-of-root project files aren't watched by default — without
-            // this, editing a scene or the config would not hot reload
-            server.watcher.add([
-                `${projectRoot}/src`,
-                `${projectRoot}/motion.config.ts`,
-            ]);
+            // the project lives OUTSIDE the vite root (.motion/studio);
+            // watch it so edits to graph modules out of root hot-reload
+            // (vite's default ignores cover node_modules/.git)
+            server.watcher.add(projectRoot);
             return server;
         },
         catch: (cause) => new MotionCliError({
@@ -103,4 +115,4 @@ const handler = (input) => Effect.gen(function* () {
     // serve until interrupted (Ctrl-C) — teardown runs via the scope
     yield* Effect.never;
 }).pipe(Effect.scoped);
-export const studioCommand = Command.make("studio", studioFlags, handler).pipe(Command.withDescription("Preview scenes in the browser with hot reload (Player + scene picker)"));
+export const studioCommand = Command.make("studio", studioArgs, handler).pipe(Command.withDescription("Preview the scenes registered in a studio.ts entrypoint (Player + picker)"));

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { DEFAULT_FORMAT, DEFAULT_OUTPUT_DIR, defineConfig, type MotionConfig, type MotionTarget, type OutputFormat, type RenderOverrides, type ResolvedTarget, resolveTarget, type TargetSettings, validateConfig, } from "./Config.js";
 export { MotionCliError, type MotionCliReason } from "./MotionCliError.js";
+export { type EntriesResources, isStudioConfig, type PlayerOptions, type ResolvedEntry, resolveEntries, type StudioConfig, StudioConfigTypeId, type StudioEntry, studioConfig, } from "./StudioConfig.js";

package/dist/index.js

@@ -1,5 +1,5 @@
-// Public API: the config contract (imported by user motion.config.ts files
-// and the studio app, so this entry must stay browser-safe) and the error
-// type. The commands live behind the `motion` bin, not this entry.
-export { DEFAULT_FORMAT, DEFAULT_OUTPUT_DIR, defineConfig, resolveTarget, validateConfig, } from "./Config.js";
+// Public API: the studio entrypoint contract (imported by user studio.ts
+// files and the studio app, so this entry must stay browser-safe) and the
+// error type. The commands live behind the `motion` bin, not this entry.
 export { MotionCliError } from "./MotionCliError.js";
+export { isStudioConfig, resolveEntries, StudioConfigTypeId, studioConfig, } from "./StudioConfig.js";