CSS View Transitions Module Level 1

1. Let transition be a new ViewTransition object in this’s relevant Realm.

2. Set transition’s update callback to updateCallback.

3. Let document be this’s relevant global object’s associated document.

4. If document’s active view transition is not null, then skip the view transition document’s active view transition with an "AbortError" DOMException in this’s relevant Realm.

   Note: This can result in two asynchronous update callbacks running concurrently. One for the document’s current active view transition, and another for this transition. As per the design of this feature, it’s assumed that the developer is using another feature or framework to correctly schedule these DOM changes.

5. Set document’s active view transition to transition.

   Note: The process continues in setup view transition, via perform pending transition operations, which is called in § 8.1 Monkey patches to rendering.

6. Return transition.

1. If this's phase is not "done", then skip the view transition for this with an "AbortError" DOMException.

1. For each fully active Document in docs, perform pending transition operations for that Document.

Note: These steps will be added to the update the rendering in the HTML spec. As such, the prose style is written to match other steps in that algorithm.

A navigable has no rendering opportunities if active document has transition suppressing rendering set to true.

Note: These steps will be added to the update the rendering in the HTML spec. See #7884 for more context.

1. If document’s active view transition is not null, then:

   1. If document’s active view transition's phase is "pending-capture", then setup view transition with document’s active view transition.

   2. Otherwise, if document’s active view transition's phase is "animating", then handle transition frame for document’s active view transition.

Note: This algorithm captures the current state of the document, calls the transition’s UpdateCallback, then captures the new state of the document.

1. Let document be transition’s relevant global object’s associated document.

2. Capture the old state for transition.

   If failure is returned, then skip the view transition for transition with an "InvalidStateError" DOMException in transition’s relevant Realm, and return.

3. Set document’s transition suppressing rendering to true.

4. Queue a global task on the DOM manipulation task source, given transition’s relevant global object, to execute the following steps:

   Note: A task is queued here because the texture read back in capturing the image may be async, although the render steps in the HTML spec act as if it’s synchronous.

   1. If transition’s phase is "done", then abort these steps.

      Note: This happens if transition was skipped before this point. The skip the view transition steps call the update callback, ensuring the transition’s update callback is always called.

   2. Call the update callback of transition.

   3. React to transition’s update callback done promise:

      • If the promise does not settle within an implementation-defined timeout, then:

        1. If transition’s phase is "done", then return.

           Note: This happens if transition was skipped before this point.

        2. Skip the view transition transition with a "TimeoutError" DOMException.

      • If the promise was rejected with reason reason, then:

        1. If transition’s phase is "done", then return.

           Note: This happens if transition was skipped before this point.

        2. Mark as handled transition’s ready promise.

           Note: transition’s update callback done promise will provide the unhandledrejection. This step avoids a duplicate.

        3. Skip the view transition transition with reason.

      • If the promise was fulfilled, then:

        1. If transition’s phase is "done", then return.

           Note: This happens if transition was skipped before this point.

        2. If transition’s initial snapshot containing block size is not equal to the snapshot containing block size, then skip the view transition for transition, and return.

        3. Set transition suppressing rendering to false.

        4. Capture the new state for transition.

           If failure is returned, then skip the view transition for transition with an "InvalidStateError" DOMException in transition’s relevant Realm, and return.

        5. For each capturedElement of transition’s named elements' values:

           1. If capturedElement’s new element is not null, then set capturedElement’s new element's involved in a view transition to true.

        6. Setup transition pseudo-elements for transition.

        7. Update pseudo-element styles for transition.

           If failure is returned, then skip the view transition for transition with an "InvalidStateError" DOMException in transition’s relevant Realm, and return.

           Note: The above steps will require running document lifecycle phases, to compute information calculated during style/layout.

        8. Set transition’s phase to "animating".

        9. Resolve transition’s ready promise.

1. Let document be transition’s relevant global object’s associated document.

2. Let namedElements be transition’s named elements.

3. Let usedTransitionNames be a new set of strings.

4. Let document be transition’s relevant global object’s associated document.

5. Set transition’s initial snapshot containing block size to the snapshot containing block size.

