dsh-motion-ui 0.7.1 → 0.8.0

package/skills/motion-design/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Support. While redistributing the Work or
+      Derivative Works thereof, You may choose to offer, and charge a
+      fee for, acceptance of support, warranty, indemnity, or other
+      liability obligations and/or rights consistent with this License.
+      However, in accepting such obligations, You may act only on Your
+      own behalf and on Your sole responsibility, not on behalf of any
+      other Contributor, and only if You agree to indemnify, defend,
+      and hold each Contributor harmless for any liability incurred by,
+      or claims asserted against, such Contributor by reason of your
+      accepting any such warranty or support.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Open Design contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/skills/motion-design/NOTICE.md

@@ -0,0 +1,9 @@
+# Third-party notice
+
+Motion Design skill — Copyright 2026 Open Design contributors.
+
+Source: https://github.com/nexu-io/open-design/tree/14fee234e6eb268058fed17ba979d8e22798dd34/skills/motion-design
+
+`SKILL.md` and `SOURCES.md` are unmodified upstream files. Their upstream Apache-2.0 license is included as `LICENSE`. `upstream.json` records the pinned source revision and exact skill SHA256.
+
+`ADAPTER.md` and the Motion UI reference loader are original Motion UI integration code/documentation. OpenDesign-specific commands and player contracts remain in the original source for completeness; the separate adapter maps them to DSH.

package/skills/motion-design/SKILL.md

