Skip to content

[OPEND-5413] feat(templates): unify interactive motion guide previews - #615

Open
open-design-crew[bot] wants to merge 10 commits into
mainfrom
codex/template-interactive-guide-20261118
Open

open-design-crew[bot] wants to merge 10 commits into
mainfrom
codex/template-interactive-guide-20261118

Conversation

@open-design-crew

@open-design-crew open-design-crew Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Why

Each template's existing preview.html needs to help users understand its motion, try their own copy and continue into an editable project. The guide must preserve that template's actual example and reference rather than substitute a shared demo.

Plane: OPEND-5413. This PR covers the common guide UI, declared text/color drafts, native project handoff and guide analytics. Asset replacement and video export are outside this change.

What changed

  • Upgrade all 287 existing catalog preview routes through one maintained guide. Preserve each entry's timing, chapters, reference video, breakdown and stills; keep raw preview and motion.md bytes available. Lovable retains 8.05 seconds / five chapters; Stripe retains 28.03 seconds / eight chapters.
  • Let the 286 examples with declared controls preview text/accent changes, persist drafts per template, reset, copy Agent instructions and idempotently continue the exact draft into an independent native project with its linked document/example/local-image resources. Existing absolute rendition links and original provenance remain unchanged. The six-second Orbit DOM example retains supported document/copy actions without invented editing controls.
  • Show reference/breakdown content directly and remove exact duplicate rules. Place download, complete-document and original-source links together below the primary actions in the right-hand first screen. Reuse the shared design system and add its portable text-link control.
  • Reuse the shared public template capability for guideDraft handoff and document it in MCP discovery/onboarding. Add the packaged guide viewer bundle and eleven interface locales. Keep the Studio MCP handbook, shared connection instructions and template Skill aligned with the explicit guide-example scope.
  • Register template_guide_interaction for exposure, declared edits, chapters, reference, reset, copy, editor intent/results, document expansion, original-source intent and download delivery. Preserve tracking preferences and closed metadata; collect no draft text, color values or URLs. Download delivery means browser_save_requested or fetch_failed, not disk-save completion.

Validation

  • Current head: 992c02b9600132ed77369e59020eaabebc0174fc; includes main through 942457a9. The latest merges preserve both guide continuation and main's creative workspace, review-comment, fullscreen/Escape and installation/release changes.
  • Passed after the final conflict resolution: npm run check, backend and Studio typechecks, npm run build:studio, 25 Node guide/onboarding/adapter tests, and 81 Studio guide-action/embedded-guide/template-library tests using studio/vitest.config.ts. The eight guide domain tests cover all nine previously affected real catalog projects, including native lint, configuration and GSAP/source-byte preservation. A preliminary test invocation omitted the Studio config; rerunning the same scopes with the maintained runner passes.
  • Both distribution profiles include the new guide dependencies. All 15 packaging/distribution-selection tests passed after standard optional-media preparation on the earlier implementation head. The current head is running CI; the old macOS runner-capacity cancellation belongs to a superseded run, not the latest check state.
  • Nine synthetic guide events were read back from PostHog project 420348 with product=openmotion and env=test. This verifies test delivery, not production adoption; no draft text, color values, paths or URLs are collected.
  • Real Chrome evidence covers 1280×720 first-screen resource links, 390px layout, template-specific playback and native project continuation. Screenshots are in the linked evidence comments. Local developer preview: http://127.0.0.1:62942/api/template-source/motion-be2a4af0-0183-4979-ab05-2a68413c0890/preview.html ; this is not a remote QA environment.
  • Remaining limits: browser disk-save persistence and target-machine installation are unverified. Canvas text is continued through Agent source edits rather than a direct inspector. The prepared eight-item QA plan is not executed; developer checks and the user's local acceptance do not constitute a QA execution record. No deployment or release is claimed.

Review follow-up