6. For each element of every element that is connected, and has a node document equal to to document, in paint order:

   The link for "paint order" doesn’t seem right. Is there a more canonical definition?

   1. If any flat tree ancestor of this element skips its contents, then continue.

   2. If element has more than one box fragment, then continue.

      We might want to enable transitions for fragmented elements in future versions.

   3. Let transitionName be the computed value of view-transition-name for element.

   4. If transitionName is none, or element is not rendered, then continue.

   5. If usedTransitionNames contains transitionName, then return failure.

   6. Append transitionName to usedTransitionNames.

   7. Let capture be a new captured element struct.

   8. Set capture’s old image to the result of capturing the image of element.

   9. Set capture’s old styles to the following:

      transform

      A transform that would map element’s border box from the snapshot containing block origin to its current visual position.

      This value is identity for the document element.

      width

      height

      The size of the snapshot containing block if element is the document element, otherwise, the width and height of element’s border box.

      object-view-box

      none if element is the document element, otherwise, an object-view-box value that, when applied to the old image, will cause the view box to coincide with element’s border box in the image. This must be expressed using inset().

      writing-mode

      The writing-mode of element.

      direction

      The direction of element.

      This needs proper types.

   10. Set namedElements[transitionName] to capture.

1. Let document be transition’s relevant global object’s associated document.

2. Let namedElements be transition’s named elements.

3. Let usedTransitionNames be a new set of strings.

4. For each element of every element that is connected, and has a node document equal to to document, in paint order:

   The link for "paint order" doesn’t seem right. Is there a more canonical definition?

   1. If any flat tree ancestor of this element skips its contents, then continue.

   2. Let transitionName be the computed value of view-transition-name for element.

   3. If transitionName is none, or element is not rendered, then continue.

   4. If usedTransitionNames contains transitionName, then return failure.

   5. Append transitionName to usedTransitionNames.

   6. If namedElements[transitionName] does not exist, then set namedElements[transitionName] to a new captured element struct.

   7. Set namedElements[transitionName]'s new element to element.

Note: This algorithm constructs the pseudo-element tree for the transition, and generates initial styles. The structure of the pseudo-tree is covered at a higher level in § 5.3 View transition pseudo-elements.

1. Let document be this’s relevant global object’s associated document.

2. Set document’s show view-transition root pseudo-element to true.

3. For each transitionName → capturedElement of transition’s named elements:

   1. Let group be a new ::view-transition-group(), with its view-transition name set to transitionName.

   2. Append group to transition’s transition root pseudo-element.

   3. Let imagePair be a new ::view-transition-image-pair(), with its view-transition name set to transitionName.

   4. Append imagePair to group.

   5. If capturedElement’s old image is not null, then:

      1. Let old be a new ::view-transition-old(), with its view-transition name set to transitionName, displaying capturedElement’s old image.

      2. Append old to imagePair.

      3. Let oldViewBox be capturedElement’s old styles object-view-box property.

      4. Set capturedElement’s old view-box rule to a new CSSStyleRule representing the following CSS, and append it to document’s view transition style sheet.

         :root::view-transition-old(transitionName) {
           object-view-box: oldViewBox;
         }
         

         Note: The above code example contains variables to be replaced.

   6. If capturedElement’s new element is not null, then:

      1. Let new be a new ::view-transition-new(), with its view-transition name set to transitionName.

         Note: The styling of this pseudo is handled in update pseudo-element styles.

      2. Append new to imagePair.

      The new element and its contents (the flat tree descendants of the element, including both text and elements, or the replaced content of a replaced element), except the transition’s transition root pseudo-element's inclusive descendants, are not painted (as if they had visibility: hidden) and do not respond to hit-testing (as if they had pointer-events: none) until new exists.

   7. If both of capturedElement’s old image and new element are not null, then:

      1. Let transform be capturedElement’s old styles's transform property.

      2. Let width be capturedElement’s old styles's width property.

      3. Let height be capturedElement’s old styles's height property.

      4. Set capturedElement’s group keyframes to a new CSSKeyframesRule representing the following CSS, and append it to document’s view transition style sheet:

         @keyframes -ua-view-transition-group-anim-transitionName {
           from {
             transform: transform;
             width: width;
             height: height;
           }
         }
         

         Note: The above code example contains variables to be replaced.

      5. Set capturedElement’s group animation name rule to a new CSSStyleRule representing the following CSS, and append it to document’s view transition style sheet:

         :root::view-transition-group(transitionName) {
           animation-name: -ua-view-transition-group-anim-transitionName;
         }
         

         Note: The above code example contains variables to be replaced.

      6. Set capturedElement’s image pair isolation rule to a new CSSStyleRule representing the following CSS, and append it to document’s view transition style sheet:

         :root::view-transition-image-pair(transitionName) {
           isolation: isolate;
         }
         

         Note: The above code example contains variables to be replaced.

      7. Set capturedElement’s view blend mode rule to a new CSSStyleRule representing the following CSS, and append it to document’s view transition style sheet:

         :root::view-transition-old(transitionName),
         :root::view-transition-new(transitionName) {
           mix-blend-mode: plus-lighter;
         }
         

         Note: The above code example contains variables to be replaced.

         Note: mix-blend-mode: plus-lighter ensures that the blending of identical pixels from the old and new images results in the same color value as those pixels, and achieves a "correct" cross-fade.

         Isolation and the dynamic setting of blending is only necessary to get the right cross-fade between new and old image pixels. Would it be simpler to always add it and try to optimize in the implementation?

