Are the events meant to be blocking or not blocking?

The following diagram shows a simplified representation of the status quo. When navigate() is called, several preparatory steps are performed before the actual view transition, such as loading the target page.

The upper red arrow is when the view transition API takes the "screenshot" for the before image, and the lower red arrow marks the point when the DOM got updated and defines the after state for the view transition.

The view transition itself should not be delayed by loading the DOM or similar, as the view would appear frozen during this time. There should also be no new layout or rendering of the current page between these two arrows, as this would be seen as flickering.

The green blocks are where the current events are dispatched.

graph TD
  subgraph rout[router.ts]
    subgraph API
      direction LR
      nav("navigate()")
      subgraph Events
        eas("astro:after-swap")
        eal("astro:load")
      end
    end

    subgraph flow[Processing Flow]
      osp{"same<br>page?"}
      ff("Load newDocument from URL")
      hco("Postprocess newDocument")    
      ssp("Save scroll position")
      subgraph VTR["<b>View Transition</b>"]
        psl("Preload style links")
        subgraph Swap
          swb("Merge &lt;html>-attributes,<br>&lt;head> and &lt;body><br>of current and newDOM")
          mpe("Copy over persisted elements")
          uhsp2("Move to Location")
          emas("Dispatch astro:after-swap")
        end
      end
      uhsp["Move to Location"]
      flowend["end"]
      RS("Run Scripts")
      empl("Dispatch astro:page-load")
      AN("Announce")
    end
  end
  nav-->osp--"no"-->ff-->hco-->ssp-->psl-->swb-->mpe-->uhsp2-->emas-->RS-->empl-->AN-->flowend
  osp--"yes"-->uhsp------>flowend
   style emas fill:#060,stroke:#333,stroke-width:4px
   style empl fill:#060,stroke:#333,stroke-width:4px
   linkStyle 4,9 stroke:#f00

The design principles for View Transitions are an easy-to-use solution with only a few lines of client-side code.

While this works well in most cases, there are many innovative ideas on how to extend the current solution. While some of these are suitable for most users, others could be considered niche requirements that are beyond the scope and maintainability of the core implementation.

I would like to add some scenarios from users about what they expect from view transitions. We could use those to evaluate the new API. Some of them might become part of the core implementation. But if the new API supports it, some requirements that we don't see in the core could also be realized as add-on and community solutions.

