motion-previs-studio: Instructions file for Codex

AGENTS.md — running & modifying Motion Previs Studio with an AI agent

This file is the single source of truth for AI coding agents (Claude Code, Codex, Hermes, …) working on this repo. Read it before making changes.

What this app is

Electron + TypeScript + React desktop app. Filmmakers import a reference video shot, extract pose (MediaPipe), depth, a subject-masked optical-flow camera solve, edges/lineart/masks/normals control layers, and OpenPose BODY_25 skeleton video + keypoints, then export a production pack (control videos + prompts + Blender scripts + ZIP) for AI-video generators (Seedance, ComfyUI, Runway, Kling) and Blender. All ML runs locally in the renderer.

Commands

npm install            # once; runs scripts/prepare-mediapipe-assets.cjs (postinstall)
npm run dev            # Vite + Electron with hot reload (127.0.0.1 only)
npm run build          # tsc + vite build into dist/
npm start              # run the production build
npm run verify         # smoke checks (tests/smoke.cjs)
npm run verify:quality # unified quality-score sync check
npm run verify:engines # engine/runtime checks
npm run verify:e2e     # headless Electron export; asserts openpose_pose.mp4 + openpose_keypoints.json land in the bundle
npm run verify:all     # verify + build + verify:e2e
npm run dist           # electron-builder → arm64 DMG + ZIP in release/

Definition of done for any change: npm run build && npm run verify:quality && npm run verify:engines && npm run verify:e2e green. Run npm run verify:all before shipping.

Repo map

src/                React UI. App.tsx owns the whole studio surface.
src/lib/            Pure-ish analysis modules, all locally runnable:
                    pose.ts (MediaPipe), cameraMotion.ts (LK + RANSAC camera solve),
                    aiDepth.ts (Depth Anything), openpose.ts (BODY_25 render + JSON),
                    poseVideo.ts, frameEncoder.ts (deterministic ffmpeg frame encode),
                    quality.ts (single source of the unified quality score).
src/components/     ThreePreview (three.js stick figure), PoseCanvas.
src/control/        Agent-control renderer layer: registry.ts (the window.__mps surface
                    contract), handler.ts (whitelisted action dispatcher, wired from main.tsx).
electron/           main.cjs (window, IPC, ffmpeg, save/restore, Send to Blockout, control server wiring),
                    control.cjs (localhost HTTP agent-control server + discovery file),
                    preload.cjs (window.motionPrevis bridge), security.cjs (path + IPC allowlist).
mcp/                motion-previs-mcp.mjs (zero-dep stdio MCP bridge) + README.md (agent-integration guide).
shared/             quality.cjs — the CJS mirror of src/lib/quality.ts (verify:quality checks they agree).
tests/              e2e-electron.cjs (real export + control-server smoke), smoke, quality-sync, engines.
public/             generated MediaPipe/model/bin assets (gitignored).