Note: This is guaranteed to happen for every ViewTransition, even if the transition is skipped. The reasons for this are discussed in § 1.3 Transitions as an enhancement.

1. Assert: transition’s phase is "done", or before "update-callback-called".

2. Let callbackPromise be null.

3. If transition’s update callback is null, then set callbackPromise to a promise resolved with undefined, in transition’s relevant Realm.

4. Otherwise, set callbackPromise to the result of invoking transition’s update callback.

5. If transition’s phase is not "done", then set transition’s phase to "update-callback-called".

6. Resolve transition’s update callback done promise with the result of reacting to callbackPromise:

   • If the promise was fulfilled, then return undefined.

   Note: Since the rejection of callbackPromise isn’t explicitly handled here, if callbackPromise rejects, then transition’s update callback done promise will reject with the same reason.

1. Let document be transition’s relevant global object’s associated document.

2. Assert: document’s active view transition is transition.

3. Assert: transition’s phase is not "done".

4. If transition’s phase is before "update-callback-called", then queue a global task on the DOM manipulation task source, given transition’s relevant global object, to call the update callback of transition.

5. Set transition suppressing rendering to false.

6. Clear view transition transition.

7. Set transition’s phase to "done".

8. Reject transition’s ready promise with reason.

   Note: The ready promise may already be resolved at this point, if skipTransition() is called after we start animating. In that case, this step is a no-op.

9. Resolve transition’s finished promise with the result of reacting to transition’s update callback done promise:

   • If the promise was fulfilled, then return undefined.

   Note: Since the rejection of transition’s update callback done promise isn’t explicitly handled here, if transition’s update callback done promise rejects, then transition’s finished promise will reject with the same reason.

1. If element is the document element, then:

   1. Render the region of the element and the [/=document=]'s top layer that intersects the snapshot containing block, on a transparent canvas the size of the snapshot containing block, following the capture rendering characteristics, and these additional characteristics:

      • Areas outside element’s scrolling box should be rendered as if they were scrolled to, without moving or resizing the layout viewport. This must not trigger events related to scrolling or resizing, such as IntersectionObservers.

        

      • Areas that cannot be scrolled to (i.e. they are out of scrolling bounds), should render the canvas background.

        

   2. Return the canvas as an image. The natural size of the image is equal to the snapshot containing block.

2. Otherwise:

   1. Render element and its descendants, at the same size it appears in its node document, over an infinite transparent canvas, following the capture rendering characteristics.

   2. Return the portion of the canvas that includes element’s ink overflow rectangle as an image. The natural size of the image must be element’s border box's size, and its origin corresponds to the element’s border box's origin.

• The origin of element’s ink overflow rectangle is anchored to canvas origin.

• If the referenced element has a transform applied to it (or its ancestors), then the transform is ignored.

  Note: This transform is applied to the snapshot using the transform property of the associated ::view-transition-group pseudo-element.

• Effects on the element, such as opacity and filter are applied to the capture.

• Implementations may clip the rendered contents if the ink overflow rectangle exceeds some implementation-defined maximum. However, the captured image should include, at the very least, the contents of element that intersect with the snapshot containing block. Implementations may adjust the rasterization quality to account for elements with a large ink overflow area that are transformed into view.

• For each descendant of shadow-including descendant Element and pseudo-element of element, if descendant has a computed value of view-transition-name that is not none, then skip painting descendant.

  Note: This is necessary since the descendant will generate its own snapshot which will be displayed and animated independently.

  Refactor this so the algorithm takes a set of elements that will be captured. This centralizes the logic for deciding if an element should be included or not.

  Specify what happens with mix-blend-mode.

