@effect-motion/cli 0.4.0 → 0.5.0

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/commands/render.d.ts

@@ -4,13 +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 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,155 +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)"))),
-    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 = {
-        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");
@@ -66,35 +96,12 @@ const handler = (input) => Effect.gen(function* () {
                 // fallback is the classic transform, which crashes with
                 // "React is not defined" before anything mounts
                 esbuild: { jsx: "automatic" },
-                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);
-                        },
-                    },
-                ],
             });
             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({
@@ -108,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";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effect-motion/cli",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Command line for effect-motion: preview scenes with hot reload (studio) and render videos from motion.config.ts (render). Scaffold new projects with `pnpm create effect-motion`",
   "type": "module",
   "license": "MIT",
@@ -40,8 +40,8 @@
     "@effect/platform-node": "4.0.0-beta.98",
     "effect": "4.0.0-beta.98",
     "vite": "^7.0.0",
-    "@effect-motion/export": "^0.4.0",
-    "effect-motion": "^0.4.0"
+    "@effect-motion/export": "^0.5.0",
+    "effect-motion": "^0.5.0"
   },
   "devDependencies": {
     "@types/node": "^26.1.1",
@@ -51,7 +51,7 @@
     "react-dom": "^19.2.0",
     "typescript": "^7.0.2",
     "vitest": "^4.1.10",
-    "@effect-motion/react": "^0.4.0"
+    "@effect-motion/react": "^0.5.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",

package/studio-app/App.tsx

@@ -1,162 +1,68 @@
 import { Player, type PlayerProps } from "@effect-motion/react";
-import { useEffect, useMemo, useState } from "react";
-import { projectRoot } from "./project";
+import { useMemo, useState } from "react";
+// generated by `motion studio`: statically re-exports the user's studio.ts,
+// which places the entire scene graph in Vite's module graph (ordinary HMR
+// covers scene edits/additions/removals — no bespoke watchers)
+import studioModule, { studioPath } from "./entry";
+// the CLI's own contract module, copied beside the app at prepare time —
+// one brand, one entry-normalization implementation, shared with `motion`
+import {
+	type ResolvedEntry,
+	resolveEntries,
+	type StudioConfig,
+	StudioConfigTypeId,
+} from "./StudioConfig";
 
-// 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>;
-	readonly player?: Record<string, unknown>;
-};
-type ConfigLike = { readonly targets?: ReadonlyArray<TargetLike> };
-
-/** the PlayerProps subset a config's `player` block may set */
-type PlayerOptions = Pick<
-	PlayerProps,
-	| "autoPlay"
-	| "defaultRepeatMode"
-	| "isInfinite"
-	| "prebufferedFrames"
-	| "bufferCapacity"
-	| "fps"
->;
-
-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;
-	/** studio preview options from the target's `player` block */
-	readonly player: PlayerOptions | 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;
+// selection survives the full-page reloads that scene edits trigger
+const selectionFromHash = () =>
+	decodeURIComponent(window.location.hash.slice(1)) || null;
 
-const loadByAbsolutePath = (key: string) => () =>
-	import(/* @vite-ignore */ `/@fs${projectRoot}/${key}`);
+type Resolved =
+	| { readonly _tag: "ready"; readonly entries: ReadonlyArray<ResolvedEntry> }
+	| { readonly _tag: "error"; readonly message: string };
 
-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"],
-			player: target.player as PlayerOptions | undefined,
-			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,
-			player: undefined,
-			load,
-		});
+const resolve = (): Resolved => {
+	try {
+		return {
+			_tag: "ready",
+			entries: resolveEntries(studioModule, studioPath),
+		};
+	} catch (error) {
+		return {
+			_tag: "error",
+			message: error instanceof Error ? error.message : String(error),
+		};
 	}
-	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"];
-	  };
+// the config's layers cover the union of every registered scene's
+// resources (typed in the user's studio.ts); the dynamic boundary here is
+// backed by that authoring-time check
+const configLayers =
+	typeof studioModule === "object" &&
+	studioModule !== null &&
+	StudioConfigTypeId in studioModule
+		? (studioModule as StudioConfig).layers
+		: undefined;
 
 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" });
+	const resolved = useMemo(resolve, []);
 
