CSS View Transitions Module Level 1

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

2. Set transition’s DOM update callback to callback.

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

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

   Note: This can result in two asynchronous DOM update callbacks running concurrently. One for the document’s current active DOM 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 DOM 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.

1. For each Document in docs with a transition suppressing rendering of true:

   Move this to the html spec. See html/8368.

   How should input be handled when in this state? The last frame presented to the user will not reflect the DOM state as it asynchronously switches to the new version. See issue 7797.

   Note: The aim is to prevent unintended DOM updates from being presented to the user after a cached snapshot for the elements has been captured. We wait for one rendering opportunity after prepare to present DOM mutations made by the author before prepare to be presented to the user. This is also the content captured in snapshots.

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.

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

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

   2. Otherwise, if document’s active DOM transition's phase is "animating", then update transition DOM for document’s active DOM transition.

1. Let namedElements be transition’s named elements.

2. Let usedTransitionNames be a new set of strings.

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

4. For each element of every Element and pseudo-element connected 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 any of the following is true:

      • usedTransitionNames contains transitionName.

      • element is not element’s root and element does not have layout containment.

      • element is not element’s root and element allows fragmentation.

      Then skip the view transition for transition with an "InvalidStateError" DOMException in transition’s relevant Realm, and return.

   5. Append transitionName to usedTransitionNames.

   6. Let capture be a new captured element struct.

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

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

      transform

      A CSS transform that would place element from the snapshot viewport origin to its current quad.

      This value is identity for the document element.

      width

      height

      The size of the snapshot viewport 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.

   9. Set namedElements[transitionName] to capture.

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

6. 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.

   "DOM manipulation task source" doesn’t link due to a bikeshed bug.

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

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

   2. Call the DOM update callback of transition.

   3. React to transition’s DOM updated 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 resolved, then:

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

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

        2. Set transition suppressing rendering to false.

        3. Let usedTransitionNames be a new set of strings.

        4. For each element of every Element and pseudo-element connected 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 any of the following is true:

              • usedTransitionNames contains transitionName.

              • element is not element’s root and element does not have layout containment.

              • element is not element’s root and element allows fragmentation.

              Then skip the view transition transition with an "InvalidStateError" DOMException, and return.

           5. Append transitionName to usedTransitionNames.

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

           7. Let capture be namedElements[transitionName].

           8. Let capture’s new element item be element.

        5. Setup transition pseudo-elements for transition.

        6. Update pseudo-element styles for transition.

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

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

        8. Resolve transition’s ready promise.

      • 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. Skip the view transition transition with reason.

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

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

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

4. If transition’s phase is before "dom-update-callback-called", then call the DOM update callback of transition.

5. Set transition suppressing rendering to false.

6. If transition’s phase is equal to or after "animating", then clear view transition transition.

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

8. Set document’s active DOM transition to null.

9. If transition’s ready promise has not yet been resolved, reject it with reason.

   Note: The ready promise would’ve been resolved if skipTransition() is called after we start animating.

10. React to transition’s DOM updated promise:

    • If transition’s DOM updated promise was resolved, then resolve transition’s finished promise.

    • If transition’s DOM updated promise was rejected with reason reason, then reject transition’s finished promise with reason.

1. If element is the document element, then:

   1. Render the region of the element and the top layer that intersects the snapshot viewport, on a transparent canvas the size of the snapshot viewport, 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.

        "scrolling box" and "layout viewport" are not exported. They either need exporting, or replaced with better references.

        

      • 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 viewport.

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. Let interestRectangle be the result of computing the interest rectangle for element.

      Note: The interestRectangle is the subset of element’s ink overflow rectangle that should be captured. This is required for cases where an element’s ink overflow rectangle needs to be clipped because of hardware constraints. For example, if it exceeds the maximum texture size.

   3. Return the portion of the canvas within interestRectangle as an image. The natural size of the image is equal to the interestRectangle bounds.

• 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.

• 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 view-transition pseudo-elements associated with transition:

   1. Let element be the view-transition pseudo-element.

   2. 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 idle 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. Set document’s active DOM transition to null.

   4. Resolve transition’s finished promise.

   5. Return.

5. Update pseudo-element styles for transition.

   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. Assert: element is not element’s node document's document element.

   Note: The document element is captured differently, as specified in capture the image.

2. If element’s ink overflow area does not exceed an implementation-defined maximum size, then return a rectangle that is equal to element’s ink overflow rectangle.

3. Otherwise:

   Define the algorithm used to clip the snapshot when it exceeds max size.

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

2. Let transitionRoot be the result of creating a new ::view-transition pseudo-element in document’s snapshot viewport.

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

   1. Let group be the result of creating a new ::view-transition-group() pseudo-element with the name transitionName.

      "name" should be defined/linked.

   2. Append group to transitionRoot.

      This should be better defined. I’m not sure if pseudo-elements have defined ways to modify their DOM.

   3. Let imagePair be a new ::view-transition-image-pair() pseudo-element with the name 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() replaced element pseudo-element, with the name 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.

         html::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() replaced element pseudo-element, with the name transitionName, displaying the capture the image of capturedElement’s new element.

      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 view-transition pseudo-elements, 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:

         html::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:

         html::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:

         html::view-transition-old(transitionName),
         html::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?

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. Set width to the current width of capturedElement’s new element's border box.

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

      3. Set transform to a transform that maps the capturedElement’s new element's border box from document origin to its quad from the snapshot viewport origin.

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

      5. 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:

      html::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() replaced element pseudo-element, with the name transitionName, displaying the capture the image of capturedElement’s new element.

      2. 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().

      3. 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:

         html::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. Assert: transition’s phase is before "dom-update-callback-called".

2. Let callbackPromise be a new promise in transition’s relevant Realm.

   • If transition’s DOM update callback is null, then resolve callbackPromise.

   • Otherwise, let callbackPromise be the result of invoking transition’s DOM update callback.

3. Set transition’s phase to "dom-update-callback-called".

4. React to callbackPromise:

   • If callbackPromise was resolved, then resolve transition’s DOM updated promise.

   • If callbackPromise was rejected with reason r, then reject transition’s DOM updated promise with r.

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

2. Remove all associated view-transition pseudo-elements from document.

   There needs to be a definition/link for "remove".

   There needs to be a definition/link for "associated".

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

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

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