Add details of migration (w3c#73)

 - Introduce state and its serialization concept
 - Fix many link issues
 - Animation now has a timeline and list of attached timelines

Author: majido

index.bs

@@ -29,6 +29,9 @@ urlPrefix: https://heycam.github.io/webidl/; type: dfn;
     url: es-invoking-callback-functions; text: Invoke
 urlPrefix: https://html.spec.whatwg.org/#; type: dfn;
     url: run-the-animation-frame-callbacks; text: running the animation frame callbacks
+urlPrefix: http://w3c.github.io/html/infrastructure.html#; type: dfn;
+    text: structuredserialize
+    text: structureddeserialize
 urlPrefix: https://www.w3.org/TR/css3-transitions/#; type: dfn;
     text: animatable properties
 urlPrefix: https://w3c.github.io/web-animations/#; type: dfn;
@@ -271,26 +274,26 @@ and owns the instance specific state such as animation effect and timelines. It
  - An <dfn>animator current time</dfn> which is the corresponding <a>worklet animation</a>'s current
      time.
 
- - An <dfn>animator timelines list</dfn> which is <a>list</a> of its attached <a>timelines</a>.
+ - An <dfn>animator timeline</dfn> which is a <a>timeline</a>.
+
+ - An <dfn>animator attached timelines</dfn> which is <a>list</a> of attached <a>timelines</a>
+
+ - An <dfn>animator serialized options</dfn> which is a serializable object.
 
 
 Creating an Animator Instance {#creating-animator-instance}
 -----------------------------------------------------------
 
-Each <a>animator instance</a> lives in an {{AnimationWorkletGlobalScope}}. The <a>animator
-instance</a> cannot be disposed arbitrarily (e.g., in the middle of running animation as it may
-contain the scripted animation state.
-
-Issue: This is no longer true as we provide destroy callback.
+Each <a>animator instance</a> lives in an {{AnimationWorkletGlobalScope}}.
 
 Each {{AnimationWorkletGlobalScope}} has an <dfn>animator instance set</dfn>. The set is populated
 when the user agent constructs a new <a>animator instance</a> in the {{AnimationWorkletGlobalScope}}
 scope. Each <a>animator instance</a> corresponds to a worklet animation in the document scope.
 
 <div algorithm="create-animator">
 
-To <dfn>create a new animator instance</dfn> given a |name|, |timeline|, |effect|, |options|, and
-|workletGlobalScope|, the user agent <em>must</em> run the following steps:
+To <dfn>create a new animator instance</dfn> given a |name|, |timeline|, |effect|, |serializedOptions|,
+|serializedState|, and |workletGlobalScope|, the user agent <em>must</em> run the following steps:
 
     1. Let the |definition| be the result of looking up |name| on the |workletGlobalScope|'s
          <a>animator name to animator definition map</a>.
@@ -301,18 +304,25 @@ To <dfn>create a new animator instance</dfn> given a |name|, |timeline|, |effect
 
     3. Let |timelineList| be a new <a>list</a> with |timeline| added to it.
 
-    4. Let |animatorInstance| be the result of <a>Construct</a>(|animatorCtor|, [|options|]).
+    4. Let |options| be <a>StructuredDeserialize</a>(|serializedOptions|).
+
+    5. Let |state| be <a>StructuredDeserialize</a>(|serializedState|).
+
+    6. Let |animatorInstance| be the result of <a>Construct</a>(|animatorCtor|, [|options|, |state|]).
 
         If <a>Construct</a> throws an exception, abort the following steps.
 
-    5. Set the following on |animatorInstance| with:
+
+    7. Set the following on |animatorInstance| with:
         - <a>animator name</a> being |name|
         - <a>animation requested flag</a> being <a>frame-current</a>
         - <a>animator current time</a> being unresolved
         - <a>animator effect</a> being |effect|
-        - <a>animator timelines list</a> being |timelineList|
+        - <a>animator timeline</a> being |timeline|
+        - <a>animator attached timelines</a> being |timelineList|
+        - <a>animator serialized options</a> being |options|
 
-    6. Add |animatorInstance| to |workletGlobalScope|'s <a>animator instance set</a>.
+    8. Add |animatorInstance| to |workletGlobalScope|'s <a>animator instance set</a>.
 
 </div>
 
@@ -345,12 +355,11 @@ instance set</a>. For each such |instance| the user agent <em>must</em> perform
        belonging to the |instance| will not be visible within the visual viewport of the current
        frame the user agent <em>may</em> abort all the following steps.
 
-        Issue: Consider giving user agents permission to skip running animator instances to
-        throttle slow animators.
+       Issue: Consider giving user agents permission to skip running animator instances to
+       throttle slow animators.
 
   4. Let |animateFunction| be |definition|'s <a>animate function</a>.
 
-
   5. Let |currentTime| be <a>animator current time</a> of |instance|.
 
   6. Let |effect| be <a>animator effect</a> of |instance|.
@@ -370,7 +379,63 @@ Removing an Animator Instance {#removing-animator}
 To <dfn>remove an animator instance</dfn> given |instance| and |workletGlobalScope| the user agent
 <em>must</em> run the following steps:
 
-1. Remove |animatorInstance| from |workletGlobalScope|'s <a>animator instance set</a>.
+1. Remove |instance| from |workletGlobalScope|'s <a>animator instance set</a>.
+
+</div>
+
+Migrating an Animator Instance {#migrating-animator}
+-----------------------------------------
+User agents are responsible for assigning an animator to a worklet global scopes of which many can
+exist across different threads or processes. In order to give the most flexibility to user agents in
+this respect, we allow migration of an animator while it is running.
+
+The section defines a migration process such that any author-defined effect that depends on internal
+state can maintain its state across such migrations. The basic mechanism for achieving this is to
+serialize the state and later restore it.
+
+<div algorithm="migrate-animator">
+
+When user agents wants to <dfn>migrate an animator instance</dfn> from one worklet global scope
+to another given |instance|, |sourceWorkletGlobalScope|, |destinationWorkletGlobalScope|,
+it <em>must</em> run the following steps :
+
+  1. Let |serializedState| be undefined.
+
+  2. <a>Queue a task</a> on |sourceWorkletGlobalScope| to run the following steps:
+
+     1. Let |animatorName| be |instance|'s <a>animator name</a>
+
+     2. Let the |definition| be the result of looking up |animatorName| on the
+        |sourceWorkletGlobalScope|'s <a>animator name to animator definition map</a>.
+
+        If |definition| does not exist then abort the following steps.
+
+     4. Let |prototype| be the result of <a>Get</a>(|animatorCtor|, "prototype").
+
+     5. Let |onDestroyFunction| be the result of <a>Get</a>(|prototype|, "onDestroy").
+
+     6. If the result of <a>IsCallable</a>(|onDestroyFunction|) is false then abort the following
+        steps.
+
+     7. <a>Invoke</a> |onDestroyFunction| with |instance| as the <a>callback this value</a> and let
+        |state| be the result of this invocation.
+
+     8. Set |serializedState| to be the result of <a>StructuredSerialize</a>(|state|).
+        If any exception is throws, then abort the following steps.
+
+     9. <a>remove an animator instance</a> given |instance|, and |sourceWorkletGlobalScope|.
+
+  2. Wait for the above step complete.
+
+  3. <a>Queue a task</a> on |destinationWorkletGlobalScope| to run the following steps:
+
+     1. <a>create a new animator instance</a> given:
+        - The |instance|'s <a>animator name</a> as name.
+        - The |instance|'s <a>animator timeline</a> as timeline.
+        - The |instance|'s <a>animator effect</a> as effect.
+        - The |instance|'s <a>animator serialized options</a> as options.
+        - The |serializedState| as state.
+        - The |destinationWorkletGlobalScope| as workletGlobalScope.
 
 </div>
 
@@ -384,7 +449,7 @@ Each <a>animator instance</a> has an associated <dfn>animation requested flag</d
 either <dfn>frame-requested</dfn> or <dfn>frame-current</dfn>. It is initially set to
 <a>frame-current</a>. Different circumstances can cause the <a>animation requested flag</a> to be
 set to <a>frame-requested</a>. These include the following:
-  - Changes in the <a>current time</a> of any <a>timeline</a> in the animator's <a>animator timelines list</a>
+  - Changes in the <a>current time</a> of any <a>timeline</a> in the animator's <a>animator attached timelines</a>
   - Changes in the <a>current time</a> of the animator's corresponding <a>Worklet Animation</a>
 
 [[#running-animators]] resets the <a>animation requested flag</a> on animators to
@@ -410,7 +475,7 @@ animation's output.
 
 <a>Worklet animation</a> has the following properties in addition to the {{Animation}} interface:
   - an <dfn>animation animator name</dfn> which identifies it's <a>animator definition</a>.
-  - a <dfn>serialized options</dfn> which is <a>serializable</a> object that is used when
+  - a <dfn>serialized options</dfn> which is serializable object that is used when
     constructing a new animator instance.
 
 <figure>
@@ -467,7 +532,7 @@ Creates a new {{WorkletAnimation}} object using the following procedure.
     4. Run the procedure to <a>set the target effect of an animation</a> on |workletAnimation|
          passing |effect| as the new effect.
 
-    5. Let |serializedOptions| be the result of {{StructuredSerializeWithTransfer(options)}}.
+    5. Let |serializedOptions| be the result of <a>StructuredSerialize</a>(|options|).
         Rethrow any exceptions.
 
     6. Set the <a>serialized options</a> of |workletAnimation| to |serializedOptions|.
@@ -527,11 +592,11 @@ When a given |workletAnimation|'s <a>play state</a> changes to <a>pending</a>, <
     |workletAnimation|.
   3. <a>Queue a task</a> on |workletGlobalScope| to run the procedure to <a>create a new animator
        instance</a>, passing:
-      * The |workletAnimation|'s animation animator name as |name|.
-      * The |workletAnimation|'s timeline as |timeline|.
-      * The |workletAnimation|'s effect as |effect|.
-      * The |workletAnimation|'s serialized options as |options|.
-      * The |workletGlobalScope| as |workletGlobalScope|.
+      * The |workletAnimation|'s <a>animation animator name</a> as name.
+      * The |workletAnimation|'s <a>timeline</a> as timeline.
+      * The |workletAnimation|'s <a>animation effect</a> as effect.
+      * The |workletAnimation|'s <a>serialized options</a> as options.
+      * The |workletGlobalScope| as workletGlobalScope.
   4. If the procedure was successful, set the resulting <a>animator instance</a> as corresponding to
     |workletAnimation|.