@@ -0,0 +1,388 @@
+---
+name: motion-design
+description: "Apply motion craft to an active task: refine a brief, beat map, visual continuity, typography, pacing, and timeline implementation. Use when planning or improving motion graphics; the host task owns artifact creation, output format, and export."
+triggers:
+  - motion design
+  - motion graphics
+  - 视频动效
+  - 动态设计
+  - MG动画
+  - kinetic typography
+  - animated explainer
+od:
+  mode: utility
+  category: animation-motion
+  featured: -100
+  example_prompt: Create a 15-second motion film for a focus timer. Show scattered thoughts converging into one clear task, with expressive typography, a continuous visual motif, and a confident closing frame.
+---
+
+# Motion Design
+
+Use this functional helper to refine the user's brief or work in progress with
+one clear idea expressed through composition, transformation, rhythm, and appropriate sound unless the user requires silence. Apply the relevant craft guidance within the current task; this
+skill is not a rendering template and does not create a project or choose an
+output format. The Motion Design creation route owns those decisions. Quality
+means viewers understand and remember the idea while wanting to watch it move.
+
+## Execution context
+
+Follow the active host's task route, stage, capability, and delivery contract.
+This skill supplies motion craft; it does not create tool access or change the
+host's workflow. In OD Next, retain its Core, general orchestration, keyed
+production-ready marker, and ship-on-write default. Plan in ordinary language;
+author during production. Never emit Plan Contract or Runtime State blocks,
+request protocol repair, or claim a host-frozen delivery contract. Only actual
+user-requested video-motion production, when the host Core authorizes it,
+permits the bounded video check below. For a video brief (a timed
+film, promo, explainer or showreel), declare BOTH editable HTML source and MP4
+as required deliverables. Rendering the MP4 is Build production and must finish
+before delivery. For pointer/scroll-driven interaction or UI micro-animation,
+deliver runnable HTML/code instead; do not flatten the requested interaction
+into video. Never describe an unrendered video file as complete.
+
+Where the active task's tools and scope permit visual iteration, examine the
+opening, key transformation, transition,
+text hold and ending at intended size, plus continuous playback. Correct the
+largest observable defect, then revisit only affected moments. A runnable file
+alone is not proof of successful motion. Distinguish what was observed from
+what was only specified; never invent quality measurements.
+
+## Resolve the brief without stalling
+
+Use the user's assets, references, script and previous decisions first. Resolve:
+message and audience; destination/aspect; duration; exact copy; must-show assets;
+visual direction; audio; and required output. Ask only when missing information
+would change the story or make the result misleading. Otherwise choose a coherent
+direction and state the meaningful assumption briefly. Do not impose three
+style options or an approval round on a user who asked you to make the piece.
+
+For an unconstrained short film, a useful starting point is 12–18 seconds,
+16:9, 1920×1080, 30fps, no invented voiceover, and a replayable source. A portrait
+social brief calls for 9:16. Existing brand, timing, platform and copy override
+these defaults. Do not invent product claims, metrics, testimonials or assets.
+
+Create a compact beat map as part of the existing plan, not a second document:
+`time → viewer takeaway → focal object → transformation → copy/audio → exit`.
+Time budget includes entrances, reading holds and exits. Choose a recurring
+object, shape, line or typographic motif that connects the beats.
+
+Example mechanism for a focus product (adapt, do not copy as a universal style):
+scattered words orbit → one word attracts the others → orbit becomes a timer →
+timer completes and becomes the wordmark. Each movement changes the meaning;
+four unrelated title cards would lose the mechanism.
+
+## Art direction before adding movement
+
+Resolve one strong representative frame in the composition before expanding
+all scenes. Choose the actual hierarchy, crop, type, palette, texture and focal
+object. A weak still will not be rescued by particles, camera shake or effects.
+When planning-only, describe this frame; do not create an artifact early.
+
+- Use a specific visual premise tied to the subject. "Premium", "cinematic"
+  and "modern" alone are not art directions. Define what fills the frame,
+  where attention rests, the material language and the contrast structure.
+- Typography is a graphic object. Compose with scale, alignment, line breaks,
+  negative space and font character. Choose fonts that cover the actual
+  language; use tested fallbacks and wait for font readiness before capture.
+- Prefer a small palette with intentional contrast. No default neon gradient,
+  glass cards, glowing orb or beige background independent of the brief.
+- Choose one material/world logic: editorial ink, precise instrument, folded
+  paper, tactile collage, vector geometry, painterly field, or another justified
+  system. Carry its lighting, edges and textures through the film.
+- A scene may be asymmetric, full-bleed or sparse. Avoid repeatedly centering
+  a headline above three cards. Keep subtitles and platform chrome out of the
+  focal area; use destination-specific safe margins, not one universal ratio.
+- Supplied product screens and logos retain their proportions and content.
+  Crop deliberately rather than stretching. Keep data axes, units and values
+  correct through their entire animation.
+
+## Choreograph attention
+
+Choose the lead action and let supporting motion answer it. Offset independent
+objects when that clarifies reading; move them together when collective motion
+is the idea. Do not mechanically stagger every word or enforce a fixed moving
+fraction of the screen.
+
+Use three possible layers, not three mandatory effects:
+1. Primary action carries the idea.
+2. Secondary action conveys weight or causality: a trailing label, a shadow
+   settling, an elastic edge, a reaction in a connected object.
+3. Ambient motion provides life only when the scene needs it. Quiet scenes
+   and reading holds may be genuinely still.
+
+Timing and spacing have different jobs: timing places story beats; spacing
+controls acceleration and weight between them. Suggested starting ranges:
+
+| Job | Starting range | Shape |
+| --- | --- | --- |
+| Small accent / punctuation | 120–220ms | decisive snap, then settle |
+| Main element arrival | 350–650ms | quick travel, controlled landing |
+| Meaningful shape transformation | 600–1200ms | readable setup and resolution |
+| Large reveal / camera move | 900–1800ms | sustained trajectory, clear destination |
+
+These are film heuristics, not UI response-time limits. Fit distance, mass,
+emotion and soundtrack. Use ease-out for an arrival, ease-in for a motivated
+exit, and smooth acceleration/deceleration for a camera. Constant-speed travel
+is appropriate for conveyors, clocks, scans and intentional mechanical motion.
+Playful material can overshoot; precise instruments should not bounce by default.
+
+- Give fast actions preparation and recovery. Anticipation may be tiny, but
+  there should be a legible cause rather than an unexplained teleport.
+- Change position on arcs when physical motion calls for it. Use straight
+  paths for precision, direction or mechanical intent.
+- Match-cut across shared shapes, track a moving object into the next scene,
+  reveal through a meaningful mask, or use a clean cut. Choose transitions
+  because of the relationship between beats, not a desire for variety.
+- Preserve velocity and direction at hand-offs. Avoid accidental jumps in
+  scale, lighting or object identity. Morph only where topology supports it;
+  a designed match-cut is better than an unreadable mesh distortion.
+- Alternate action and rest. Reserve the strongest transformation for the
+  central idea; endless maximum intensity makes everything feel equal.
+- Close intentionally: resolve the motif and hold the final message. Loops
+  need matching start/end state AND velocity, without a duplicated pause.
+
+## Choose a visual grammar
+
+**Product / brand film:** build around a real benefit and a concrete action.
+Use actual screens where available, isolate what changes, and carry the brand
+motif into the closing frame. A slow camera move over a static page is supporting
+footage, not the entire demonstration.
+
+**Kinetic typography:** let words act out meaning through weight, tracking,
+direction and transformation. Keep a stable reading window; do not rotate,
+blur or scatter every line. Animate a phrase as a unit when word-by-word entry
+would obstruct comprehension. Reveal timing is not reading time.
+
+**Explainer / data:** choose spatial metaphors that preserve the causal model.
+Show the object before transforming it; maintain labels while relationships
+change. Reveal axes before values when the scale matters. If narrated, align
+beats to actual supplied or generated audio timing, not guessed timestamps.
+Do not add unrelated decoration to cover a weak explanation.
+
+**Art / procedural scene:** distinguish a style's structure from surface noise.
+Define marks, material, palette, composition and one characteristic movement.
+Examples: a woodcut uses cut-line direction and layered ink; a painted night
+uses coherent curved strokes and moving light; paper cutouts use plane depth,
+edge shadows and hinged motion. Seed texture once and move it coherently;
+regenerating every mark each frame causes flicker. Animate elements inside the
+world, not only the camera between static paintings. Human identity and complex
+anatomy should use suitable supplied/generated assets when tools allow; keep
+silhouette, palette and lighting consistent. Never pretend those assets exist.
+
+**3D / professional-tool task:** retain the user's existing AE, Blender or
+Remotion project if specified and available. Read its state, edit the smallest
+relevant scene, and retain editable layers/keyframes. A tool-specific pipeline
+is justified by the desired result, not by the name of this skill. Do not make
+installation of AE, Blender, a paid provider or a new framework the default.
+
+## Author reliable editable motion
+
+For a new Open Design film, use timeline-driven HTML with GSAP and optional
+SVG/Canvas. HTML/SVG suit typography, crisp diagrams and UI; Canvas suits dense
+marks, fields and procedural worlds. Combine them when useful. Preserve an
+existing supported renderer instead of rebuilding it just to fit this default.
+
+Keep duration, frame size, palette, type scale, easing and scene timings in one
+small configuration. Group each scene's elements and motion together. Separate
+content/data from drawing. Reuse geometry and cached textures; cap offscreen
+work and particle counts. Keep a scene stable at any requested timestamp.
+
+The Open Design video composition contract:
+
+```html
+<div id="main" data-composition-id="main" data-start="0"
+     data-duration="15" data-width="1920" data-height="1080" data-poster-time="13.5">
+  <!-- Real scene elements, sized for this stage. -->
+</div>
+<script>
+// Load GSAP before this block; retain the host's pinned dependency when supplied.
+const duration = 15;
+const tl = gsap.timeline({ paused: true });
+// Define initial states explicitly, then animate scene objects at absolute times.
+// tl.fromTo(...); tl.to(...); Reading holds occupy real time in the timeline.
+const clock = { t: 0 };
+tl.to(clock, { t: duration, duration, ease: 'none' }, 0);
+window.__timelines = { main: tl };
+// A procedural layer must draw from clock.t, not increment state each frame.
+// Video export seeks with timeline callbacks suppressed, so draw from a
+// per-frame loop rather than from onUpdate alone:
+// (function render() { drawWorld(clock.t); requestAnimationFrame(render); })();
+</script>
+```
+
+This is a protocol skeleton, not a finished visual template. Author the real
+composition. Root duration, timeline duration, aspect and the brief must agree.
+Use real seconds: the master timeline must keep `timeScale(1)`, no repeat or
+start delay, and its actual `duration()` must equal `data-duration`. The setter
+`tl.duration(seconds)` changes playback speed; it does NOT add a reading hold.
+Use the full-length clock tween above, and keep all tracks within its duration.
+The player and renderer reject inconsistent video clocks before export.
+
+For SVG pop/scale entrances, establish a shared origin BEFORE the from state.
+Animate a common group for related shapes (a disk and its shading), or set the
+same `svgOrigin` in both states. Do not set it only in the destination: GSAP
+smooth-origin compensation can offset shapes with different bounding boxes.
+
+```js
+function popShape(tl, node, cx, cy, at, duration = 0.45) {
+  const svgOrigin = cx + ' ' + cy;
+  tl.fromTo(node, { scale: 0, svgOrigin },
+    { scale: 1, svgOrigin, duration, ease: 'back.out(2)' }, at);
+}
+```
+Use the actual composition id consistently. Register timelines before signalling
+readiness; all image/font dependencies need a known ready state. Keep assets
+local when possible and avoid relying on inaccessible remote URLs.
+
+Deterministic motion must survive forward/backward seeking: no Date.now-based
+scene state, unseeded randomness, simulation that only works after playing from
+zero, or independent CSS animation competing with the master timeline. Define
+positions and reveals as functions of time, or as seekable timeline tracks.
+Never make visible content depend on timeline callbacks (onUpdate, onComplete);
+the MP4 exporter seeks with them suppressed.
+Audio-reactive motion needs a precomputed envelope or known beat map when exact
+replay matters. Never imply that an arbitrary pulse is analysis of the music.
+
+Open Design scaffolds and embeds shared source playback: open the HTML to
+automatically loop the film, with no separate player bar. Click the picture to
+pause/resume or unlock audio blocked by browser autoplay. The internal
+`window.__odMotionPlayer` interface retains play/pause, seek and replay. Preserve its `script[data-od-motion-source-player]`. Do not create
+competing controls or start a second playback clock. The renderer sets
+`window.__odMotionRender` before author scripts to disable preview chrome and
+scaling during capture. The scaffold includes pinned GSAP 3.14.2 at
+`./gsap.min.js`; preserve and reference that local file. No download is needed. Prefer installed/system fonts with Chinese coverage; an unrequested font
+must not block delivery. If an optional download fails, use an available font
+instead of probing more mirrors, installing font tools or creating environments.
+For an existing standalone source without the host player, put controls outside the
+composition and connect them to the same master timeline. Scale the whole stage
+uniformly to fit; do not reflow scene layout when the viewport changes. Controls
+must not appear in the exported frames. Keep a useful poster when reduced motion
+is requested and let the user explicitly start playback.
+
+## Plan and produce sound for video
+
+For a video motion brief, decide voice, music and effects separately in the
+existing Design Spec and beat map. If the film benefits from music or sound
+accents and the user has not requested silence, add suitable sound proactively.
+“No voiceover” disables speech only; it does not mean no music or effects.
+An explicit silent/muted/no-sound request wins. Choose silence when justified
+by the destination (for example a silent ambient loop), and state that choice.
+This policy belongs to video motion; do not add sound to ordinary prototypes,
+documents, slides or interactive motion unless their brief calls for it.
+
+Record the audio decision in the ordinary plan. Declare
+`<meta name="od-motion-audio" content="required">` for an audible film or
+`content="silent"` for intentional silence. This is composition metadata for
+the actual exporter, not a model-output planning contract.
+For `required`, author real local audio assets inside the composition directory:
+use supplied/licensed media, the host audio-generation tool when available, or
+an original synthesized instrumental/effect WAV. Do not invent an asset URL,
+install an unrelated audio environment, or substitute a pulsing visual for sound.
+If required audio production fails, report the blocker instead of delivering
+silence as complete.
+
+Declare every track with the renderer's supported timing, for example:
+`<audio src="assets/music.wav" data-start="0" data-duration="15" data-volume="0.3" preload="auto"></audio>`.
+Effects use the same contract with their own start and duration. Keep sources
+local and relative, pre-trim tracks, and avoid loop, playback-rate and media-start
+attributes. Keep music below speech and align accents to the actual beat map.
+Preserve the shared source player: it automatically loops picture and sound, and synchronizes audio to play,
+pause, seek and replay. Do not start a second audio clock or use Web Audio alone, which is
+not an exportable track. The renderer mixes these tracks into the MP4.
+
+In the existing bounded video check, verify source audio follows those controls,
+that downloaded MP4 contains an audible audio track, and that key sounds occur
+at the authored times. A file extension or an audio tag alone does not prove
+sound. Silent films remain valid; never require audio for other task types.
+
+## Video production and dual delivery
+
+For video briefs, use Open Design's existing local HyperFrames renderer during
+Build. It needs no video-generation API key. Do not ask the user to render it
+manually or run a second renderer. Plan declares `hyperframes-html` as the
+production route, editable source as canonical, and MP4 as a required derived
+output. For interactive briefs use `html` and source only.
+
+Keep source and MP4 paths in the readable plan and in the composition's MP4
+link. The exporter checks its actual output path and the declared audio policy;
+Open Design does not parse or freeze a model-authored plan. Do not add machine
+blocks or a contract-repair turn.
+
+Apply this delivery guidance only to the user's actual current video-motion
+request, including an explicit video-motion request in another project. A
+selected scenario or loaded helper alone does not authorize creating a film.
+Plan-only requests end with the plan; interactive motion and hover/scroll
+animation in a prototype remain runnable HTML. Follow-ups may directly edit an
+existing film; re-render only when the requested change affects the video.
+
+1. Scaffold a visible source directory with the native shell tool:
+   `"$OD_NODE_BIN" "$OD_BIN" media scaffold --project "$OD_PROJECT_ID" --composition-dir "motion-source/film"`.
+   Use a new descriptive directory for a new film; edit the existing source on
+   revisions. Keep `hyperframes.json`, `meta.json`, HTML and local assets there.
+2. Author `motion-source/film/index.html`. Its composition root must have
+   `data-composition-id="main"`, `data-start="0"`, `data-duration`, `data-width`,
+   `data-height` and `data-fps`. Register the seekable master timeline at
+   `window.__timelines.main`. Use actual GSAP animations, not a placeholder
+   timeline. Keep assets/fonts local and relative to this source directory.
+   Include `<meta name="od-motion-output" content="video">` and
+   `<link rel="alternate" type="video/mp4" href="../../film.mp4">` in the head.
+   The href must identify the actual planned MP4 inside the project. The
+   interactive equivalent declares `content="interactive"` and needs no MP4.
+   For video, choose a stable, representative moment in your actual timeline
+   and declare its time in seconds as `data-poster-time` on that root. It must
+   satisfy `0 <= time < data-duration`; avoid an empty opening or a transition.
+   Prefer a frame that communicates the product or main idea at thumbnail size.
+   The host validates the source/video clock and dimensions and extracts this
+   exact frame from the finished MP4. Do not generate a separate invented cover,
+   change the video's opening for the cover, or bake preview containers into it.
+3. Render through the host:
+   `"$OD_NODE_BIN" "$OD_BIN" media generate --project "$OD_PROJECT_ID" --surface video --model hyperframes-html --composition-dir "motion-source/film" --output "film.mp4"`.
+   If it returns a task ID, use `"$OD_NODE_BIN" "$OD_BIN" media wait <id>` and wait for success.
+   A queued task, HTML preview or failed command is not a completed film.
+4. Preserve the source and assets, and link BOTH the actual MP4 and the source
+   HTML in the final response using project-relative Markdown links. The file
+   viewer provides preview/download. On later video edits re-render the same
+   linked MP4 so the download matches the current source.
+
+If the host reports a renderer failure, preserve the editable source and report
+that blocker truthfully. Never fabricate a download or label HTML-only output
+as a finished video. Only actual user-requested video-motion production, and
+only when the host Core authorizes it, permits this bounded check:
+
+- During planning, retain factual invariants and exact required copy in the
+  existing Design Spec/beat map. An explainer must preserve the causal mechanism
+  and exceptions when shortening subtitles; decorative metaphors are not facts.
+- After the first render, perform one review of the actual source and exported
+  video: check the clock/dimensions, compare captions against those invariants,
+  and inspect at most three representative frames (opening, key explanation,
+  ending). Check related SVG shapes stay aligned. Use available host/browser/
+  frame tools and actually view the images; source reading alone is not visual
+  evidence. Do not claim a check that tool access did not allow.
+- If that review or the renderer identifies a concrete defect, make at most one
+  targeted repair and re-render; recheck only the affected facts/frames. If still
+  incorrect or unverifiable, report the limitation instead of certifying it.
+- Do not spawn acceptance agents, score aesthetics, add a separate pipeline
+  stage, or repeat an open-ended polish loop. Interactive motion, prototypes,
+  slides, documents and other tasks keep their existing ship-on-write policy.
+
+## Quality while composing
+
+For each beat, account for focal point, motion cause, reading time and exit.
+At a transition, account for both outgoing and incoming states and their overlap.
+At the end, account for resolution, holding time and replay behavior.
+
+Use these concrete defect-to-decision pairs while building:
+
+| Defect | Better decision |
+| --- | --- |
+| Feels like a slideshow | Carry one object through a meaningful transformation |
+| Everything competes | Choose the lead action; reduce or delay support |
+| No sense of weight | Adjust travel time, acceleration, anticipation and settle |
+| Text is unreadable | Shorten copy only if allowed; increase hold and contrast |
+| Looks generic | Strengthen type, composition and the subject-specific motif |
+| Painterly texture flickers | Seed and cache marks; move a coherent field |
+| Sequence feels monotonous | Vary shot scale and action/hold rhythm with purpose |
+| Looks busy but says little | Remove decorative motion and show the causal action |
+
+Do not invent a numeric score to certify aesthetics. Report the usable artifact,
+its duration/aspect, and any missing asset, audio or export capability succinctly.

