Repository navigation
[KS][MOT] API: Windows motion engine (Composition) #237
Description
Part of #42 · Umbrella #9 · Task key MOT.win-core · Follow-up to #174
Goal
A Windows implementation of the @legendapp/spark/motion engine from #174. Today getMotionAvailability() reports unsupported-platform on Windows, every operation fails with E_UNSUPPORTED_PLATFORM, MotionView throws it when rendered, and packages/motion declares no Windows native project.
Why it was not done in #174
- [KS][MOT] API: core animation engine #174 was built on a macOS host with no Windows machine or VM, so no Windows Composition code could be compiled, run or checked visually.
- No Windows black-box backend exists to run the motion flows ([KS][INFRA] Windows black-box backend (UI Automation + SendInput) and OS-state commands #51), and a compositor engine cannot be accepted from generated bundles alone.
Design (from docs/motion.md#windows)
- Reuse
packages/motion/cpp(spark::motion::Engine) unchanged: it is portable C++ with no platform types and already does solving, interruption, timelines, completion and baking. - RNW glue resolves the element's
VisualwithElementCompositionPreviewand converts each baked channel into linearKeyFrameAnimations onOffset,Scale,RotationAngleInDegrees(centre point at half size) andOpacity. Loop periods useIterationBehavior.Forever. - Scroll links observe
ScrollViewer.ViewChanged; frame telemetry and the virtual clock (CompositionAnimationControllerpause, driversetClock/advanceClock) need a Windows driver too. - Define Fluent-tuned spring presets alongside the macOS (SwiftUI) presets.
Scope
- RNW module and
SparkMotionViewcomponent inpackages/motion/windows, sharing the C++ engine - Truthful
getMotionAvailability()on Windows; Windows presets inspring() -
motion-systemflows run on Windows x64 and ARM64
Acceptance
- The Kitchen Sink
motion-systemscreens animate on Windows, light/dark, LTR/RTL - A 500 ms JavaScript block during an animation drops no frames
MOT-*checks listwindowsinplatformsand pass in the release gate
Blocked by
- [KS][INFRA] Windows black-box backend (UI Automation + SendInput) and OS-state commands #51 (Windows black-box backend)
Activity
[KS] API: core animation engine (#174) (#248)
sethwebster commentedon Oct 12, 2026
Scope addition from #176 (MOT.effects): the Windows engine also needs the visual-effect properties (OKLCH backgroundColor, borderRadius, shadow, blur, rotateX/rotateY/perspective, mask insets), MotionNumber and MotionText (which only need the engine and MotionView), and a design for symbol effects (SF Symbols do not exist on Windows). All of them are typed E_UNSUPPORTED_PLATFORM on Windows today; docs/motion.md#windows sketches the Composition mapping.
sethwebster commentedon Oct 12, 2026
Scope from #407 (PR #430):
MotionMaterialandgetMaterialAvailabilityare typed unsupported on Windows (E_UNSUPPORTED_PLATFORM/unsupported-platform) until Composition backdrop brushes are wired. Intended glue (docs/motion.md#windows):withinWindow→CreateBackdropBrush,behindWindow→CreateHostBackdropBrush(with Acrylic-style blur and tint effects);materialIntensityandmaterialTintOpacity→ the brush visual's and the tint visual'sOpacitykeyframes from the shared engine bake; a material change → two brush visuals crossfaded bymaterialCrossfade. Reduce Transparency →UISettings.AdvancedEffectsEnabled.[KS] Motion: animatable backdrop materials (#407)
[KS] Motion: animatable backdrop materials (#407) (#430)
sethwebster commentedon Oct 13, 2026
Scope added by #406 (MotionShape: shape morph and stroke drawing). On Windows
MotionShapethrowsE_UNSUPPORTED_PLATFORMlike every motion component (checked bye2e/flows/motion-system/windows-unsupported.yaml, MOT-UNSUP-01). Intended glue: aCompositionSpriteShapewhoseCompositionPathGeometrytakes the engine's baked sample paths (every path has the same cubic structure, as on macOS) asPathKeyFrameAnimationkeyframes formorph;strokeStart/strokeEndontoTrimStart/TrimEnd,strokeWidthontoStrokeThickness, andfillColor/strokeColorontoCompositionColorBrushColorKeyFrameAnimations (each sample converted from OKLCH).lineCap,lineJoinandfillRulemap ontoStrokeStartCap/StrokeEndCap,StrokeLineJoinandCompositionPathGeometry's fill rule. See docs/motion.md#shapes.sethwebster commentedon Oct 13, 2026
Scope added by #405 (PR #442: MotionShader shader effects and MotionEmitter particles). On Windows
MotionShaderandMotionEmitterthrowE_UNSUPPORTED_PLATFORM,startParticles/stopParticlesreject with it, andgetShaderEffectAvailability/getParticleAvailabilityreportunsupported-platform(checked bye2e/flows/motion-system/windows-unsupported.yaml, MOT-UNSUP-01). Intended glue (docs/motion.md#windows): ripple and distortion as Win2DDisplacementMapEffectbrushes over aCompositionVisualSurfaceof the element, the specular sweep as an animatedCompositionLinearGradientBrush, the dissolve as a precompiled pixel shader behind aCompositionEffectBrushmask (or a Direct2D custom effect), and particles as a Composition sprite pool, with the same 1,000-particle budget, Reduce Motion rules and built-in-only shaders.[KS] Motion: shape morph and stroke drawing (#406) (#439)
[KS] Motion: shader effects and particles (#405)
[KS] Motion: shader effects and particles (#405) (#442)