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.

Merge main and preserve editor handoff fixes under canonical OpenMotion names

罗高f61ada6d6bdf
diff --cc docs/mcp-phase1-tools.md
index c1f2420f,c5405ce9..75efc70f
--- a/docs/mcp-phase1-tools.md
+++ b/docs/mcp-phase1-tools.md
@@@ -52,11 -52,11 +52,11 @@@ Default action=open accepts an explici
Preview and export preflight use the same pinned native `host:"studio"` lint policy as the editor. Structural errors return `PROJECT_VALIDATION_FAILED` before preview opening, or a failed export before rendering, with native code/file/location/fix hints. Warnings do not fail the check. See the [shared lint command](hyperframes.md).
- The handoff preserves the current chat by default (presentation=foreground): reuse its native Tab and queue while inactive. On return, resolve the latest project version without replaying the queued version. Codex actions include a calling-chat-only visibilitySync and bounded observation instructions; queued alone is neither confirmation nor proof that the calling chat is inactive. First delivery follows the same checks as continued edits. A separate hidden automation tab, markDeliverable or completed MP4 export does not satisfy editor delivery. Retry a missing native tab presentation once, then report the display gap. Only an explicit presentation=now request allows switching back for this turn; background skips presentation. See the shared [continuing-edit workflow](../skills/motion-production/references/native.md#continuing-edits).
-The handoff preserves the current chat by default (presentation=foreground): reuse its native Tab and queue while inactive. On return, resolve the latest project version without replaying the queued version. Codex actions include a calling-chat-only visibilitySync and bounded observation instructions; queued alone is not confirmation. Only an explicit presentation=now request allows switching back for this turn; background skips presentation. See the shared [continuing-edit workflow](../skills/openmotion-production/references/native.md#continuing-edits).
++The handoff preserves the current chat by default (presentation=foreground): reuse its native Tab and queue while inactive. On return, resolve the latest project version without replaying the queued version. Codex actions include a calling-chat-only visibilitySync and bounded observation instructions; queued alone is neither confirmation nor proof that the calling chat is inactive. First delivery follows the same checks as continued edits. A separate hidden automation tab, markDeliverable or completed MP4 export does not satisfy editor delivery. Retry a missing native tab presentation once, then report the display gap. Only an explicit presentation=now request allows switching back for this turn; background skips presentation. See the shared [continuing-edit workflow](../skills/openmotion-production/references/native.md#continuing-edits).
- action=record_display requires projectId, requestId and display={revision,versionId,previewUrl,visibility,contentVerified,evidence}; optional hostStatus and hostTabId retain the acknowledgment and actual native providerTabId independently. Only visible plus inspected latest content returns confirmed. Hidden/queued/unavailable or unverified content remains pending. visibility=queued explicitly reports host-confirmed inactive-chat deferral and returns wait_for_calling_chat; hostStatus=queued with visibility=hidden/unavailable retains present_preview recovery rather than assuming inactivity. Reject foreign project/session/origin URLs and stale revision/version identities, including same-hash restores and retries. Records are host_reported; motion_get_project.previewDisplay exposes isCurrentVersion and liveVisibilityVerified=false, never a live visibility claim.
-action=record_display requires projectId, requestId and display={revision,versionId,previewUrl,visibility,contentVerified,evidence}; optional hostStatus and hostTabId retain the acknowledgment and actual native providerTabId independently. Only visible plus inspected latest content returns confirmed. Hidden/queued/unavailable or unverified content remains pending. Reject foreign project/session/origin URLs and stale revision/version identities, including same-hash restores and retries. Records are host_reported; openmotion_get_project.previewDisplay exposes isCurrentVersion and liveVisibilityVerified=false, never a live visibility claim.
++action=record_display requires projectId, requestId and display={revision,versionId,previewUrl,visibility,contentVerified,evidence}; optional hostStatus and hostTabId retain the acknowledgment and actual native providerTabId independently. Only visible plus inspected latest content returns confirmed. Hidden/queued/unavailable or unverified content remains pending. visibility=queued explicitly reports host-confirmed inactive-chat deferral and returns wait_for_calling_chat; hostStatus=queued with visibility=hidden/unavailable retains present_preview recovery rather than assuming inactivity. Reject foreign project/session/origin URLs and stale revision/version identities, including same-hash restores and retries. Records are host_reported; openmotion_get_project.previewDisplay exposes isCurrentVersion and liveVisibilityVerified=false, never a live visibility claim.
- motion_edit_project and motion_restore_version accept the same optional presentation and return a fresh version-bound previewHandoff after each save or replay. The host owns persistent background preferences; show-now permission does not persist. Stored native Tab IDs are reuse hints that must be validated against the current host inventory. A host queue can open on return without another model turn; absent a new observation the service receipt stays pending.
+ openmotion_edit_project and openmotion_restore_version accept the same optional presentation and return a fresh version-bound previewHandoff after each save or replay. The host owns persistent background preferences; show-now permission does not persist. Stored native Tab IDs are reuse hints that must be validated against the current host inventory. A host queue can open on return without another model turn; absent a new observation the service receipt stays pending.
可选 action=record_review,须 projectId、requestId、review,记录已观察对象/versionId/结论/依据/来源与可选时间范围,不修改源码。
diff --cc docs/product/architecture.md
index 4d4717e7,98f0eb84..26a9bcb9
--- a/docs/product/architecture.md
+++ b/docs/product/architecture.md
@@@ -128,9 -128,9 +128,9 @@@ README 参考 OpenDesign 的产品导�
## 核心用户流程
1. The user creates a blank project or opens an existing one from the sidebar, asks an external Agent to create a project, or chooses a template in the editor. Bundled templates create independent project copies; external references require Agent reconstruction.
- 2. The Agent uses the existing MCP integration and verifies the selected project, revision and workflow. Integration setup remains available outside the MVP editor. Successful Agent-led installation returns the canonical reply rules from `docs/install.md` plus bounded real catalog summaries in the setup result, without waiting for the first MCP use. The Agent defaults to one eligible template; explicit comparison requests can receive three confirmed candidates. Acceptance preserves that exact choice and creates one independent editable project; refusal stops. Registration does not prove active-chat loading or that an invitation was actually displayed. No invitation telemetry/state service is introduced. Follow the [first-run defaults](../../skills/motion-production/references/templates.md#first-run-experience-defaults) for creation and delivery.
- 3. `motion_open_preview({projectId})` opens the project directly. Project switching waits for pending saves and reloads the document to release the previous edit session. Opening a bookmark warms only its scoped native context without switching other editor tabs. Rendering and write conflicts continue to block unsafe switches. Original creation, reference recreation and template production automatically open the saved project before delivery; the open editor is the deliverable, and video files are handed over only when requested (video-to-template still delivers its template ZIP). Continued edits and restores return a project/revision/version-bound previewHandoff. Reuse the native project tab: present it when the calling chat is active, otherwise queue it without switching chats and resolve the latest version when the user returns. Only this turn's explicit `presentation=now` request permits switching back; explicit background requests suppress presentation. Codex IAB synchronizes visibility within the calling chat. A queued acknowledgment does not establish chat inactivity: hidden/unavailable panels retain presentation recovery, and only host-confirmed inactive-chat deferral waits for return. First delivery uses the same visibility checks; hidden automation playback, markDeliverable and export success do not complete editor delivery. A queued acknowledgment is separate from observed visibility and live-content freshness; `record_display` rejects stale content identities, and stored previewDisplay remains historical host-reported evidence. The shared [editable preview handoff](../../skills/motion-production/references/native.md#editable-preview-handoff) defines readiness, host checks and capability limitations.
- 4. Agent 根据本轮目标直接选择 Skill:motion-director 负责原创、局部/整体叙事动作声音重新设计和创作审片;motion-template-to-video 负责已有模板出片;motion-recreate 负责参考作品重建(已接入实际流程、独立参考与测量脚本);motion-video-to-template 负责可复用模板生产;motion-production 承接既定决定下的工程操作、预览、技术检查、排错和导出。共享规则同源引用,已有 production/start 保留导航,无需前置总路由。项目来源与画面锁定不固定入口;保持项和已完成操作继续有效。
+ 2. The Agent uses the existing MCP integration and verifies the selected project, revision and workflow. Integration setup remains available outside the MVP editor. Successful Agent-led installation returns the canonical reply rules from `docs/install.md` plus bounded real catalog summaries in the setup result, without waiting for the first MCP use. The Agent defaults to one eligible template; explicit comparison requests can receive three confirmed candidates. Acceptance preserves that exact choice and creates one independent editable project; refusal stops. Registration does not prove active-chat loading or that an invitation was actually displayed. No invitation telemetry/state service is introduced. Follow the [first-run defaults](../../skills/openmotion-production/references/templates.md#first-run-experience-defaults) for creation and delivery.
-3. `openmotion_open_preview({projectId})` opens the project directly. Project switching waits for pending saves and reloads the document to release the previous edit session. Opening a bookmark warms only its scoped native context without switching other editor tabs. Rendering and write conflicts continue to block unsafe switches. Original creation, reference recreation and template production automatically open the saved project before delivery; the open editor is the deliverable, and video files are handed over only when requested (video-to-template still delivers its template ZIP). Continued edits and restores return a project/revision/version-bound previewHandoff. Reuse the native project tab: present it when the calling chat is active, otherwise queue it without switching chats and resolve the latest version when the user returns. Only this turn's explicit `presentation=now` request permits switching back; explicit background requests suppress presentation. Codex IAB synchronizes visibility within the calling chat. A queued acknowledgment is separate from observed visibility and live-content freshness; `record_display` rejects stale content identities, and stored previewDisplay remains historical host-reported evidence. The shared [editable preview handoff](../../skills/openmotion-production/references/native.md#editable-preview-handoff) defines readiness, host checks and capability limitations.
++3. `openmotion_open_preview({projectId})` opens the project directly. Project switching waits for pending saves and reloads the document to release the previous edit session. Opening a bookmark warms only its scoped native context without switching other editor tabs. Rendering and write conflicts continue to block unsafe switches. Original creation, reference recreation and template production automatically open the saved project before delivery; the open editor is the deliverable, and video files are handed over only when requested (video-to-template still delivers its template ZIP). Continued edits and restores return a project/revision/version-bound previewHandoff. Reuse the native project tab: present it when the calling chat is active, otherwise queue it without switching chats and resolve the latest version when the user returns. Only this turn's explicit `presentation=now` request permits switching back; explicit background requests suppress presentation. Codex IAB synchronizes visibility within the calling chat. A queued acknowledgment does not establish chat inactivity: hidden/unavailable panels retain presentation recovery, and only host-confirmed inactive-chat deferral waits for return. First delivery uses the same visibility checks; hidden automation playback, markDeliverable and export success do not complete editor delivery. A queued acknowledgment is separate from observed visibility and live-content freshness; `record_display` rejects stale content identities, and stored previewDisplay remains historical host-reported evidence. The shared [editable preview handoff](../../skills/openmotion-production/references/native.md#editable-preview-handoff) defines readiness, host checks and capability limitations.
+ 4. Agent 根据本轮目标直接选择 Skill:openmotion-director 负责原创、局部/整体叙事动作声音重新设计和创作审片;openmotion-template-to-video 负责已有模板出片;openmotion-recreate 负责参考作品重建(已接入实际流程、独立参考与测量脚本);openmotion-video-to-template 负责可复用模板生产;openmotion-production 承接既定决定下的工程操作、预览、技术检查、排错和导出。共享规则同源引用,已有 production/start 保留导航,无需前置总路由。项目来源与画面锁定不固定入口;保持项和已完成操作继续有效。
5. The Agent imports or generates media through the existing backend. In the editor, the user imports assets, edits text/solid color/opacity, previews, and edits clips on the timeline. Element, clip, time-range and official animation-library Ask Agent entry points are hidden in the MVP; users can continue requesting edits through their external Agent. Text controls include headings with explicit line breaks and preserve those breaks when edited. The MVP omits the layer-count heading and Add text field controls. Unselected off-canvas elements have no dashed markers in the MVP preview; selecting an element, including from Layers, retains its selection boundary. Text selections omit the separate Style group and background-fill control; element opacity remains in Text. For opacity-animated elements, the MVP opacity control saves an independent CSS filter multiplier, retaining the authored fade and existing static filters rather than writing over the animated opacity channel. The multiplier is part of project source, so preview and export use the same value. Other element types retain their Style controls. Generation, image replacement, advanced style/animation controls, code and inspector Layout settings are hidden without rewriting existing source content or removing Agent capabilities.
6. 完成画面、文案、声音检查后,按用户要求导出固定 revision 的快照,等待真实产物并验证。
diff --cc docs/product/changes.md
index c0096db4,0384f7b5..7dfff063
--- a/docs/product/changes.md
+++ b/docs/product/changes.md
@@@ -1,12 -1,5 +1,12 @@@
# 公开变更记录
+## 2026-11-12: Complete visible editor delivery after video creation
+
+- **Problem:** A queued host acknowledgment with a hidden panel could send an Agent into waiting for the user to return without evidence that the calling chat was inactive. A separate hidden inspection tab or successful MP4 export could then end the turn without visible editor delivery.
+- **Implementation:** Hidden/unavailable display receipts retain native-panel presentation recovery and its tab reuse hint. Only explicit host-confirmed inactive-chat deferral returns the wait action. First delivery follows the same visibility and latest-content checks as continued edits, and unresolved display failures remain visible in the final handoff.
- - **Validation:** 47 targeted contract, workflow, adapter and packaging tests passed, alongside static checks, Studio type checking and the Studio build. Regression coverage separates queued acknowledgments from observed visibility, preserves inactive-chat deferral and verifies that the updated Skill and Tool sources ship together.
++- **Validation:** 53 targeted contract, workflow, adapter, naming-compatibility and packaging tests passed, alongside static checks, Studio type checking and the Studio build. Regression coverage separates queued acknowledgments from observed visibility, preserves inactive-chat deferral and verifies that the updated Skill and Tool sources ship together.
+- **Limits:** Original-machine host reproduction and a new model-driven video creation/handoff acceptance run remain unverified. The service records host-reported evidence; it does not independently measure the outer host panel. This change does not publish a package.
+
## 2026-11-11: Check historical media before offering MCP restoration
- **Problem and audience:** Agents and creators could be told that a historical version was restorable after its media blobs had disappeared; restoration then exposed a low-level file-copy error.
diff --cc phase1.ts
index e61bab36,f23cd942..78700239
--- a/phase1.ts
+++ b/phase1.ts
@@@ -29,11 -30,11 +30,11 @@@ function previewHandoff(origin: string
const confirmed = display?.visibility === 'visible' && display.contentVerified === true;
const background = presentation === 'background';
const now = presentation === 'now';
- const onReturn = { tool: 'motion_open_preview', arguments: { projectId: target.projectId } };
+ const onReturn = { tool: 'openmotion_open_preview', arguments: { projectId: target.projectId } };
- const deferred = !now && display?.visibility !== 'visible' && (display?.hostStatus === 'queued' || display?.visibility === 'queued');
+ const deferred = !now && display?.visibility === 'queued';
const recovery = now ? { when: 'hidden_after_queued_ack', tool: 'navigate_to_codex_page', scope: 'calling_chat_only',
threadIdFrom: 'open_in_codex.response.threadId', then: 'present_same_tab_and_recheck_visibility' } :
- { when: 'calling_chat_not_visible', operation: 'wait_for_calling_chat', onReturn };
+ { when: 'calling_chat_confirmed_inactive', operation: 'wait_for_calling_chat', onReturn };
return { ...target, previewUrl, placement: 'right', reuseExistingTab: true, presentation,
focusPolicy: background ? 'background' : now ? 'switch_to_calling_chat' : 'preserve_current_chat',
state: background ? 'background' : confirmed ? 'confirmed' : 'pending', openedByHost: confirmed,
@@@ -49,8 -50,8 +50,8 @@@
projectId: target.projectId, expectedRevision: target.revision, expectedVersionId: target.versionId, presentation } },
instructions: background ? 'Keep this edit in the background as explicitly requested by the user.' :
(now ? 'The user explicitly requested immediate display for this turn; current-chat recovery may navigate to the calling chat. ' :
- 'Preserve the current chat. Queue the preview for its calling chat without navigating; if queued or hidden, wait for the user to return. On return, prepare the latest project version rather than replaying an old version-bound action. ') +
- 'Bind the native project tab and request Codex IAB visibility for the calling chat without navigation; inactive chats queue this request. Observe settled visibility and changed live content/time, recheck visibility, then record_display for the currently observed revision/version. A queued acknowledgment alone is not display confirmation. Follow openmotion://workflow/production/native#continuing-edits.' };
+ 'Preserve the current chat. Wait for return only when the host confirms the calling chat is inactive; queued acknowledgment or hidden panel alone does not establish inactivity. On return, prepare the latest project version rather than replaying an old version-bound action. ') +
- 'For first delivery and continued edits, bind the native project tab and request Codex IAB visibility for the calling chat without navigation. Observe settled visibility and changed live content/time, recheck visibility, then record_display for the currently observed revision/version. Use visibility=queued only for confirmed inactive-chat deferral; otherwise record hidden or unavailable and report the display failure. Hidden-tab playback, markDeliverable and completed MP4 export do not complete editor delivery. Follow motion://workflow/production/native#continuing-edits.' };
++ 'For first delivery and continued edits, bind the native project tab and request Codex IAB visibility for the calling chat without navigation. Observe settled visibility and changed live content/time, recheck visibility, then record_display for the currently observed revision/version. Use visibility=queued only for confirmed inactive-chat deferral; otherwise record hidden or unavailable and report the display failure. Hidden-tab playback, markDeliverable and completed MP4 export do not complete editor delivery. Follow openmotion://workflow/production/native#continuing-edits.' };
}
function cursor(value: any) { return Buffer.from(JSON.stringify(value)).toString('base64url'); }
function parseCursor(value: string | undefined, kind: string, scope: string) {
diff --cc shared/integration.ts
index 581b1362,59cc6b5c..d5ed2686
--- a/shared/integration.ts
+++ b/shared/integration.ts
@@@ -133,11 -133,11 +133,11 @@@ ${workflowEntryGuide
## 创建与编辑
- 新项目用 motion_create_project,提供 requestId、projectType、title、requirements。模板可从 Studio 选择,或调用 motion_list_templates 取得本地 JSONL 索引路径后用本机工具检索,再用 motion_get_template 读取详情。已知 ID 可直接读详情。内置及 Prism 模板用 projectType=template 创建;参考视频创建的是重建载体,由宿主 Agent 看参考并编写内容,不宣称已经生成影片。现有项目先 motion_get_project 列表/详情核对 projectId、sessionId、revision 与 currentVersionId。
+ 新项目用 openmotion_create_project,提供 requestId、projectType、title、requirements。模板可从 Studio 选择,或调用 openmotion_list_templates 取得本地 JSONL 索引路径后用本机工具检索,再用 openmotion_get_template 读取详情。已知 ID 可直接读详情。内置及 Prism 模板用 projectType=template 创建;参考视频创建的是重建载体,由宿主 Agent 看参考并编写内容,不宣称已经生成影片。现有项目先 openmotion_get_project 列表/详情核对 projectId、sessionId、revision 与 currentVersionId。
- 素材通过 motion_import_assets 批量持久导入实际本机附件,检查逐项结果;再用 motion_edit_project 保存原生 HTML/CSS/JS 和可选需求,传 expectedRevision、expectedVersionId 及稳定 requestId。冲突时重新读,不盲目覆盖 GUI 修改。媒体生成使用宿主或 Studio 已有能力,本期 MCP 不公开生成/供应商配置入口。
+ 素材通过 openmotion_import_assets 批量持久导入实际本机附件,检查逐项结果;再用 openmotion_edit_project 保存原生 HTML/CSS/JS 和可选需求,传 expectedRevision、expectedVersionId 及稳定 requestId。冲突时重新读,不盲目覆盖 GUI 修改。媒体生成使用宿主或 Studio 已有能力,本期 MCP 不公开生成/供应商配置入口。
-After each content edit or restore, follow previewHandoff and production/native#continuing-edits. Request the same project on the calling chat's right panel, preserving embed/query/hash and reusing the actual native Tab ID. Default foreground preserves the current chat: queue while inactive, resolve the latest version on return, and verify actual visibility and changed live content before action=record_display. Codex IAB visibility synchronization is scoped to the calling chat and does not navigate. queued is only an acknowledgment. Only this turn's explicit show-now request permits presentation=now and switching back; background skips presentation. Never guess a project from another chat or workspace.
+After each content edit or restore, follow previewHandoff and production/native#continuing-edits. Request the same project on the calling chat's right panel, preserving embed/query/hash and reusing the actual native Tab ID. Default foreground preserves the current chat: queue while inactive, resolve the latest version on return, and verify actual visibility and changed live content before action=record_display. Codex IAB visibility synchronization is scoped to the calling chat and does not navigate. queued is only an acknowledgment, not proof that the calling chat is inactive. Apply the same visibility checks to first delivery; hidden automation tabs, markDeliverable and completed MP4 export do not replace the editor handoff. Use visibility=queued only for confirmed inactive-chat deferral; otherwise report the display failure. Only this turn's explicit show-now request permits presentation=now and switching back; background skips presentation. Never guess a project from another chat or workspace.
## 版本与导出
diff --cc shared/mcp-profiles.json
index 1b1c0803,02c1828c..cf1f24c5
--- a/shared/mcp-profiles.json
+++ b/shared/mcp-profiles.json
@@@ -5,18 -5,18 +5,18 @@@
},
"phase1": {
"tools": [
- "motion_list_templates",
- "motion_get_template",
- "motion_create_project",
- "motion_open_preview",
- "motion_import_assets",
- "motion_get_project",
- "motion_edit_project",
- "motion_export_request",
- "motion_list_versions",
- "motion_restore_version",
- "motion_export_cancel"
+ "openmotion_list_templates",
+ "openmotion_get_template",
+ "openmotion_create_project",
+ "openmotion_open_preview",
+ "openmotion_import_assets",
+ "openmotion_get_project",
+ "openmotion_edit_project",
+ "openmotion_export_request",
+ "openmotion_list_versions",
+ "openmotion_restore_version",
+ "openmotion_export_cancel"
],
- "instructions": "Use only the tools returned by tools/list. Follow the installed phase-one production skills. Read the selected project and current content version before editing. Save native source through motion_edit_project; preview and export perform their required checks internally. Use motion_list_versions to find project snapshots and motion_restore_version to restore one as a new version while retaining later history. A transport cancellation does not prove a background export stopped. Report actual export state and accessible results; technical validation does not replace visual, audio and player review. Never guess a project from another conversation. Read skills locally or with resources/list and resources/read (motion://workflow/production/start, or the selected specialist); engine authoring guidance is motion://engine/SKILL.md and relative Markdown references under motion://engine/. For new work create explicitly; motion_open_preview never silently creates a project. Persisted create/import/edit/restore/export/cancel and review requests require a stable requestId; preview action=open does not. Edits require projectId, expectedRevision and expectedVersionId. Query export progress through motion_get_project with projectId and exportJobId. Project list and version list are five per page; follow nextCursor. For template discovery, call motion_list_templates to obtain a local JSONL index path, then search that file with local tools. It does not return search results. Read the selected ID with motion_get_template; create its independent editable copy with motion_create_project projectType=template. Use the connected Motion MCP tools for project operations and exports; a shell HTTP call is not an MCP tool invocation. Before opening a project, verify the connection dataDirectory and project/version with motion_get_project. Browser URLs and project IDs do not select another workspace. Compatible phase-one plugin/backend updates continue automatically on the existing connection through API protocol and Tool negotiation; keep the workspace, project binding and running exports. If the API is incompatible, update the incompatible components together when idle. Only an already-closed host transport or an internal legacy runtime replacement requires reconnection. Do not silently bypass MCP or change workspaces. After each content edit or restore, follow previewHandoff and production/native#continuing-edits to request the latest preview in the calling chat. Default foreground preserves the current chat: queue while inactive, then resolve the latest project version on return. Bind the actual native providerTabId, synchronize Codex IAB visibility without navigation, and independently verify settled visibility and changed live content. Record action=record_display only for the observed revision/version; queued alone is not confirmation or proof that the calling chat is inactive. Complete the same visibility checks for first delivery. Hidden automation tabs, markDeliverable and MP4 export do not satisfy editor delivery. Use visibility=queued only for confirmed inactive-chat deferral; otherwise report the hidden/unavailable panel as a display failure. Use presentation=now only for this turn's explicit show-now request; background skips presentation."
- "instructions": "Use only the tools returned by tools/list. Follow the installed phase-one production skills. Read the selected project and current content version before editing. Save native source through openmotion_edit_project; preview and export perform their required checks internally. Use openmotion_list_versions to find project snapshots and openmotion_restore_version to restore one as a new version while retaining later history. A transport cancellation does not prove a background export stopped. Report actual export state and accessible results; technical validation does not replace visual, audio and player review. Never guess a project from another conversation. Read skills locally or with resources/list and resources/read (openmotion://workflow/production/start, or the selected specialist); engine authoring guidance is openmotion://engine/SKILL.md and relative Markdown references under openmotion://engine/. For new work create explicitly; openmotion_open_preview never silently creates a project. Persisted create/import/edit/restore/export/cancel and review requests require a stable requestId; preview action=open does not. Edits require projectId, expectedRevision and expectedVersionId. Query export progress through openmotion_get_project with projectId and exportJobId. Project list and version list are five per page; follow nextCursor. For template discovery, call openmotion_list_templates to obtain a local JSONL index path, then search that file with local tools. It does not return search results. Read the selected ID with openmotion_get_template; create its independent editable copy with openmotion_create_project projectType=template. Use the connected OpenMotion MCP tools for project operations and exports; a shell HTTP call is not an MCP tool invocation. Before opening a project, verify the connection dataDirectory and project/version with openmotion_get_project. Browser URLs and project IDs do not select another workspace. Compatible phase-one plugin/backend updates continue automatically on the existing connection through API protocol and Tool negotiation; keep the workspace, project binding and running exports. If the API is incompatible, update the incompatible components together when idle. Only an already-closed host transport or an internal legacy runtime replacement requires reconnection. Do not silently bypass MCP or change workspaces. After each content edit or restore, follow previewHandoff and production/native#continuing-edits to request the latest preview in the calling chat. Default foreground preserves the current chat: queue while inactive, then resolve the latest project version on return. Bind the actual native providerTabId, synchronize Codex IAB visibility without navigation, and independently verify settled visibility and changed live content. Record action=record_display only for the observed revision/version; queued alone is not confirmation. Use presentation=now only for this turn's explicit show-now request; background skips presentation."
++ "instructions": "Use only the tools returned by tools/list. Follow the installed phase-one production skills. Read the selected project and current content version before editing. Save native source through openmotion_edit_project; preview and export perform their required checks internally. Use openmotion_list_versions to find project snapshots and openmotion_restore_version to restore one as a new version while retaining later history. A transport cancellation does not prove a background export stopped. Report actual export state and accessible results; technical validation does not replace visual, audio and player review. Never guess a project from another conversation. Read skills locally or with resources/list and resources/read (openmotion://workflow/production/start, or the selected specialist); engine authoring guidance is openmotion://engine/SKILL.md and relative Markdown references under openmotion://engine/. For new work create explicitly; openmotion_open_preview never silently creates a project. Persisted create/import/edit/restore/export/cancel and review requests require a stable requestId; preview action=open does not. Edits require projectId, expectedRevision and expectedVersionId. Query export progress through openmotion_get_project with projectId and exportJobId. Project list and version list are five per page; follow nextCursor. For template discovery, call openmotion_list_templates to obtain a local JSONL index path, then search that file with local tools. It does not return search results. Read the selected ID with openmotion_get_template; create its independent editable copy with openmotion_create_project projectType=template. Use the connected OpenMotion MCP tools for project operations and exports; a shell HTTP call is not an MCP tool invocation. Before opening a project, verify the connection dataDirectory and project/version with openmotion_get_project. Browser URLs and project IDs do not select another workspace. Compatible phase-one plugin/backend updates continue automatically on the existing connection through API protocol and Tool negotiation; keep the workspace, project binding and running exports. If the API is incompatible, update the incompatible components together when idle. Only an already-closed host transport or an internal legacy runtime replacement requires reconnection. Do not silently bypass MCP or change workspaces. After each content edit or restore, follow previewHandoff and production/native#continuing-edits to request the latest preview in the calling chat. Default foreground preserves the current chat: queue while inactive, then resolve the latest project version on return. Bind the actual native providerTabId, synchronize Codex IAB visibility without navigation, and independently verify settled visibility and changed live content. Record action=record_display only for the observed revision/version; queued alone is not confirmation or proof that the calling chat is inactive. Complete the same visibility checks for first delivery. Hidden automation tabs, markDeliverable and MP4 export do not satisfy editor delivery. Use visibility=queued only for confirmed inactive-chat deferral; otherwise report the hidden/unavailable panel as a display failure. Use presentation=now only for this turn's explicit show-now request; background skips presentation."
}
}
diff --cc shared/phase1-tools.ts
index fa9162c9,67e6dd82..8dc90357
--- a/shared/phase1-tools.ts
+++ b/shared/phase1-tools.ts
@@@ -12,28 -13,28 +13,28 @@@ const display = object({ revision, vers
const read = { readOnlyHint: true, openWorldHint: false };
const write = { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false };
export const phase1Tools = [
- { name: 'motion_list_templates', description: 'Fetch or refresh the shared template catalog cache. Returns indexPath (local JSONL, one summary per template), total and catalogVersion, not search results. Read or grep/jq the file on this machine to select a template, then call motion_get_template. No query or pagination arguments.', inputSchema: object({}), annotations: { ...read, openWorldHint: true } },
- { name: 'motion_get_template', description: 'Read one exact template ID, its editable file manifest and TEMPLATE.md guidance. This does not create a project. Use motion_create_project with projectType=template to download the files into a new editable project. Known IDs do not require motion_list_templates first.', inputSchema: object({ templateId: id }, ['templateId']), annotations: { ...read, openWorldHint: true } },
- { name: 'motion_create_project', description: 'Create an independent editable native Motion project from a prompt, an editable template ID or reference-video ID. The host Agent authors the film; creation does not generate a finished video. Persist requirements and source, return project/session IDs and the initial content version. A requestId is required for safe retries.',
+ { name: 'openmotion_list_templates', title: 'OpenMotion · List Templates', description: 'Fetch or refresh the shared template catalog cache. Returns indexPath (local JSONL, one summary per template), total and catalogVersion, not search results. Read or grep/jq the file on this machine to select a template, then call openmotion_get_template. No query or pagination arguments.', inputSchema: object({}), annotations: { ...read, openWorldHint: true } },
+ { name: 'openmotion_get_template', title: 'OpenMotion · Get Template', description: 'Read one exact template ID, its editable file manifest and TEMPLATE.md guidance. This does not create a project. Use openmotion_create_project with projectType=template to download the files into a new editable project. Known IDs do not require openmotion_list_templates first.', inputSchema: object({ templateId: id }, ['templateId']), annotations: { ...read, openWorldHint: true } },
+ { name: 'openmotion_create_project', title: 'OpenMotion · Create Project', description: 'Create an independent editable native OpenMotion project from a prompt, an editable template ID or reference-video ID. The host Agent authors the film; creation does not generate a finished video. Persist requirements and source, return project/session IDs and the initial content version. A requestId is required for safe retries.',
inputSchema: object({ requestId: id, projectType: { enum: ['natural_language', 'template', 'reference_video'] }, title: { type: 'string', minLength: 1, maxLength: 100 }, requirements: text,
sessionId: projectId, templateId: id, referenceVideoId: id, referenceUrl: { type: 'string', maxLength: 2000 } }, ['requestId', 'projectType', 'title', 'requirements']), annotations: write },
- { name: 'motion_open_preview', description: 'Prepare the named project in the shared editable Studio; this Tool does not open the host browser. Without projectId use only an explicitly bound OpenMotion session, never the global most-recent project. Follow previewHandoff to present the native panel and verify visibility plus latest content for first delivery and continued edits. Default foreground shows the active calling chat panel without switching chats; wait for return only when the host confirms that chat is inactive. A queued acknowledgment, hidden automation tab or markDeliverable does not complete delivery. Only an explicit show-now request uses presentation=now to permit switching for this turn. action=record_display records the current revision/version observation; queued or unverified content stays pending. Report a still-hidden panel as a display failure. action=record_review records evidence about a previously viewed frozen version without changing source.',
- { name: 'openmotion_open_preview', title: 'OpenMotion · Open Preview', description: 'Open the named project in the shared editable Studio. Without projectId use only an explicitly bound OpenMotion session, never the global most-recent project. Returns a version-bound previewHandoff; default foreground queues for the calling chat without switching chats. Only an explicit show-now request uses presentation=now to permit switching for this turn. Inspect the latest content after the user returns. action=record_display records the host observation against the current revision/version; queued or unverified content stays pending. action=record_review records evidence about a previously viewed frozen version without changing source.',
++ { name: 'openmotion_open_preview', title: 'OpenMotion · Open Preview', description: 'Prepare the named project in the shared editable Studio; this Tool does not open the host browser. Without projectId use only an explicitly bound OpenMotion session, never the global most-recent project. Follow previewHandoff to present the native panel and verify visibility plus latest content for first delivery and continued edits. Default foreground shows the active calling chat panel without switching chats; wait for return only when the host confirms that chat is inactive. A queued acknowledgment, hidden automation tab or markDeliverable does not complete delivery. Only an explicit show-now request uses presentation=now to permit switching for this turn. action=record_display records the current revision/version observation; queued or unverified content stays pending. Report a still-hidden panel as a display failure. action=record_review records evidence about a previously viewed frozen version without changing source.',
inputSchema: object({ action: { enum: ['open', 'record_review', 'record_display'] }, projectId, sessionId: projectId, embedded: { type: 'boolean' }, presentation, expectedRevision: revision, expectedVersionId: id, requestId: id, review, display }, []), annotations: write },
- { name: 'motion_import_assets', description: 'Persist a batch of real local attachments into this project, at most 500 MB (500000000 bytes) per file. Probe actual media and return per-item asset IDs, types, sizes, paths and errors. Successful items survive other failures. Existing history is not overwritten. Import does not place media on the timeline. Reuse the same requestId/itemId to retry without duplicate assets.',
+ { name: 'openmotion_import_assets', title: 'OpenMotion · Import Assets', description: 'Persist a batch of real local attachments into this project, at most 500 MB (500000000 bytes) per file. Probe actual media and return per-item asset IDs, types, sizes, paths and errors. Successful items survive other failures. Existing history is not overwritten. Import does not place media on the timeline. Reuse the same requestId/itemId to retry without duplicate assets.',
inputSchema: object({ projectId, requestId: id, items: { type: 'array', minItems: 1, maxItems: 100, items: object({ itemId: id, sourcePath: { type: 'string', minLength: 1, maxLength: 4096 }, name: { type: 'string', maxLength: 200 } }, ['itemId', 'sourcePath']) } }, ['projectId', 'requestId', 'items']), annotations: write },
- { name: 'motion_get_project', description: 'Without projectId list projects in the current workspace, newest creation first, exactly five per page (except the last); use nextCursor. With projectId read that project, current revision/version, requirements, native file inventory, asset references and associated export state. file supports bounded UTF-8 reads; exportJobId reads a historical task. This does not switch Studio or create projects.',
+ { name: 'openmotion_get_project', title: 'OpenMotion · Get Project', description: 'Without projectId list projects in the current workspace, newest creation first, exactly five per page (except the last); use nextCursor. With projectId read that project, current revision/version, requirements, native file inventory, asset references and associated export state. file supports bounded UTF-8 reads; exportJobId reads a historical task. This does not switch Studio or create projects.',
inputSchema: object({ projectId, sessionId: projectId, cursor: { type: 'string', maxLength: 2000 }, file: object({ path: { type: 'string', minLength: 1, maxLength: 240 }, offset: { type: 'integer', minimum: 0 }, length: { type: 'integer', minimum: 1, maximum: 2097152 } }, ['path']), expectedRevision: revision, exportJobId: id }, []), annotations: read },
- { name: 'motion_edit_project', description: 'Save the host Agent\'s native text-file batch and associated requirements into the explicitly named project. Check both expectedRevision and expectedVersionId, commit all files or none, protect GUI writes, record one complete content version and let Studio refresh. Every save returns a version-bound previewHandoff: preserve the current chat by default, queue when inactive and confirm the latest content on return. An accepted queued preview may be reported as saved and waiting for return. Only an explicit show-now request permits presentation=now for this turn; background skips presentation. The service does not generate code. Read project/version again after conflicts.',
+ { name: 'openmotion_edit_project', title: 'OpenMotion · Edit Project', description: 'Save the host Agent\'s native text-file batch and associated requirements into the explicitly named project. Check both expectedRevision and expectedVersionId, commit all files or none, protect GUI writes, record one complete content version and let Studio refresh. Every save returns a version-bound previewHandoff: preserve the current chat by default, queue when inactive and confirm the latest content on return. An accepted queued preview may be reported as saved and waiting for return. Only an explicit show-now request permits presentation=now for this turn; background skips presentation. The service does not generate code. Read project/version again after conflicts.',
inputSchema: object({ projectId, requestId: id, expectedRevision: revision, expectedVersionId: id, presentation, requirements: text, summary: { type: 'string', maxLength: 300 },
files: { type: 'array', maxItems: 100, items: object({ path: { type: 'string', minLength: 1, maxLength: 240 }, content: { type: 'string' } }, ['path', 'content']) } }, ['projectId', 'requestId', 'expectedRevision', 'expectedVersionId', 'files']), annotations: write },
- { name: 'motion_export_request', description: 'Queue a background MP4 of the explicit project version and immutable source/media snapshot. Automatically lint and fully technically verify the result. Return jobId; read progress/results with motion_get_project exportJobId. Export does not open the editor or complete an outstanding editable-preview handoff; follow motion_open_preview separately for creation/edit delivery. Repeated requestId returns the original task. action=record_review only records actual playback/visual/audio evidence for an existing job; it never starts another render.',
- { name: 'openmotion_export_request', title: 'OpenMotion · Export Request', description: 'Queue a background MP4 of the explicit project version and immutable source/media snapshot. Automatically lint and fully technically verify the result. Return jobId; read progress/results with openmotion_get_project exportJobId. Repeated requestId returns the original task. action=record_review only records actual playback/visual/audio evidence for an existing job; it never starts another render.',
++ { name: 'openmotion_export_request', title: 'OpenMotion · Export Request', description: 'Queue a background MP4 of the explicit project version and immutable source/media snapshot. Automatically lint and fully technically verify the result. Return jobId; read progress/results with openmotion_get_project exportJobId. Export does not open the editor or complete an outstanding editable-preview handoff; follow openmotion_open_preview separately for creation/edit delivery. Repeated requestId returns the original task. action=record_review only records actual playback/visual/audio evidence for an existing job; it never starts another render.',
inputSchema: object({ action: { enum: ['request', 'record_review'] }, projectId, requestId: id, expectedRevision: revision, versionId: id, jobId: id,
audio: { enum: ['required', 'silent', 'optional'] }, review }, ['projectId', 'requestId']), annotations: write },
- { name: 'motion_list_versions', description: 'List consistent project content snapshots, not individual file save counts. Return current-version identity and five snapshots per page with a cursor for older pages, including stable IDs, vN labels, source, summary and restorability. Five is a page size, not a retention limit.',
+ { name: 'openmotion_list_versions', title: 'OpenMotion · List Versions', description: 'List consistent project content snapshots, not individual file save counts. Return current-version identity and five snapshots per page with a cursor for older pages, including stable IDs, vN labels, source, summary and restorability. Five is a page size, not a retention limit.',
inputSchema: object({ projectId, cursor: { type: 'string', maxLength: 2000 } }, ['projectId']), annotations: read },
- { name: 'motion_restore_version', description: 'Restore the explicitly selected project snapshot as a NEW version. Restoring v3 while current is v5 produces v6 with v3 content; v4 and v5 remain. Check current version/revision, restore native source, styles, timing and retained media together, and reject missing historical resources without changing the current project. Returns the same previewHandoff as a source edit; explicit background requests use presentation=background.',
+ { name: 'openmotion_restore_version', title: 'OpenMotion · Restore Version', description: 'Restore the explicitly selected project snapshot as a NEW version. Restoring v3 while current is v5 produces v6 with v3 content; v4 and v5 remain. Check current version/revision, restore native source, styles, timing and retained media together, and reject missing historical resources without changing the current project. Returns the same previewHandoff as a source edit; explicit background requests use presentation=background.',
inputSchema: object({ projectId, requestId: id, versionId: id, expectedRevision: revision, expectedVersionId: id, presentation }, ['projectId', 'requestId', 'versionId', 'expectedRevision', 'expectedVersionId']), annotations: write },
- { name: 'motion_export_cancel', description: 'Cancel the specified export owned by this project. Distinguish cancellation accepted/cancelling from a confirmed cancelled terminal state. A completed task stays completed. Cancellation does not restore source, delete older results or promise a refund. Stopping a host conversation does not automatically call this tool.',
+ { name: 'openmotion_export_cancel', title: 'OpenMotion · Export Cancel', description: 'Cancel the specified export owned by this project. Distinguish cancellation accepted/cancelling from a confirmed cancelled terminal state. A completed task stays completed. Cancellation does not restore source, delete older results or promise a refund. Stopping a host conversation does not automatically call this tool.',
inputSchema: object({ projectId, requestId: id, jobId: id }, ['projectId', 'requestId', 'jobId']), annotations: write },
];
diff --cc skills/openmotion-production/references/native.md
index 5722713b,7814cae5..c39ea8ac
--- a/skills/openmotion-production/references/native.md
+++ b/skills/openmotion-production/references/native.md
@@@ -14,10 -14,8 +14,10 @@@ Read the pinned engine guide returned a
## Editable preview handoff
- The first output of original creation, reference-video recreation and editable-template production automatically includes an editable preview. Once the requested HTML and its supporting files/assets have been saved, call `motion_open_preview({projectId})` for that same project, then visibly open its exact returned `previewUrl` in the host's built-in browser. No additional user request or confirmation is needed. This includes drafts and unchanged template HTML; it does not wait for MP4 export. An empty carrier's `index.html` is not the requested output. Explicit user instructions to stay in the background take precedence.
+ The first output of original creation, reference-video recreation and editable-template production automatically includes an editable preview. Once the requested HTML and its supporting files/assets have been saved, call `openmotion_open_preview({projectId})` for that same project, then visibly open its exact returned `previewUrl` in the host's built-in browser. No additional user request or confirmation is needed. This includes drafts and unchanged template HTML; it does not wait for MP4 export. An empty carrier's `index.html` is not the requested output. Explicit user instructions to stay in the background take precedence.
+First delivery must complete steps 1–5 under [Continuing edits](#continuing-edits) too: preparing the preview is only the first step. Hidden-tab playback, screenshots, `markDeliverable()` and a completed MP4 export do not prove editor delivery. Before finishing, either confirm the native panel is visible with the latest content, or state the specific display failure/deferred status and give the project URL. Do not silently replace the editor with files.
+
The Tool runs lint and selects an existing project in Studio; it does not create a project or open the host browser. Preserve the URL's embed/query/hash, verify that the intended project and current content loaded, and reuse its browser tab on continued work. If lint fails, fix the reported source problem before retrying. If preview or browser capability is unavailable, provide the project URL when available and state the concrete gap; report the page as opened only after observing it. Do not substitute the system `open` command, AppleScript or a separately launched visible browser for the host's browser. For an independent folder/ZIP, use a supported managed-project handoff if available; the public MCP has no general folder/ZIP adoption Tool. Preserve the actual source and report that limitation rather than opening an unrelated carrier.
Preview preflight, export preflight and the OpenMotion command `node <runtimeRoot>/scripts/lint-project.mjs <runtimeRoot> <projectDirectory>` use the native linter with `host: "studio"`. Structural errors therefore fail before the editor is opened or rendering begins; ordinary warnings remain non-blocking. A direct upstream `hyperframes lint` still uses its own CLI warning policy and is not proof that Studio will accept a project.
@@@ -26,13 -24,13 +26,13 @@@
Every content-editing turn saves the result and requests its preview in the same host chat. Reuse the project and native tab. Default `presentation:"foreground"` preserves the user's current chat: show the right panel when this chat is active; otherwise queue it until the user returns. Before writing, confirm project ownership and the current source/version; show the target when this chat is active. Apply this shared rule across production, director, template and recreation edits.
-After the final source batch, complete the applicable delivery branch:
+For first delivery and continued edits, after the final requested source batch complete these steps:
- 1. Take `projectId`, `revision` and `versionId` from the save's `previewHandoff`. Call its `nextAction` (`motion_open_preview` with both expected identities) when the HTML is ready. A conflict means reread the current project and source, preserve intervening GUI changes, and prepare the preview with the newly read identities. Studio can add source handles on first open; do not overwrite that normalization with the old batch. Verify and acknowledge the current version returned by the successful open.
+ 1. Take `projectId`, `revision` and `versionId` from the save's `previewHandoff`. Call its `nextAction` (`openmotion_open_preview` with both expected identities) when the HTML is ready. A conflict means reread the current project and source, preserve intervening GUI changes, and prepare the preview with the newly read identities. Studio can add source handles on first open; do not overwrite that normalization with the old batch. Verify and acknowledge the current version returned by the successful open.
-2. Request the same project's native preview on the right. In Codex, call `open_in_codex` with `placement:"right"` in the calling chat; omit `threadId` unless the user asked for another chat. The host queues the action when its target chat is inactive. Reuse the actual native Tab ID when available; CUA wrapper `id` is not the host's `providerTabId`. A hidden `browser-use:` tab may be separate from the native right-panel tab. Without an established native Tab ID use the exact returned `previewUrl`, preserving embed/query/hash. Reuse an already queued same-project live preview while subsequent edits update that project; avoid duplicate tabs or a queue of frozen versions.
-3. Read the host acknowledgment **and separately observe visibility**. `queued` is neither success nor failure evidence. Rebind the actual native panel tab; a previous hidden automation tab can report false while a native tab is visible. In Codex IAB, after binding that tab, call the browser's supported `visibility.set(true)` capability once: it requests the calling chat's panel, queues while that chat is inactive, and does not navigate to it. Do not substitute another host's unverified focus-changing API. Observe `visibility.get()` as the host settles (bounded by the handoff's `settleTimeoutMs`); an immediate false can precede queued panel activation. If inactive, leave it queued and finish with “saved; latest preview will appear when you return.” Navigation remains forbidden by default. A still-hidden active-chat panel is a display failure to report. A closed/collapsed panel is not a request to skip preview entirely.
+2. Request the same project's native preview on the right. In Codex, call `open_in_codex` with `placement:"right"` in the calling chat; omit `threadId` unless the user asked for another chat. The host queues the action when its target chat is inactive. Reuse the actual native Tab ID when available; CUA wrapper `id` is not the host's `providerTabId`. Without an established native Tab ID use the exact returned `previewUrl`, preserving embed/query/hash. Rebind it from the current host inventory after presentation. If the matching native tab is absent, retry the same host presentation once, then report the gap; do not create a separate `visible:false` / `browser-use:` automation tab as a substitute. Hidden tabs remain valid for inspection only. Reuse an already queued same-project live preview while subsequent edits update that project; avoid duplicate tabs or a queue of frozen versions.
+3. Read the host acknowledgment **and separately observe visibility**. `queued` is neither success nor failure evidence and does not establish that the calling chat is inactive. Rebind the actual native panel tab; a previous hidden automation tab can report false while a native tab is visible. In Codex IAB, after binding that tab, call the browser's supported `visibility.set(true)` capability once: it requests the calling chat's panel, queues while that chat is inactive, and does not navigate to it. Do not substitute another host's unverified focus-changing API. Observe `visibility.get()` as the host settles (bounded by the handoff's `settleTimeoutMs`); an immediate false can precede queued panel activation. Only if the host confirms the calling chat is inactive, leave it queued and finish with “saved; preview queued for when you return.” Otherwise a still-hidden or unobservable panel is a display failure to report, even when the host acknowledged `queued`. Navigation remains forbidden by default. A closed/collapsed panel is not a request to skip preview entirely.
4. When the user returns, the host consumes its queued action. If executing a follow-up observation, use the handoff's `onReturn` action to resolve the **latest** project version, rather than replaying an old version-bound open or acknowledging the queued version. Locate the newest changed content at the affected time in the live preview, then recheck host visibility after inspecting it. A hidden WebContents screenshot, DOM `visibilityState`, metadata, a source read, file-watcher notification and a successful open alone do not prove visible freshness. Reload that native tab once if stale; preserve saved content and report any remaining failure. The host queue, not a continuing model turn, owns opening when the user returns; without a new observation leave the receipt pending. In disposable tests, consume queued actions before closing their tabs/server so an old queued tab cannot reappear later.
- 5. Record `motion_open_preview({action:"record_display",projectId,requestId,presentation,display:{revision,versionId,previewUrl,visibility,hostStatus,hostTabId,contentVerified,evidence}})` with the observed current version and a stable requestId per observation. Optional `hostStatus` preserves the acknowledgment (`queued` can coexist with actual `visibility:"visible"`); optional `hostTabId` preserves the established native ID as a reuse hint, validated against the current inventory. A closed tab's stale ID is omitted in favor of the fresh URL. Use `visibility:"queued"` only for confirmed inactive-chat deferral, with that host evidence; use `hidden` or `unavailable` for failed/unknown presentation. Every unconfirmed observation stays pending; only a visible preview with the latest content actually inspected can be `confirmed`. Report deferred delivery or the concrete display failure, without claiming the user has seen it or polling indefinitely. If export or packaging follows, retain this unresolved status in the final reply.
-5. Record `openmotion_open_preview({action:"record_display",projectId,requestId,presentation,display:{revision,versionId,previewUrl,visibility,hostStatus,hostTabId,contentVerified,evidence}})` with the observed current version and a stable requestId per observation. Optional `hostStatus` preserves the acknowledgment (`queued` can coexist with actual `visibility:"visible"`); optional `hostTabId` preserves the established native ID as a reuse hint, validated against the current inventory. A closed tab's stale ID is omitted in favor of the fresh URL. A queued/hidden observation stays pending; only a visible preview with the latest content actually inspected can be `confirmed`. Deferred delivery is reported as queued, without claiming the user has seen it or polling indefinitely.
++5. Record `openmotion_open_preview({action:"record_display",projectId,requestId,presentation,display:{revision,versionId,previewUrl,visibility,hostStatus,hostTabId,contentVerified,evidence}})` with the observed current version and a stable requestId per observation. Optional `hostStatus` preserves the acknowledgment (`queued` can coexist with actual `visibility:"visible"`); optional `hostTabId` preserves the established native ID as a reuse hint, validated against the current inventory. A closed tab's stale ID is omitted in favor of the fresh URL. Use `visibility:"queued"` only for confirmed inactive-chat deferral, with that host evidence; use `hidden` or `unavailable` for failed/unknown presentation. Every unconfirmed observation stays pending; only a visible preview with the latest content actually inspected can be `confirmed`. Report deferred delivery or the concrete display failure, without claiming the user has seen it or polling indefinitely. If export or packaging follows, retain this unresolved status in the final reply.
Only an explicit request such as “show it now / 现在展示” permits `presentation:"now"` for this turn, carried through save/open/display calls. Its recovery may take the verified calling-chat `threadId` from `open_in_codex`, call `navigate_to_codex_page({threadId})` once, and present/recheck the native tab. Use the host chat identity, not the OpenMotion sessionId. This permission does not persist into later ordinary edits. An ordinary “finish editing” or hidden/queued state is not immediate-display authorization.
diff --cc skills/openmotion-recreate/SKILL.md
index 00000000,fd8dc1cb..cef78753
mode 000000,100644..100644
--- a/skills/openmotion-recreate/SKILL.md
+++ b/skills/openmotion-recreate/SKILL.md
@@@ -1,0 -1,85 +1,85 @@@
+ ---
+ name: openmotion-recreate
+ description: >-
+ Recreate a reference video (a link or file) as the user's own film with OpenMotion: rebuild it as an
+ editable OpenMotion project and hand it over open in the editor, keeping the original content or
+ swapping in the user's copy, brand and assets. This includes small edits to
+ the user's own finished video when no editable project for it exists. "Make one like this" and "I
+ want this feel" both count as recreation. In a workspace with the user's product material, a bare
+ link alone means "make one like this for us". Not for only analysing or discussing a video. Use
+ openmotion-director when the reference is only inspiration for an original film,
+ openmotion-template-to-video for an existing template, openmotion-production for edits to an existing
+ editable OpenMotion project, and openmotion-video-to-template for a reusable template package.
+ ---
+
+ # OpenMotion Recreate — reference video → the user's own film
+
+ ## Role and goal
+
+ The user supplies a video and wants a version of it for themselves. Deliver the editable OpenMotion project, open in the editor, where the user reviews it and keeps editing. Before handing it over, export it and check the exported film against the reference by numeric measurement and by inspecting extracted frames; the export is for this check, not a file to send. This Skill carries the recreation rules and the measuring script; shared engineering rules still come from the documents in §0. [rebuild](references/rebuild.md) covers reading, measuring and rebuilding the reference; [check and deliver](references/verify.md) covers export and numeric measurement. Use only the Tools actually returned by tools/list.
+
+ This workflow currently covers motion graphics only. For live action, talking heads or AI footage, say that this workflow does not support them yet. Do not suggest that footage or other material would make such a recreation possible: material the user provides can only go into a motion-graphics adaptation, which you may offer. State the limit as a fact about this workflow; never mention, quote or link this Skill or its files in the reply.
+
+ ## 0. Shared context
+
+ Read the [shared context](../openmotion-production/references/context.md) before working; it lists the references a recreation needs and how to reuse documents already read. When the work changes an existing draft or project, also apply the [shared edit workflow](../openmotion-production/references/edit.md). If the reference turns out to be only loose inspiration for an original film, switch to [openmotion-director](../openmotion-director/SKILL.md).
+
+ ## 1. Read the user's context before anything else
+
+ Before asking anything, look in the current workspace for the user's own material: README and docs, product or marketing copy, brand files, logos, screenshots, colour or font definitions, package or site metadata. Read what is there. This is the user's brand, product and latest features; use it as the content of the film.
+
+ Then read the reference as [rebuild](references/rebuild.md) describes: a local decodable copy, its URL and checksum, the whole video and consecutive frames around important changes. Links and local files take the same route. A cover image or an unreachable link is not a viewed video; never claim to have watched it.
+
+ ## 2. Decide what the user wants
+
+ Work out the film the user wants from everything available: their words, whose film the reference is, what the workspace holds and the conversation so far. Short requests often mean more than they say. A bare link in a workspace with product material usually asks for a film like this about that product; "do this for our new feature" or "I want this feel" usually asks for the reference's craft carrying the user's story; an explicit list of changes asks for exactly those changes.
+
+ Whether the reference's brand stays or becomes the user's is your judgement from the request and context, not a fixed rule. When a wrong guess would change the whole film, such as "make one identical" while the workspace holds the user's own brand, put it in the single question below; otherwise decide and state the assumption at delivery.
+
+ Parts the request does not cover keep the original. Requested changes are in scope without restriction: wording, brand, images, colours, typography, pacing, duration, adding or removing scenes.
+
+ ## 3. Ask at most once
+
+ Ask only when the workspace and the request together still lack something only the user can supply (brand, product, claims, numbers, prices, logos, images), or when an ambiguity would materially change the result. With usable material in the workspace, do not ask who the film is for. Offer "you decide" where it fits. This package exposes no generation Tool: when a needed image, clip or sound is missing, use the user's material, ask for it, or offer a generation tool the host actually has; never generate a real logo, product photo or factual claim.
+
+ Ask all of it in one batch through the host's question interface, in the user's language. If nothing is missing, do not ask. Do not ask about technical choices, intermediate approval or storyboards. After the answers, work through to the finished film without stopping.
+
+ ## 4. Create the project
+
+ Follow the [runtime adapter](../openmotion-production/references/production.md) and [Native authoring](../openmotion-production/references/native.md). A continued recreation reuses its projectId. Otherwise create one project with `openmotion_create_project` and a stable requestId: `projectType: "reference_video"` with `referenceUrl` for a link, or `projectType: "natural_language"` for a local file, with the file path and the agreed brief in `requirements`. Creation makes an empty carrier, not a film, and never overwrites another project.
+
+ Read `openmotion_get_project({projectId})` for the directory, revision, current version, `hyperframesCli` and `authoringGuide`; read the pinned engine guide before writing source. Commands you run yourself (`node <hyperframesCli>`, the measurer, `ffmpeg`) use `node` and `ffmpeg` from `PATH`. The self-contained package does not put them on `PATH`: its directory is the one holding `node_modules/hyperframes` in the `hyperframesCli` path, with Node at `runtime/node/bin/node` (Windows `runtime\node\node.exe`) and FFmpeg/ffprobe in `runtime/media/bin`. For an npm installation there is no bundled `runtime/` directory: the application root is the directory containing `node_modules/hyperframes`, and `scripts/npm-runtime.mjs` exports `ensureNativeRuntime(appRoot)` and `nativeConfiguration(appRoot)`. Prepare through the former when needed; the latter returns `paths.HYPERFRAMES_FFMPEG_PATH` and `paths.HYPERFRAMES_FFPROBE_PATH` for the verified cache. Pass these as environment variables to the measurer or direct media commands. When neither is available, record the affected check as blocked with the reason; never as passed.
+
+ ## 5. Rebuild, then change
+
+ Follow [rebuild](references/rebuild.md) for understanding the video, choosing an editable representation, measuring and rebuilding. Build the user's version directly: rebuild the parts that stay faithfully and put the user's content into the rebuilt structure. Do not build a complete copy of the reference first only to change it again.
+
+ Import real media with `openmotion_import_assets` and use the returned paths; save text files (HTML, CSS, JS, SVG, JSON) with `openmotion_edit_project` using the latest `expectedRevision` and `expectedVersionId`. Re-read the project after a conflict instead of replaying an old batch.
+
+ When the reference is the user's own finished film and the request changes only a few details (a year, a line of copy, a logo) while everything else stays, the project may keep the original video as its base layer: import it, cover only the changed areas with clean patches and set the new text or logo as editable native elements that follow the original's timing and motion. Check that each patch leaves no smudge or seam against its surroundings. This is still the editor project and delivery below; never deliver an MP4 edited outside the project. Otherwise, placing the whole original video on the timeline is not a recreation, and an unrelated built-in template is not a substitute.
+
+ New content must keep the reference's craft, not just its palette. Match its visual density (a screen full of tiles stays full), camera and 3D motion (a tilted orbit stays tilted), type scale and type character (the closest available face of the same kind, such as a pixel, mono or wide display face, instead of a generic system font), and its background layers (line drawings, grids, textures). A line, label or headline that is clearly visible in the reference must be equally visible in the remix, and the remix must not be darker or lower-contrast than the reference. Simplifying a dense or 3D passage into a few flat cards is a defect to fix, not an acceptable approximation.
+
+ Apply the changes with care: fit longer text with related layout and reading-time changes, update every relevant appearance of a replaced brand or object, keep unrelated content and motion, never invent facts, and check audio timing when changes shift pictures.
+
+ Sound: when the reference has sound, the remix has sound. Keep the reference soundtrack by default (extract it as AAC `.m4a` and import it) and re-time it to the new cut; remove a voiceover that names the reference's brand or product. Deliver a silent film only when the user asks or the reference is silent.
+
+ Once this turn's requested HTML output is saved, complete the [editable preview handoff](../openmotion-production/references/native.md#editable-preview-handoff) automatically, before export or delivery.
+
+ ## 6. Export and check
+
+ Apply the [production decisions](../openmotion-director/references/production-decisions.md) and [Motion review](../openmotion-director/references/motion-review.md) to time structure, key actions, joins and state; still frames that look similar do not replace a moving comparison. Do not restart original creative direction.
+
+ Then follow [check and deliver](references/verify.md): export the inspected version, read the automatic technical verification, inspect the exported MP4, measure it against the reference with the bundled measurer and fix every failing row before delivery.
+
+ Opening the editor is a preview handoff, not completion of these checks. Keep working after it opens; the shared starter draft default does not replace this recreation workflow. Check small objects whose shape carries meaning with close crops as described in rebuild and verify: numerical similarity does not establish the correct contour. If a required check remains blocked or fails after the bounded retries, identify the project as an incomplete draft and state the specific gap.
+
+ ## 7. Deliver
+
+ The project open in the editor is the deliverable. Do not copy, link or attach the exported MP4 or other files unless the user asks for them.
+
-Reply briefly in the user's language. Give the `previewUrl` returned by `openmotion_open_preview` and say the project is open there for review and further edits. Say in one or two sentences what changed, which assumptions you made from the workspace material, and any limitation the user would notice. When the reference, analysis or tools fall short, name the specific gap and its effect; never claim a faithful result that was not achieved.
++Reply briefly in the user's language. Give the `previewUrl` returned by `openmotion_open_preview` and say the editor is open only after confirming visible latest content through the shared handoff; otherwise state the display failure or confirmed inactive-chat deferral, even if the MP4 exported successfully. Say in one or two sentences what changed, which assumptions you made from the workspace material, and any limitation the user would notice. When the reference, analysis or tools fall short, name the specific gap and its effect; never claim a faithful result that was not achieved.
+
+ ## 8. Follow-up requests
+
+ Apply follow-ups to the same project with the shared edit workflow and check them again as in §6; never start over. `openmotion_list_versions` and `openmotion_restore_version` bring back an earlier version as a new one. When the user is unhappy without saying why ("not satisfied", "第一版不太满意"), ask at most three multiple-choice questions in one batch, for example: follow the reference's story or tell our own; which feature is the hero; size and duration. Offer "you decide" as an option. Then revise the existing project.
diff --cc tests/npm-package.test.ts
index 46b3bf51,e612f912..b5b95277
--- a/tests/npm-package.test.ts
+++ b/tests/npm-package.test.ts
@@@ -108,8 -125,11 +125,11 @@@ test('test npm artifacts contain their
const help = await runFile(process.execPath, [cli, 'setup', '--help']);
for (const host of ['codex', 'claude', 'deepseek', 'workbuddy']) assert(help.includes(host), host);
await readFile(path.join(installer, 'package/LICENSE'));
- assert.deepEqual((await readdir(path.join(application, 'skills'))).sort(), [...phase1Skills].sort());
- for (const document of ['skills/motion-director/SKILL.md', 'skills/motion-production/references/context.md', 'skills/motion-production/references/native.md', 'skills/motion-production/references/verification.md', 'skills/motion-recreate/SKILL.md', 'phase1.ts', 'shared/phase1-tools.ts', 'shared/mcp-profiles.json']) {
+ assert.deepEqual((await readdir(path.join(application, 'skills'))).sort(), [...packagedSkills].sort());
+ assert.match(await readFile(path.join(application, 'skills/motion-production/agents/openai.yaml'), 'utf8'), /allow_implicit_invocation: false/);
+ assert.match(await readFile(path.join(application, 'skills/motion-production/SKILL.md'), 'utf8'), /disable-model-invocation: true/);
+ assert.match(await readFile(path.join(application, 'skills/openmotion-production/agents/openai.yaml'), 'utf8'), /OpenMotion Production/);
- for (const document of ['skills/openmotion-director/SKILL.md', 'skills/openmotion-production/references/context.md']) {
++ for (const document of ['skills/openmotion-director/SKILL.md', 'skills/openmotion-production/references/context.md', 'skills/openmotion-production/references/native.md', 'skills/openmotion-production/references/verification.md', 'skills/openmotion-recreate/SKILL.md', 'phase1.ts', 'shared/phase1-tools.ts', 'shared/mcp-profiles.json']) {
assert.equal(await readFile(path.join(application, document), 'utf8'), await readFile(document, 'utf8'));
}
assert.equal(await sha256(path.join(application, 'package-lock.json')), release.locks.npm);
diff --cc tests/preview-handoff.test.ts
index 90fd7bd2,461ace28..da3f70ec
--- a/tests/preview-handoff.test.ts
+++ b/tests/preview-handoff.test.ts
@@@ -23,14 -23,14 +23,14 @@@ function display(saved: any, visibilit
visibility, contentVerified, evidence: 'Host panel visibility read back; inspected the edited text in the live preview at 1s.' } };
}
-test('default deferred preview preserves the current chat and resolves the latest version on return', () => fixture(async store => {
+test('confirmed inactive-chat deferral preserves the current chat and resolves the latest version on return', () => fixture(async store => {
const service = api(store, async () => {}), p = await create(service), first = await edit(service, p, 'first');
- const opened = await service.call('motion_open_preview', first.previewHandoff.nextAction.arguments);
+ const opened = await service.call('openmotion_open_preview', first.previewHandoff.nextAction.arguments);
assert.equal(opened.previewHandoff.focusPolicy, 'preserve_current_chat');
assert.equal(opened.previewHandoff.nextAction.codex.recovery.tool, undefined);
- const queued = display(first, 'hidden', false);
- queued.display = { ...queued.display, hostStatus: 'queued' } as any;
+ const queued = display(first, 'queued', false);
+ queued.display = { ...queued.display, hostStatus: 'queued', evidence: 'Host confirms the calling chat is inactive; preview is queued for its return.' } as any;
- const pending = await service.call('motion_open_preview', queued);
+ const pending = await service.call('openmotion_open_preview', queued);
assert.equal(pending.previewHandoff.state, 'pending');
assert.equal(pending.previewHandoff.nextAction.operation, 'wait_for_calling_chat');
const second = await edit(service, first, 'second');
@@@ -38,27 -38,10 +38,27 @@@
const latest = await service.call(resume.tool, resume.arguments);
assert.equal(latest.currentVersionId, second.version.versionId);
assert.equal(latest.previewHandoff.focusPolicy, 'preserve_current_chat');
- await assert.rejects(service.call('motion_open_preview', display(first)), /VERSION_CONFLICT/);
- assert.equal((await service.call('motion_open_preview', display({ ...second, previewHandoff: latest.previewHandoff }))).previewHandoff.state, 'confirmed');
+ await assert.rejects(service.call('openmotion_open_preview', display(first)), /VERSION_CONFLICT/);
+ assert.equal((await service.call('openmotion_open_preview', display({ ...second, previewHandoff: latest.previewHandoff }))).previewHandoff.state, 'confirmed');
}, false));
+test('a queued acknowledgment with a hidden or unavailable panel retains presentation recovery', () => fixture(async store => {
+ const service = api(store, async () => {}), p = await create(service), saved = await edit(service, p, 'complete film');
+ const nativeTabId = crypto.randomUUID();
+ for (const visibility of ['hidden', 'unavailable']) {
+ const receipt = display(saved, visibility, true);
+ receipt.display = { ...receipt.display, hostStatus: 'queued', hostTabId: nativeTabId } as any;
- const result = await service.call('motion_open_preview', receipt);
++ const result = await service.call('openmotion_open_preview', receipt);
+ assert.equal(result.previewHandoff.state, 'pending');
+ assert.equal(result.previewHandoff.openedByHost, false);
+ assert.equal(result.previewHandoff.nextAction.operation, 'present_preview');
+ assert.equal(result.previewHandoff.nextAction.codex.arguments.target.url, saved.previewHandoff.previewUrl);
+ assert.equal(result.previewHandoff.nextAction.codex.arguments.target.tabId, nativeTabId);
+ assert.equal(result.previewHandoff.nextAction.codex.recovery.when, 'calling_chat_confirmed_inactive');
+ assert.equal(result.previewHandoff.nextAction.codex.recovery.tool, undefined, 'ordinary display recovery must not navigate chats');
+ }
+}, false));
+
test('every edit returns a version-bound foreground handoff without claiming the host opened', () => fixture(async store => {
const service = api(store), p = await create(service);
const first = await edit(service, p, 'first');