package/skills/motion-design/SOURCES.md

@@ -0,0 +1,16 @@
+# Design sources
+
+This is an original Open Design skill, informed by these public approaches:
+
+- https://github.com/alchaincyf/huashu-art-motion — representative-frame-first art direction, motion within a scene, deterministic procedural drawing, and separating aesthetic judgment from technical signals.
+- https://github.com/LottieFiles/motion-design-skill — emotional intent, timing versus spacing, easing, and primary/secondary/ambient choreography.
+- https://github.com/LobzyJay/motion-design-with-claude-and-codex — restraint, specific motion decisions, and preserving the user's working tool.
+
+No upstream engine, character assets, sample film, or style-card library is
+vendored. The broad film workflow is adapted to Open Design's existing timeline
+preview/export contract. Heuristics remain defaults, not universal aesthetic laws.
+
+The maintained entrypoint is `skills/motion-design/SKILL.md`. The OD Next sealed
+package carries a generated identical copy. From the repository root run
+`pnpm exec tsx scripts/sync-motion-design-skill.ts` after editing it. The daemon's
+motion-design integration test rejects drift and exercises the actual bundle.

package/skills/motion-design/upstream.json

@@ -0,0 +1,8 @@
+{
+  "modified": false,
+  "retrieved": "2026-10-17",
+  "sha256": "19525f19eb62f0f69924c679e08e9a9c07d5bc378fa1fabd736af26413603b76",
+  "path": "skills/motion-design/SKILL.md",
+  "upstream": "https://github.com/nexu-io/open-design",
+  "commit": "14fee234e6eb268058fed17ba979d8e22798dd34"
+}