1. Let document be transition’s relevant global object’s associated document.

2. Let hasActiveAnimations be a boolean, initially false.

3. For each element of transition’s transition root pseudo-element's inclusive descendants:

   1. For each animation whose timeline is a document timeline associated with document, and contains at least one associated effect whose effect target is element, set hasActiveAnimations to true if any of the following conditions is true:

      The prose around "effect target" is incorrect, but #8001 needs to land before it can be fixed.

      • animation’s play state is paused or running.

      • document’s pending animation event queue has any events associated with animation.

        This prose isn’t quite right, but it’s blocked on #8004.

4. If hasActiveAnimations is false:

   1. Set transition’s phase to "done".

   2. Clear view transition transition.

   3. Resolve transition’s finished promise.

   4. Return.

5. If transition’s initial snapshot containing block size is not equal to the snapshot containing block size, then skip the view transition for transition, and return.

6. Update pseudo-element styles for transition.

   If failure is returned, then skip the view transition for transition with an "InvalidStateError" DOMException in transition’s relevant Realm, and return.

   Note: The above implies that a change in incoming element’s size or position will cause a new keyframe to be generated. This can cause a visual jump. We could retarget smoothly but don’t have a use-case to justify the complexity. See issue 7813 for details.

1. For each transitionName → capturedElement of transition’s named elements:

   1. Let width, height, transform, writingMode, and direction be null.

   2. If capturedElement’s new element is null, then:

      1. Set width to capturedElement’s old styles width property.

      2. Set height to capturedElement’s old styles height property.

      3. Set transform to capturedElement’s old styles transform property.

      4. Set writingMode to capturedElement’s old styles writing-mode property.

      5. Set direction to capturedElement’s old styles direction property.

   3. Otherwise:

      1. Return failure if any of the following conditions is true:

         • capturedElement’s new element has a flat tree ancestor that skips its contents.

         • capturedElement’s new element is not rendered.

         • capturedElement has more than one box fragment.

         Note: Other rendering constraints are enforced via capturedElement’s new element being involved in a view transition.

      2. Set width to the current width of capturedElement’s new element's border box.

      3. Set height to the current height of capturedElement’s new element's border box.

      4. Set transform to a transform that would map capturedElement’s new element's border box from the snapshot containing block origin to its current visual position.

      5. Set writingMode to the computed value of writing-mode on capturedElement’s new element.

      6. Set direction to the computed value of direction on capturedElement’s new element.

   4. If capturedElement’s group styles rule is null, then set capturedElement’s group styles rule to a new CSSStyleRule representing the following CSS, and append it to document’s view transition style sheet.

      Otherwise, update capturedElement’s group styles rule to match the following CSS:

      :root::view-transition-group(transitionName) {
        width: width;
        height: height;
        transform: transform;
        writing-mode: writingMode;
        direction: direction;
      }
      

      Note: The above code example contains variables to be replaced.

   5. If capturedElement’s new element is not null, then:

      1. Let new be the ::view-transition-new() with the view-transition name transitionName.

      2. Set new’s replaced element content to the result of capturing the image of capturedElement’s new element.

      3. Let newViewBox be an object-view-box value that when applied to new, will cause the view box to coincide with capturedElement’s new element's border box in the image. This must be expressed using inset().

      4. If capturedElement’s new view-box rule is null, then set capturedElement’s new view-box rule to a new CSSStyleRule representing the following CSS, and append it to document’s view transition style sheet.

         Otherwise, update capturedElement’s new view-box rule to match the following CSS:

         :root::view-transition-new(transitionName) {
           object-view-box: newViewBox;
         }
         

         Note: The above code example contains variables to be replaced.

This algorithm must be executed to update styles in user-agent origin if its effects can be observed by a web API.

Note: An example of such a web API is window.getComputedStyle(document.documentElement, "::view-transition").

1. Let document be transition’s relevant global object’s associated document.

2. Assert: document’s active view transition is transition.

3. For each capturedElement of transition’s named elements' values:

   1. If capturedElement’s new element is not null, then set capturedElement’s new element's involved in a view transition to false.

   2. For each style of capturedElement’s style definitions:

      1. If style is not null, and style is in document’s view transition style sheet, then remove style from document’s view transition style sheet.

4. Set document’s show view-transition root pseudo-element to false.

5. Set document’s active view transition to null.