• Swap that does not lose iframe status. (View Transition API: keeping parts untouched #717)
• Control over participation in transitions for off-screen elements. (Visibility control for view transition elements #714)
• Finer control over how elements transition in and out. (Noop transition animation #628)
• Improved prefetching with ViewTransitions. (Improve prefetching w/ ViewTransitions #661)
• Finer control over transition behavior. (Change view transition behaviour based on clicked element #624)
• Progress bar for HTML loading. #feedback-ideas
• Do nifty things with the ViewTransition promises

For the API extension I would like to see something like the following:

graph TD
  subgraph rout[router.ts]
    subgraph API
      direction TB
      nav("navigate()")
      subgraph Events
      epr("astro:transition-prepare")
      ebs("astro:before-swap")
      eas("astro:after-swap")
      eal("astro:load")
      end
    end

    subgraph flow[Processing Flow]
      emtp("Fire astro:transition-prepare")
      subgraph newDOM["Prepare Transition"]
        ff("Load newDocument from URL")
        hco("Postprocess newDocument")
      end
      ssp("Save scroll position")
      psl("Preload style links")
      subgraph VTR["<b>View Transition</b>"]
        embs("Fire astro:before-swap")
        subgraph Swap
          direction TB
          swb("Merge &lt;html>-attributes,<br>&lt;head> and &lt;body><br>of current and newDOM")
          mpe("Move persisted elements")
          uhsp2("Move to Location")
        end
        emas("Fire astro:after-swap")
      end
      flowend["end"]
      RS("Run Scripts")
      empl("Fire astro:page-load")
      AN("Announce")
    end
  end
  nav-->emtp-->ff-->hco-->ssp-->psl-->embs-->swb-->mpe-->uhsp2-->emas-->RS-->empl-->AN-->flowend
   style emtp fill:#cc0,stroke:#333,stroke-width:4px,color:#000
   style embs fill:#cc0,stroke:#333,stroke-width:4px,color:#000
   style emas fill:#060,stroke:#333,stroke-width:4px,color:#fff
   style empl fill:#060,stroke:#333,stroke-width:4px,color:#fff
   linkStyle 5,10 stroke:#f00

The intercept calls allow additional steps to be added to the processing flow. Basically you can get:

graph TD
    subgraph flow[Processing Flow]
      emtp("Fire astro:transition-prepare")
      subgraph newDOM["Prepare Transition"]
        ff("Load newDocument from URL")
        hco("Postprocess newDocument")
      end
      ssp("Save scroll position")
      psl("Preload style links")
      subgraph VTR["<b>View Transition</b>"]
        embs("Fire astro:before-swap")
        subgraph Swap
          direction TB
          swb("Merge &lt;html>-attributes,<br>&lt;head> and &lt;body><br>of current and newDOM")
          mpe("Move persisted elements")
          uhsp2("Move to Location")
        end
        emas("Fire astro:after-swap")
      end
    end
   emtp-->ff-->hco-->pi1("prepare intercept 1")-->pi2("prepare intercept 2")-->pi3("...")-->ssp-->psl-->embs-->swb-->mpe-->uhsp2-->si1("swap intercept 1")-->si2("swap intercept 2")-->si3("...")-->emas
   style emtp fill:#cc0,stroke:#333,stroke-width:4px,color:#000
   style embs fill:#cc0,stroke:#333,stroke-width:4px,color:#000
   style emas fill:#060,stroke:#333,stroke-width:4px,color:#fff
   style newDOM fill:#606,stroke:#333,stroke-width:4px,color:#fff
   style Swap fill:#606,stroke:#333,stroke-width:4px,color:#fff
   linkStyle 7 stroke:#f00

The purple blocks are the default implementations for prepare and swap. Calling preventDefault removes them from the processing flow.

If you want to replace the default document loading with your own DOM manipulation/creation function, you would call preventDefault in the handler for TransitionPrepareEvent and provide your document by calling e.provideNewDocument. If you need to do async stuff to provide your document do not create it in the event handler but call e.intercept to add a flow step.

If you want to replace the default swap function with your own, call preventDefault in the handler for TransitionBeforeSwapEvent and call e.intercept to add a flow step that merges e.newDocument into document.

The the interception steps are executed in order. The next step is only executed once the Promise of its predecessor fulfills.

In the last few days I have completed a large part of a proof of concept in which astro-transition-prepare is the NavigateEvent of the navigation API. The PoC shows that this would be a solution with many advantages. However, it also shows that the effort required to simulate the Navigation API on browsers that do not natively support it is far too complicated, even for a subset. To my knowledge, there is no reliable polyfill.

The benefit of integrating with the navigation API is that in the long run we can get rid of a lot of the code that is currently maintained by Astro but will become redundant by using the API

• Event handlers for link navigation, history traversal and form submission,
• Scrolling to the target hash
  (which the browser can do much better than we can, as it also takes into account that the page may not be complete and tries several times asynchronously),
• Setting history entries, redirects and rollbacks
• An error model with abort signals and error and success events (not yet part of Astro)
• Read access to older history entries (not yet part of Astro)

Thus, using the NavigatEvent for preparation is still the way to go, in my opinion, since it is a web standard. We should do this as soon as the Navigation API is generally available. A mixed-mode implementation of view transition and simulated navigation API does not seem maintainable in the meantime.

This proposal now defines three new events:

• astro:before-swap
• astro:after-preparation
• astro:before-preparation
  They are called at the start of the navigation (astro:before-preparation), directly before the startViewTransition (astro:after-preparation) and within the View Transition directly at the start (astro:before-swap) to complement the existing astro:after-swap event.

The astro:after-* events are simple signals, the astro:before-* events enable the modification of parts of the astro view transition implementation (via loader and swap).

The proposal for the astro:before-swap event is now:

• readonly from: URL The page where the navigation started (renamed to avoid confusion with the navigation API)
• read-write to: URL The destination of the navigation (renamed to minimize confusion with the navigation API)
• readonly direction: Direction | string the values directly supported by Astro are 'forward' and 'backward' but this can be extended to other values. (edited to 'readonly' at 11/10)
• readonly navigationType: NavigationTypeString
• readonly sourceElement: Element If triggered by a link navigation, the anchor element. If triggered by form submission, the submitter (and if submitter is null, the form element). Can also be set via the sourceElement property of the options parameter on a call to navigate() (added 11/11)
• readonly info: any If the transition was initiated by a call to navigate(), the value of options.info. Otherwise undefined Set to an empty object if undefined. Reflects the state of
  info object from the end of the astro:before-preparation phase (edited 11/10)
• read-write newDocument: Document The DOM to be transitioned to. Could be an empty DOM if swap() manipulates the current DOM in place.
• read-write swap: ()=>void Initially the standard implementation of the swap() operation.
  The task of the swap operation is to update the current DOM, typically to reflect the contents of newDocument. Event listeners can set swap to their own implementation. It is the responsibility of this implementation to call the value that was previously stored in this property. In this way, a decorator / chain of resposibility can be built with parts that run before or after the original swap(), or even instead of the original swap() if the implementation deliberately chooses not to call the earlier swap().
• readonly viewTransition: The ViewTransition object returned by startViewTransition().

The event is triggered on window.document right at the beginning of the view transition. The listeners should only execute short sequences of synchronous code, as EventListeners cannot be awaited. Also swap() should only execute short sequences of code as the screen freezes during swap().

Two additional events are proposed for preparing the transition: astro:before-prepareand astro:after-prepare These events will also be supported once an implementation of Astro's View Transitions build on Navigation API is available.

The proposal for the astro:before-preparation event is as follows:

• redonly from: URL The page where the navigation started
• readwrite to: URL The destination of the navigation.
• readwrite direction: Direction | string The values directly supported by Astro are 'forward' and 'backward', but this can be extended to other values. This property is writable.
• readonly navigationType: NavigationTypeString
• readonly sourceElement: Element If triggered by a link navigation, the anchor element. If triggered by form submission, the submitter (and if submitter is null, the form element). Can also be set via the sourceElement property of the options parameter on a call to navigate() (added 11/11)
• readonly info: any If the transition was initiated by a call to navigate(), the value of options.info. Otherwise undefined Set to an empty object if undefined. (edited 11/10)
• read-write newDocument:Document The DOM to be transitioned to. This can be an empty DOM if swap() manipulates the current DOM in place.
• readonly formData: FormData Automatically filled in if the navigation was triggered by a form. If the navigation was triggered by a call to navigate, the value of options.formData. (added at 11/9)
• read-write loader: ()=>Promise<void> Initially holds the built-in implementation of the loader() operation. The task of the loader is to define a value for event.newDocument. Event listeners can set this to their own implementation. It is the task of this implementation to call and await the value that was previously stored in this property. In this way, a Decorator / Chain of Resposibility can be built with parts that run before or after the original loader(), or even instead if the implementation deliberately decides not to call the former loader(), for example to replace loading from the server with programmatic DOM manipulation. Another example of a decorator is using the original loader and adding image prefetching based on the content of the newDocument. In the case of redirects while loading, the value of the writable variable event.to should also be updated to reflect the redirect.

The event is fired on window.document right at the beginning of the navigation. The listeners should only execute short sequences of synchronous code, as EventListeners cannot be 'waited for'. Arbitrary asynchronous code can be executed within loader() by defining a decorator callback.

The astro:after-preparation imitates the astro:after-swap event. It is a standard event without additional attributes or functions. It is triggered at window.document just before the view transition begins. The listeners should only execute short sequences of synchronous code, as EventListeners cannot be waited for. This event is ideal, for example, to remove a waiting animation before the view transition API takes a screenshot.

Added 11/10:
The read-write properties allow listeners to actively influence the navigation process:
to: determines what the browser's address bar should display after navigation (and what should be loaded on reload or history navigation to the target page)
direction: a modifier for the animation to be used for the view transition
newDocument: what should be rendered on the target page
loader: how newDocument is generated
swap: how the DOM should be updated during the view transition

The initial values of the properties for the astro:before-swap event are taken from the final state of the corresponding astro:before-preparation event. In particular, changes to the info object are not only visible to other astro:before-preparation listeners, but also to the astro:before-swap listeners. You can use this to communicate between your astro:before-* listeners on a per event basis.

Hey everyone,

I've been following the discussion about the new events you are going to add (astro:before-swap, astro:after-preparation, and astro:before-preparation). I was going to comment about a few events that were almost the same:

astro:page-start
astro:page-error
astro:page-end
astro:form-start
astro:form-error
astro:form-end

I was wondering if you think its a good idea to split the events between pages transition and forms submissions (maybe navigationType do the trick). I can imagine this could help to build things like useRouter and useForm for all UI frameworks inside Astro. For instance, consider two simple examples that leverages these proposed events; one framework agnostic and the other one in React:

Framework agnostic:

Using nanostores like createSearchParams in nanostores/router: https://github.com/nanostores/router/blob/83699283a01f319e080a97fb1f2eef6801af5349/index.js#L162C56-L162C56

React

import { useState, useEffect } from 'react';

function useForm(formId) {
    const [formStatus, setFormStatus] = useState({
        from: null,
        to: null,
        direction: '',
        navigationType: '',
        info: {},
        newDocument: null,
        formData: null,
        error: null,
        loading: false,
        data: null
    });

    useEffect(() => {
        function handleFormStart(event) {
            if (event.detail.formId === formId) {
                setFormStatus(prevStatus => ({
                    ...prevStatus,
                    from: event.detail.from,
                    to: event.detail.to,
                    direction: event.detail.direction,
                    navigationType: event.detail.navigationType,
                    info: event.detail.info || {},
                    formData: event.detail.formData,
                    loading: true,
                    error: null
                }));
            }
        }

        function handleFormError(event) {
            if (event.detail.formId === formId) {
                setFormStatus(prevStatus => ({
                    ...prevStatus,
                    error: event.detail.error,
                    loading: false
                }));
            }
        }

        function handleFormEnd(event) {
            if (event.detail.formId === formId) {
                setFormStatus(prevStatus => ({
                    ...prevStatus,
                    loading: false,
                    data: event.detail.data
                }));
            }
        }

        window.addEventListener('astro:form-start', handleFormStart);
        window.addEventListener('astro:form-error', handleFormError);
        window.addEventListener('astro:form-end', handleFormEnd);

        return () => {
            window.removeEventListener('astro:form-start', handleFormStart);
            window.removeEventListener('astro:form-error', handleFormError);
            window.removeEventListener('astro:form-end', handleFormEnd);
        };
    }, [formId]);

    return { formStatus };
}

export default useForm;

PS: In the context of ViewTransitions form handling, how could Astro handle endpoint responses in non-HTML formats, such as JSON or other media types? I know you can opt out of router transition with data-astro-reload, but then it won't work without JS. I think this comment may be related, if you have a hook that gets the data and you can do things with JS, you should be able to do it without JS (PE).

PS2: Maybe I'm confused and mixing things, sorry for that :)

Thank you!

Added sourceElement to the proposal as in https://chromium.googlesource.com/chromium/src/+/3719b4f51e4919413e8eb08dab383c5278c756a1

@martrapp can we close this proposal? I think we have all those events now