-	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),
+	if (resolved._tag === "error") {
+		return (
+			<main className="studio-main">
+				<div className="studio-error">
+					<h2>Studio entrypoint failed to load</h2>
+					<pre>{resolved.message}</pre>
+				</div>
+			</main>
 		);
-	}, []);
+	}
 
-	const entries = useMemo(() => buildEntries(config), [config]);
+	const entries = resolved.entries;
 	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">
@@ -173,51 +79,40 @@ export const App = () => {
 						}}
 					>
 						{e.label}
-						<small>{e.registered ? e.path : `${e.path} (unregistered)`}</small>
+						{e.label !== e.key && <small>{e.key}</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" &&
+				{entry !== undefined &&
 					(() => {
-						// player.fps is a preview override of the scene's own rate,
+						// options.fps is a preview override of the scene's own rate,
 						// so it lands in settings.frameRate (the Player's one clock,
 						// which wins over its fps prop); everything else is a plain
 						// Player prop and wins over the studio defaults
-						const { fps, ...playerProps } = entry?.player ?? {};
+						const {
+							fps,
+							settings: entrySettings,
+							...playerProps
+						} = entry.options;
 						const settings =
 							fps !== undefined
-								? { ...entry?.settings, frameRate: fps }
-								: entry?.settings;
+								? { ...entrySettings, frameRate: fps }
+								: entrySettings;
 						return (
 							<Player
-								key={state.key}
-								scene={state.scene}
+								key={entry.key}
+								scene={entry.scene as PlayerProps["scene"] as never}
 								autoPlay
 								defaultRepeatMode
 								{...(settings !== undefined ? { settings } : {})}
+								{...(configLayers !== undefined
+									? { renderLayers: configLayers as never }
+									: {})}
 								{...playerProps}
 							/>
 						);
 					})()}
-				{(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/StudioConfig.ts

@@ -0,0 +1,5 @@
+// In-repo typecheck stub: re-exports the CLI's contract module. At prepare
+// time this file is NOT copied — the built dist/StudioConfig.js is placed
+// next to the app instead, so the app and CLI share one implementation
+// resolved against the user's project node_modules.
+export * from "../src/StudioConfig.js";

package/studio-app/entry.ts

@@ -0,0 +1,4 @@
+// OVERWRITTEN by `motion studio` at prepare time with a static /@fs import
+// of the user's studio entrypoint — this stub only types the app in-repo.
+export const studioPath = "";
+export default undefined as unknown;

package/dist/Config.d.ts

@@ -1,97 +0,0 @@
-import type * as Runner from "effect-motion/Runner";
-/**
- * The `motion.config.ts` contract. This module is intentionally
- * browser-safe (the studio app imports the user's config directly), so it
- * must stay free of Node-only imports — loading/discovery live in
- * ConfigLoader.ts.
- */
-/**
- * Per-target playback settings: the Runner `Settings` subset an export can
- * honor, plus `dpr` (mapped to the export package's supersampling option).
- * Resolution and background are NOT here — they are the scene's own
- * composition config, set in `Scene.make(gen, { width, height, backgroundColor })`.
- */
-export interface TargetSettings {
-    readonly frameRate?: number;
-    readonly seed?: Runner.Seed;
-    readonly maxFrames?: number;
-    readonly dpr?: number;
-}
-/**
- * Studio preview options for a target's Player — how the scene PLAYS in
- * `motion studio`, as opposed to `settings`, which is what the scene IS.
- * `motion render` ignores them. Field meanings match `PlayerProps` in
- * `@effect-motion/react`.
- */
-export interface PlayerOptions {
-    readonly autoPlay?: boolean;
-    /**
-     * Preview-only frame rate (the Player's `fps` prop) — wins over
-     * `settings.frameRate` in the studio (e.g. preview a heavy 60fps target
-     * at 30). The scene RUNS at this rate, so previewed frames are not the
-     * export's frames.
-     */
-    readonly fps?: number;
-    /** Initial repeat mode; the studio's repeat button toggles it after. */
-    readonly defaultRepeatMode?: boolean;
-    /** Declare a never-ending scene so the player windows its buffer. */
-    readonly isInfinite?: boolean;
-    readonly prebufferedFrames?: number;
-    readonly bufferCapacity?: number;
-}
-/** v1 ships MP4 only; the field exists so more containers slot in later. */
-export type OutputFormat = "mp4";
-export interface MotionTarget {
-    /** Unique per config — doubles as the output file basename. */
-    readonly name: string;
-    /** Path to a module exporting `scene`, relative to the config file. */
-    readonly scene: string;
-    readonly settings?: TargetSettings;
-    /** Studio-only: how this target previews (autoplay, repeat, …). */
-    readonly player?: PlayerOptions;
-    /** Output DIRECTORY (never a file), relative to the config file. */
-    readonly output?: string;
-    readonly format?: OutputFormat;
-    /** Frame cap — required in practice for an infinite scene. */
-    readonly frames?: number;
-}
-export interface MotionConfig {
-    readonly targets: ReadonlyArray<MotionTarget>;
-}
-/** Identity helper that types `motion.config.ts` (vite/vitest convention). */
-export declare const defineConfig: (config: MotionConfig) => MotionConfig;
-export declare const DEFAULT_OUTPUT_DIR = "./output";
-export declare const DEFAULT_FORMAT: OutputFormat;
-/**
- * Validate the default export of a loaded config module. Plain structural
- * checks (not Schema): the config is authored in TS against `MotionConfig`,
- * so this only guards the untyped escape hatches (JS configs, `as any`).
- */
-export declare const validateConfig: (value: unknown, configPath: string) => MotionConfig;
-/** Flag values a `motion render` invocation can lay over a target. */
-export interface RenderOverrides {
-    readonly frameRate?: number;
-    readonly dpr?: number;
-    readonly seed?: Runner.Seed;
-    readonly maxFrames?: number;
-    readonly frames?: number;
-    readonly outDir?: string;
-    readonly format?: OutputFormat;
-}
-/** A target with overrides applied and output location derived. */
-export interface ResolvedTarget {
-    readonly name: string;
-    readonly scene: string;
-    readonly settings: TargetSettings;
-    readonly frames: number | undefined;
-    /** Output directory (still config-relative — the caller resolves). */
-    readonly outDir: string;
-    /** Derived file name: `<name>.<format>` — never user-specified. */
-    readonly fileName: string;
-}
-/**
- * Precedence, highest wins: CLI flags → target config → library defaults.
- * Library defaults are NOT materialized here — leaving fields undefined
- * lets the Runner's own defaults apply, so there is one source of truth.
- */
-export declare const resolveTarget: (target: MotionTarget, overrides?: RenderOverrides) => ResolvedTarget;

package/dist/Config.js

@@ -1,67 +0,0 @@
-import { MotionCliError } from "./MotionCliError.js";
-/** Identity helper that types `motion.config.ts` (vite/vitest convention). */
-export const defineConfig = (config) => config;
-export const DEFAULT_OUTPUT_DIR = "./output";
-export const DEFAULT_FORMAT = "mp4";
-/**
- * Validate the default export of a loaded config module. Plain structural
- * checks (not Schema): the config is authored in TS against `MotionConfig`,
- * so this only guards the untyped escape hatches (JS configs, `as any`).
- */
-export const validateConfig = (value, configPath) => {
-    const fail = (problem) => {
-        throw new MotionCliError({
-            reason: "ConfigInvalid",
-            message: `${configPath}: ${problem}`,
-        });
-    };
-    if (typeof value !== "object" || value === null) {
-        return fail("default export is not a config object (did you forget `export default defineConfig({...})`?)");
-    }
-    const config = value;
-    if (!Array.isArray(config.targets)) {
-        return fail("config has no `targets` array");
-    }
-    const seen = new Set();
-    for (const [i, target] of config.targets.entries()) {
-        if (typeof target !== "object" || target === null) {
-            return fail(`targets[${i}] is not an object`);
-        }
-        if (typeof target.name !== "string" || target.name.length === 0) {
-            return fail(`targets[${i}] is missing a \`name\``);
-        }
-        if (typeof target.scene !== "string" || target.scene.length === 0) {
-            return fail(`target "${target.name}" is missing a \`scene\` path`);
-        }
-        if (seen.has(target.name)) {
-            return fail(`duplicate target name "${target.name}" (names double as output filenames, so they must be unique)`);
-        }
-        seen.add(target.name);
-        if (target.format !== undefined && target.format !== "mp4") {
-            return fail(`target "${target.name}" has unsupported format "${target.format}" (v1 supports "mp4")`);
-        }
-    }
-    return config;
-};
-const definedEntries = (obj) => Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined));
-/**
- * Precedence, highest wins: CLI flags → target config → library defaults.
- * Library defaults are NOT materialized here — leaving fields undefined
- * lets the Runner's own defaults apply, so there is one source of truth.
- */
-export const resolveTarget = (target, overrides = {}) => {
-    const { frames: overrideFrames, outDir, format, ...settingsOverrides } = overrides;
-    const settings = {
-        ...definedEntries(target.settings ?? {}),
-        ...definedEntries(settingsOverrides),
-    };
-    const resolvedFormat = format ?? target.format ?? DEFAULT_FORMAT;
-    return {
-        name: target.name,
-        scene: target.scene,
-        settings,
-        frames: overrideFrames ?? target.frames,
-        outDir: outDir ?? target.output ?? DEFAULT_OUTPUT_DIR,
-        fileName: `${target.name}.${resolvedFormat}`,
-    };
-};

package/dist/ConfigLoader.d.ts

@@ -1,15 +0,0 @@
-import * as Effect from "effect/Effect";
-import { FileSystem } from "effect/FileSystem";
-import { Path } from "effect/Path";
-import { type MotionConfig } from "./Config.js";
-import { MotionCliError } from "./MotionCliError.js";
-import type { ViteLoader } from "./ViteLoader.js";
-export declare const CONFIG_FILE = "motion.config.ts";
-/**
- * Resolve the config path: an explicit `--config` wins; otherwise walk up
- * from `cwd` to the nearest motion.config.ts (tsc `-p` semantics). Fails
- * with ConfigNotFound naming both escape hatches.
- */
-export declare const findConfig: (cwd: string, explicit?: string) => Effect.Effect<string, MotionCliError, FileSystem | Path>;
-/** Load + validate a config module through the shared Vite loader. */
-export declare const loadConfig: (loader: ViteLoader, configPath: string) => Effect.Effect<MotionConfig, MotionCliError>;

package/dist/ConfigLoader.js

@@ -1,58 +0,0 @@
-import * as Effect from "effect/Effect";
-import { FileSystem } from "effect/FileSystem";
-import { Path } from "effect/Path";
-import { validateConfig } from "./Config.js";
-import { MotionCliError } from "./MotionCliError.js";
-export const CONFIG_FILE = "motion.config.ts";
-/**
- * Resolve the config path: an explicit `--config` wins; otherwise walk up
- * from `cwd` to the nearest motion.config.ts (tsc `-p` semantics). Fails
- * with ConfigNotFound naming both escape hatches.
- */
-export const findConfig = (cwd, explicit) => Effect.gen(function* () {
-    const fs = yield* FileSystem;
-    const path = yield* Path;
-    if (explicit !== undefined) {
-        const resolved = path.resolve(cwd, explicit);
-        const exists = yield* orFalse(fs.exists(resolved));
-        if (!exists) {
-            return yield* new MotionCliError({
-                reason: "ConfigNotFound",
-                message: `config file not found: ${resolved}`,
-            });
-        }
-        return resolved;
-    }
-    let dir = path.resolve(cwd);
-    while (true) {
-        const candidate = path.join(dir, CONFIG_FILE);
-        if (yield* orFalse(fs.exists(candidate)))
-            return candidate;
-        const parent = path.dirname(dir);
-        if (parent === dir)
-            break;
-        dir = parent;
-    }
-    return yield* new MotionCliError({
-        reason: "ConfigNotFound",
-        message: `no ${CONFIG_FILE} found from ${cwd} upward — ` +
-            `create one (export default defineConfig({ targets: [...] })), pass --config <path>, ` +
-            `or pass a scene file directly (motion render ./src/scenes/foo.ts)`,
-    });
-});
-// fs.exists fails on permission errors etc. — treat those as "not here"
-const orFalse = (effect) => Effect.catchCause(effect, () => Effect.succeed(false));
-/** Load + validate a config module through the shared Vite loader. */
-export const loadConfig = (loader, configPath) => Effect.gen(function* () {
-    const module_ = yield* loader.load(configPath);
-    return yield* Effect.try({
-        try: () => validateConfig(module_.default, configPath),
-        catch: (error) => error instanceof MotionCliError
-            ? error
-            : new MotionCliError({
-                reason: "ConfigInvalid",
-                message: `${configPath}: config validation crashed`,
-                cause: error,
-            }),
-    });
-});

package/studio-app/project.ts

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