Skip to content

The open-source full-stack studio for Opus 5.5 motion video. Reverse engineering for any video. Code video with HTML: recreate, edit and render. BYOA + BYOK · Motion.md · Images, Video, Music & Voice.

fix: share preview startup between npm start and MCP

lefarcen599e94d2fae1
diff --git a/README.md b/README.md
index 2392f6aa..ef4b0361 100644
--- a/README.md
+++ b/README.md
@@ -415,7 +415,9 @@ npm run build:studio
npm start
```
-Open the address printed by `npm start`, then open **Template library**. On macOS, use the returned `studioUrl` or `previewUrl`: the shared editor selects a local port dynamically. Other platforms default to `http://localhost:4173`. Select a template and choose **Recreate template** to copy the instruction for your agent. Keep projects and credentials outside the checkout; `MOTION_DATA_DIR` selects the workspace.
+Open the `studioUrl` or `previewUrl` printed by `npm start`, then open **Template library**. Startup reuses a compatible service for the same workspace or selects an available local port. The service keeps running in the background after the launcher exits.
+
+Select a template and choose **Recreate template** to copy the instruction for your agent. Keep projects and credentials outside the checkout; `MOTION_DATA_DIR` selects the workspace.
Source checkouts load templates from `library/templates/catalog/`. The local Studio and MCP use the same files; `openmotion_list_templates` returns a searchable local index, and `openmotion_get_template` returns local guide content and absolute source paths. Larger images and videos use existing CMS links. Local edits appear on the next catalog read.
diff --git a/docs/product/architecture.md b/docs/product/architecture.md
index c7ca77b6..44da10b3 100644
--- a/docs/product/architecture.md
+++ b/docs/product/architecture.md
@@ -255,7 +255,7 @@ The font picker offers detected local fonts, imported project fonts and fonts de
- **导出输入:** 后台任务使用不可变快照并记录期望规格;后续编辑不改变该任务的本地输入。远程媒体需要稳定复现时先导入本地。
- **后台与编辑器启动:** 仅导出启动后台服务,不初始化或补写当前工程;冷启动套模板直接创建选中的模板工程。Studio starts when the Agent calls preview for an existing project, including the automatic handoff after production HTML is ready; the existing background service is reused. 健康检查区分服务 `ready` 与 `editorReady`,不靠自动替换 expectedRevision 消除冲突。
- **服务边界:** 当前在本机回环地址运行。Model Gateway 使用本机 Codex 登录或用户自有 Atlas/fal Key 发起媒体生成,接口共用本地任务与素材入库;不托管聊天 Agent、团队协作或计费。当前使用用户自有账户接入,详见 [模型网关](../model-gateway.md)。
-- **Editor URLs:** OpenMotion and its native engine listen on separate loopback endpoints. Application launchers, preview and project/template/session responses hand off the OpenMotion origin through `previewUrl` and `studioUrl`; project links retain their explicit identity. The native address is diagnostic `nativeStudioUrl` in health responses, while upstream child-process readiness fields remain internal. Preview clients reconstruct application links from verified discovery even when reusing an older compatible backend; this does not hot-reload that backend's HTTP handlers or frontend. See the [engine boundary](../hyperframes.md).
+- **Editor URLs:** OpenMotion and its native engine listen on separate loopback endpoints. `npm start` invokes the existing `preview.ts` launcher used by MCP: compatible services for the same workspace are reused, macOS selects a port dynamically, and other platforms try `PORT` (default 4173) and the next nine ports. The launcher reports the actual address and exits while the service remains in the background. Application launchers, preview and project/template/session responses hand off the OpenMotion origin through `previewUrl` and `studioUrl`; project links retain their explicit identity. The native address is diagnostic `nativeStudioUrl` in health responses, while upstream child-process readiness fields remain internal. Preview clients reconstruct application links from verified discovery even when reusing an older compatible backend; this does not hot-reload that backend's HTTP handlers or frontend. See the [engine boundary](../hyperframes.md).
- **模型与凭据:** 配置和任务独立于工程,Key 不通过 API 返回。安装、配置、允许请求、生成成功是不同状态;任务固定发起工程,失败不静默重试。完成后的素材参与工程 revision 与导出快照。
- **并发边界:** macOS 同目录多个 MCP 连接共用后台,各自绑定工程;工作区使用一个原生 Studio 服务进程,按需保留多个工程的原生上下文;后台仍只有一个等待/运行的导出。导出固定工程与快照,重启将中断任务持久化为失败且不重放。文件锁和 revision 保护工具写入;人工与 Agent 同时编辑同一文件仍需协调,不能当作跨工具数据库事务。
- **数据归属:** 产品文档描述数据类别与流程,不复制用户的私有工程、访问凭据或个人机器配置。
diff --git a/docs/template-repository.md b/docs/template-repository.md
index a125853a..c0e8f68b 100644
--- a/docs/template-repository.md
+++ b/docs/template-repository.md
@@ -12,7 +12,9 @@ npm run build:studio
npm start
```
-Open the address printed by `npm start`. On macOS, the shared editor selects a local port dynamically and returns `studioUrl` and `previewUrl`; use those URLs instead of assuming port 4173. Other platforms default to `http://localhost:4173`. Keep user projects and credentials outside the checkout; `MOTION_DATA_DIR` can select a separate workspace. The plugin root is the cloned `openmotion/` directory: `.codex-plugin/plugin.json` points to `skills/` and `.mcp.json`; that file launches the root `mcp.ts`. For a manual MCP client, launch `node --experimental-strip-types /absolute/openmotion/mcp.ts`, or use `npm run mcp` from the checkout. The repository path is resolved from the loaded plugin, not the caller's working directory.
+Open the `studioUrl` or `previewUrl` printed by `npm start`. Startup reuses a compatible service for the same workspace. On macOS, the shared editor selects a local port dynamically; other platforms try `PORT` (default 4173) and the next nine ports, skipping occupied ones. If all ten are occupied and no compatible service is found, startup reports an error. The launcher exits after reporting the URL; the service keeps running in the background. MCP uses the same startup logic and actual service address when configured for the same `MOTION_DATA_DIR`.
+
+Keep user projects and credentials outside the checkout; `MOTION_DATA_DIR` can select a separate workspace. The plugin root is the cloned `openmotion/` directory: `.codex-plugin/plugin.json` points to `skills/` and `.mcp.json`; that file launches the root `mcp.ts`. For a manual MCP client, launch `node --experimental-strip-types /absolute/openmotion/mcp.ts`, or use `npm run mcp` from the checkout. The repository path is resolved from the loaded plugin, not the caller's working directory.
- Source checkouts default to `MOTION_TEMPLATE_SOURCE=repository`. Studio search and MCP read `library/templates/catalog/` directly, without downloading the CMS catalog. A malformed local catalog fails explicitly.
- `openmotion_list_templates` returns `source=repository`, an absolute JSONL `indexPath`, total and a hash-based `catalogVersion`. Search that file locally; each repository entry includes `localSource` paths.
diff --git a/docs/usage.md b/docs/usage.md
index cb20a1f8..5c0c34dc 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -117,10 +117,11 @@ macOS 同一数据目录中的多个 MCP 会话现在共用一个后台,每个
```sh
npm ci
-npm run dev
+npm run build:studio
+npm start
```
-默认访问 `http://localhost:4173` 首页;`/?project=<id>` 或 `/#project/<id>` 打开对应项目。插件启动会校验服务版本与工程目录,避开已占用端口。Hyperframes 原生服务使用另一个回环端口;我们的服务转发原生 API、文件事件和预览请求,直接提供自有编辑器页面。视频作品仍在独立 composition iframe 中预览,以隔离 UI 样式和作品样式。
+Open the printed `studioUrl` or `previewUrl`; do not assume port 4173. `npm start` and MCP share the existing startup logic and reuse a compatible service for the same workspace. macOS selects a port dynamically; other platforms try `PORT` (default 4173) and the next nine ports, skipping occupied ones. The service remains in the background after the launcher exits. Project links use `/?project=<id>` or `/#project/<id>` at the returned origin. Hyperframes uses a separate loopback port; OpenMotion proxies its APIs, file events and preview requests while serving its own editor. Compositions remain in isolated preview iframes. `npm run dev` retains the direct foreground server entry for development.
## Agent 工具
diff --git a/package.json b/package.json
index 59b2a229..e2ee9c00 100644
--- a/package.json
+++ b/package.json
@@ -9,7 +9,7 @@
"scripts": {
"dev": "npm run build:studio && node --env-file=.env.development --experimental-strip-types server.ts",
"mcp": "node --experimental-strip-types mcp.ts",
- "start": "node --experimental-strip-types server.ts",
+ "start": "node --experimental-strip-types preview.ts",
"test": "node --experimental-strip-types --test tests/*.test.ts",
"check": "node --experimental-strip-types scripts/check.ts",
"package:plugin": "node --experimental-strip-types scripts/package.ts",