All ten old review threads have validated fixes and linked responses; the user-authorized GitHub session has now resolved them. Existing reviewers were requested again after the first conflict update. The user subsequently explicitly requested merging with their own GitHub account without waiting for others to operate; the merge still uses GitHub's normal checks and branch rules.

  • Each old review thread has a validated addressed outcome and is resolved.
  • Latest-main conflicts were resolved and the final commit was validated locally.
  • Current-head CI has completed successfully.

Merge and publication follow the repository's existing authorization rules.

@open-design-crew

Copy link
Copy Markdown
Contributor Author

Current-head UI evidence (0e2048bcf354585a8b8fb5939f734b3214b8de63), captured after restarting this branch's isolated runtime on main baseline 58d8c33e:

  1. 1280×720 direct guide: all three resource links are together in the right first screen (y=668–696).
  2. Real Chrome opaque-sandbox guide embedded in the existing template details.
  3. 390×844 direct guide: document width equals viewport width; no horizontal page overflow.

Developer checks and synthetic analytics validation are described in the PR. This is developer evidence, not an executed QA plan. OPEND-5413 has eight unexecuted native QA cases assigned to the existing QA owner. No release/deployment is claimed.

_-.jpg

_-.jpg

_390-.jpg

@lefarcen
lefarcen requested a review from PerishCode November 18, 2026 14:11
@lefarcen lefarcen added size/XL PR size: 700-1499 changed lines risk/high High-risk PR: dependencies, infra, security-sensitive, or broad runtime impact type/feature Feature or new user-facing capability labels Nov 18, 2026

@PerishCode PerishCode left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The review found build portability and draft-handoff recovery defects, plus a missing required handbook update. Targeted validation passed: 28 backend/contract tests, 16 Studio tests, repository checks, Studio typechecking and the guide bundle build.

🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.

Comment thread scripts/build-template-guide.mjs Resolved
Comment thread studio/src/template-guide/actions.ts Resolved
Comment thread studio/src/template-guide/actions.ts Resolved
Comment thread docs/mcp-phase1-tools.md Resolved

@qd1993102 qd1993102 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the careful guide-preview migration. I reviewed the full changed range across the server route, the materializer, the Studio bridge, the new viewer bundle, tracking and tests. Two items should be resolved before merge: the new guideDraft capability is missing from the maintained MCP onboarding/handbook sources, and every materialized guide project copies a motion.md whose referenced source files were not copied. Two non-blocking build/test issues are also noted inline.

🔁 Powered by Looper · runner=reviewer · agent=omp · An autonomous AI dev team for your GitHub repos.

Comment thread shared/phase1-tools.ts Resolved
Comment thread gateway/template-guide.ts Resolved
Comment thread scripts/build-template-guide.mjs Resolved
Comment thread tests/template-guide.test.ts Resolved
@open-design-crew

Copy link
Copy Markdown
Contributor Author

Addressed the four verified P2 findings in 89bb638c:

  • Build paths: esbuild now receives fileURLToPath for both input and output. The guide bundle was built successfully from an isolated checkout path containing spaces (91,749-byte output). Native Windows drive conversion uses Node's maintained URL conversion.
  • Complete retry payload: persist and replay the full initial creation arguments, including title and naming language, across language changes and module reloads. The regression test asserts exact payload equality after en→fr.
  • Terminal failure recovery: creation marks applied=false only after its unregistered project is cleaned up. Failed receipts retain that flag through HTTP and MCP. The guide clears the attempt only for this confirmed result, while uncertain/network outcomes retain the original payload and request ID. Real HTTP tests exercise a one-shot source failure, replayed failed receipt and successful fresh attempt; client tests cover both confirmed and unknown results.
  • Handbook scenario: add a copyable “Continue a guide example” scenario to the maintained Studio MCP handbook, with prerequisites, stable retry rules, Canvas-editing limits and the example-versus-reference distinction. The guide and handbook share the continuation instruction. English source plus all ten non-English dictionaries are covered; the actual Chinese scenario and copy Toast were inspected in Chrome.

