Specs: First draft of timer API for scheduling things for this frame or next frame or when idle.

sky/specs/animation.md

Index: sky/specs/animation.md
diff --git a/sky/specs/animation.md b/sky/specs/animation.md
index af6bd3efeb05bc79e8a4cac129814e00342642f4..60e2813670c67c50d29e2e000773ad6b07178ba7 100644
--- a/sky/specs/animation.md
+++ b/sky/specs/animation.md
@@ -1,27 +1,51 @@
 Animation API
 =============
 
-(This is very incomplete, because it's all expected to be in the
-framework, not the platform.)
+```dart
+typedef void TimerCallback();
 
-```javascript
+class AnimationTimer extends Timer {
+  external factory whenIdle(TimerCallback callback, { double budget: 1.0 });
+  // calls callback next time the system is idle
+  // - if budget is in the range 0.0 < budget <= 1.0, then callback is
+  //   guaranteed to have that many milliseconds before being killed
+  // - if budget <= 0.0, then the callback could be killed [at any time](script.md).
+  // - if budget > 1.0, then it is treated as 1.0.
+
+  external factory beforePaint(TimerCallback callback, { int priority: 0 });
+  // runs this timeout before this frame's layout/paint phases begin
+  external factory nextFrame(TimerCallback callback, { int priority: 0 });
+  // runs this timeout right away
+
+  // for beforePaint and nextFrame, the callbacks are first sorted by
+  // priority, and then run in decreasing order of priority,
+  // tie-breaking by registration time, earliest first.
+
+  // once there is no more time for callbacks this frame, the Timers
+  // are all canceled, so isActive will become false
 
-dictionary EasingFunctionSettings {
-  Float duration; // required
-  Callback? completionCallback = null;
 }
+```
+
+
+Easing Functions
+----------------
+
+```dart
+// part of the framework, not sky:core
+
+typedef void AnimationCallback();
 
 abstract class EasingFunction {
-  abstract constructor (EasingFunctionSettings settings);
-  abstract Float getFactor(Float time);
-    // calls completionCallback if time >= duration
-    // then returns a number ostensibly in the range 0.0 to 1.0
-    // (but it could in practice go outside this range, e.g. for
-    // animation styles that overreach then come back)
+  EasingFunction({double duration: 0.0, AnimationCallback completionCallback: null });
+  double getFactor(Float time);
+  // calls completionCallback if time >= duration
+  // then returns a number ostensibly in the range 0.0 to 1.0
+  // (but it could in practice go outside this range, e.g. for
+  // animation styles that overreach then come back)
 }
 ```
 
-
 If you want to have two animations simultaneously, e.g. two
 transforms, then you can add to the RenderNode's overrideStyles a
 StyleValue that combines other StyleValues, e.g. a