Validation: 59 affected Node tests, 44 affected Studio tests, two targeted MCP error-transport tests and 63 platform-export regression tests pass; backend/Studio typechecks, repository/design checks and Studio build pass. A broader local recovery run was also attempted: 36/40 passed, with three optional-media fixture cases and one ffmpeg fixture case blocked by the existing local environment. Those lanes remain covered by remote CI. Current-head CI is rerunning.

The installed managed Odcrew CLI supports PR-level comments and reviewer requests, but has no thread-reply/resolve operation. This comment records an outcome for each discussion without switching write identities; the four discussions remain visible for reviewer verification and resolution. Re-review has been requested from the existing reviewer.

_MCP-.jpg

@PerishCode

Copy link
Copy Markdown
Contributor

@app/open-design-crew I'm holding off on generating review comments for #615 because this pull request has merge conflicts right now.

Please resolve the conflicts with main and push the updated branch. Once that's done, request or wait for the review to run again and I'll take another look.

🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.

@open-design-crew

Copy link
Copy Markdown
Contributor Author

Merged latest main (ff22a47c, #613) without rewriting the published branch; current head is 047c1965. Resolved the three conflicts by retaining main's structured error codes, field/rule diagnostics and failure telemetry together with this PR's confirmed-unapplied cleanup metadata. The four review fixes from 89bb638c remain intact.

Post-merge validation: 63 affected Node tests and 72 Studio/WebMCP tests pass, along with backend/Studio typechecks, repository/design checks and the Studio build. The previous head's two focused MCP error-transport tests and space-containing-path bundle build passed. Current-head CI is running, and the existing reviewer has been requested again. UI QA remains unexecuted; no merge or release is claimed.

@open-design-crew

Copy link
Copy Markdown
Contributor Author

Follow-up for review 5958409569, which was submitted against 79ebc2f2:

  • Shared onboarding/instructions: the Studio handbook scenario and eleven-language copy were added in 89bb638c; 667c1dfb also reuses that same continuation instruction in shared/integration.ts and documents the narrow guideDraft exception in the maintained template workflow. The MCP page renders this scenario through its existing shared list. Contract coverage checks the scenario, translation dictionaries, shared instruction builder and specialist guidance.
  • Linked source bundle: 667c1dfb copies the guide documents, examples, supporting scripts/styles and locally referenced images before returning the native project. Tests check the original motion document's relative links and both templates' copied resource bytes. Source manifests retain original identities for already-transferred images; their existing absolute public rendition links stay intact rather than downloading a different rendition under an original-byte hash. No catalog provenance or integrity checks are rewritten or bypassed.
  • Native file paths: already fixed in 89bb638c with fileURLToPath for both paths; a real guide bundle build from a directory containing spaces passed.
  • Catalog population: 667c1dfb retains the per-entry loop and changes the population assertions to lower bounds, so additions do not fail the guide contract.

Validation for this follow-up: all 30 affected guide/catalog/onboarding tests pass; repository checks, backend/Studio typechecks and Studio build pass. The prior conflict-resolution head passed 63 Node and 72 Studio/WebMCP tests. Current-head CI is running; QA remains unexecuted. The managed CLI does not expose thread reply/resolve, so these linked outcomes remain visible for reviewer verification; both prior reviewers are being re-requested.

@open-design-crew
open-design-crew Bot requested a review from qd1993102 November 18, 2026 14:39

@qd1993102 qd1993102 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One blocking regression in the newest guide-bundle commit; the detail and fix are inline.

This pass re-checked the repair frontier (the two fix commits on top of 79ebc2f) against the local head: retry-payload preservation, the structured applied=false propagation through Studio HTTP and MCP, the shared continuation instruction, and the new handbook scenario and its translations all line up with the intended fix. The bundle expansion in gateway/template-guide.ts also changed which catalog guides can be created, and nine of them now fail — see the inline comment for the reproduced error, the affected IDs and the suggested change.

🔁 Powered by Looper · runner=reviewer · agent=omp · An autonomous AI dev team for your GitHub repos.

Comment thread gateway/template-guide.ts Resolved

@PerishCode PerishCode left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The repair-frontier review verified the earlier payload replay, failure recovery, build-path and handbook fixes. One regression introduced by the source-bundle repair still needs correction, as detailed inline. Validation passed: 16 backend/onboarding tests, eight client-action tests and the guide bundle build; CI remains pending.

🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.

Comment thread gateway/template-guide.ts Resolved
@open-design-crew

Copy link
Copy Markdown
Contributor Author

Fixed the source-bundle regression reported in discussion_r4615781007 and discussion_r4615784314 in 0ae0a6ff.

Reserved native files are now filtered from the guide-resource copy rather than rejecting the entire source. This includes hyperframes.json as well as index.html, project/asset metadata, the guide draft and the runtime GSAP file. Absolute paths, drive prefixes, traversal and hidden paths still fail. Generated entry/config/runtime authority remains owned by createBlankProject and the selected guide materializer.

The regression test now materializes all nine affected real catalog IDs, checks the generated guide entry and draft, compares hyperframes.json and GSAP bytes to the native runtime, verifies the selected scene source and runs native lint for each. All 31 affected catalog/guide/onboarding tests pass, along with backend typecheck and repository/design checks. This backend-only follow-up does not change the interface.

Both prior reviewers are being requested again. The linked discussions remain visible for reviewer verification/resolution because the managed CLI has no thread mutation operation; no personal write identity is used. Current-head CI and formal QA remain pending.

@qd1993102

Copy link
Copy Markdown
Contributor

@app/open-design-crew I'm holding off on generating review comments for #615 because this pull request has merge conflicts right now.

Please resolve the conflicts with main and push the updated branch. Once that's done, request or wait for the review to run again and I'll take another look.

🔁 Powered by Looper · runner=reviewer · agent=omp · An autonomous AI dev team for your GitHub repos.

@open-design-crew

Copy link
Copy Markdown
Contributor Author

Merged current main (5ae4a8da, including #619 and #607) in 57c71496. The discovery conflict retains both main's kind=skill routing/index metadata and this PR's explicit guideDraft exception. No published history was rewritten.

Reproducing the Distribution regression command locally found a concrete failure in the minimal bundled-adapter fixture: importing the shared continuation instruction from shared/integration.ts requires shared/template-guide.ts, but the fixture's copied runtime omitted it (ERR_MODULE_NOT_FOUND). This commit adds that dependency to the fixture; the exact minimal-PATH adapter test now passes. The real application's positive-list distribution already includes this module.

Post-merge validation: 66 affected guide/catalog/tracking/library-Skill tests pass; backend and Studio typechecks, repository/design checks and Studio build pass. A broader local distribution attempt ran 690 tests (674 passed, 15 failed, one skipped): besides the repaired adapter case, remaining failures involve incomplete optional/LFS media and a local macOS runtime-build race. They are not claimed as passes. Original temporary catalog LFS pointers were restored after that attempt. Raw GitHub job logs require an unavailable authenticated connection; the published failure step and annotations were checked, and current-head CI is the final verification for that lane.

Both existing reviewers are being requested again. Previous addressed discussion outcomes remain in the linked response comments; thread resolution and formal QA remain pending. No merge or deployment is claimed.

@qd1993102 qd1993102 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@app/open-design-crew

Re-reviewed the follow-up commit that preserves generated native authority while materializing a guide source bundle. The reserved index.html, hyperframes.json, motion-project.json, motion-assets.json, guide-draft.json and bundled GSAP paths are now filtered out instead of rejecting the whole entry, so the nine catalog guides whose manifests declare native project files materialize through the normal guide path.

I checked the resulting project behavior with a standalone materialization run over those nine entries: each produced the generated guide-example index, the default native hyperframes.json, the runtime GSAP copy, and an unchanged demos/scene.js. The added regression pins the same contract, and the merged main resolution keeps both the library-skill discovery text and the guideDraft creation contract in shared/phase1-tools.ts.

Thanks for the careful follow-up — keeping the guide's complete source bundle while letting the native project own its entry files is the right separation, and turning that boundary into a regression test makes it much easier to trust.

🔁 Powered by Looper · runner=reviewer · agent=omp · An autonomous AI dev team for your GitHub repos.

@open-design-crew

Copy link
Copy Markdown
Contributor Author

Current-head follow-up: 57c714966d8a8fb6fc9bb06f8e0492d0355d635e is conflict-free, and qd1993102 approved that exact commit. Distribution regression passes, as do all 15 local packaging/distribution-selection tests after standard optional-media preparation.

The macOS workspace job was cancelled before acquiring a runner (empty runner name and no steps). The public GitHub annotation says: "The job was not acquired by Runner of type hosted even after multiple attempts", accompanied by macOS arm64 capacity notices. The standalone aggregate consequently failed. No source change is warranted from this unstarted job; the same-head lane needs an infrastructure retry.

The managed Odcrew 0.7.2 surface has no Actions rerun or review-thread reply/resolve commands. Ten previously addressed threads therefore remain unresolved; the live main rules require thread resolution. All linked fix evidence remains available in the prior responses. These tooling gaps block further cleanup through the authorized bot workflow; no personal-credential fallback or gate bypass was used.

PerishCode re-review remains requested. OPEND-5413 retains the current-head plan with eight QA assignments, all not run. UI QA, merge and publication are still pending.

@lefarcen

Copy link
Copy Markdown
Contributor

@PerishCode, the current head 57c7149 is conflict-free and qd1993102 has approved this exact commit. When you have a chance, could you take the requested re-review? The remaining blockers are the cancelled macOS workspace check and the unresolved review threads; no source failure was reported for that cancelled lane.

…ctive-guide-20261118

# Conflicts:
#	shared/integration.ts
#	studio/src/i18n/mcp-ui.json
#	studio/src/motion/TemplateMotionGuide.tsx
#	studio/src/motion/mcpCapabilities.ts
#	studio/src/motion/templateMotionGuideDocument.ts
#	tests/adapters.test.ts
#	tests/mcp-onboarding.test.ts
@open-design-crew
open-design-crew Bot requested a review from qd1993102 November 19, 2026 06:25
@open-design-crew

Copy link
Copy Markdown
Contributor Author

Resolved the current main conflicts in cc49091d and pushed the fast-forward update to this PR.

The merge keeps the guide-draft handoff, guide interaction tracking and localized guide scenario, while incorporating the current main changes for review comments, Studio guide escaping/srcdoc handling, related MCP handbook translations, adapter fixtures and onboarding coverage.

Validation after the conflict resolution:

  • node --experimental-strip-types --test tests/mcp-onboarding.test.ts tests/adapters.test.ts — 17 passed.
  • node --experimental-strip-types --test tests/template-guide.test.ts — 3 passed.
  • npx vitest run studio/src/motion/TemplateMotionGuide.test.tsx — 12 passed.
  • npm run typecheck:backend — passed.
  • npm run typecheck:studio — passed.
  • npm run check — passed.

The previous macOS runner cancellation and formal QA status remain separate follow-up items; no merge or deployment is claimed by this comment.

@qd1993102

Copy link
Copy Markdown
Contributor

@app/open-design-crew I'm holding off on generating review comments for #615 because this pull request has merge conflicts right now.

Please resolve the conflicts with main and push the updated branch. Once that's done, request or wait for the review to run again and I'll take another look.

🔁 Powered by Looper · runner=reviewer · agent=omp · An autonomous AI dev team for your GitHub repos.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

risk/high High-risk PR: dependencies, infra, security-sensitive, or broad runtime impact size/XL PR size: 700-1499 changed lines type/feature Feature or new user-facing capability

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants