Document that onDocumentPatch must call start in order

[rubas]

LiveView does not reorder the start callbacks it passes to onDocumentPatch. When an app delays only some patches, for example to run a view transition only when the server asks for one, a later patch can run before an earlier one. The client then crashes in Rendered.dynamicsToBuffer with Cannot read properties of undefined (reading 'length').

As discussed in #4462 (comment), keeping the order is the app's job. This PR drops the code change and adds the rule to the onDocumentPatch docs.

[SteffenDE]

I would argue that it is the app's responsibility to keep patches in order, so you only call start if your pending transition is done. Something like this:

let transition = false;
let previousTransition = Promise.resolve();

window.addEventListener("phx:start-view-transition", () => (transition = true));

let liveSocket = new window.LiveView.LiveSocket("/live", window.Phoenix.Socket, {
  dom: {
    onDocumentPatch(start) {
      // Capture the flag now, so it applies to this patch even if we wait
      const animate = transition;
      transition = false;

      previousTransition = previousTransition
        .then(() => {
          if (animate && document.startViewTransition) {
            return document.startViewTransition(start).finished;
          }
          start();
        })
        .catch((err) => console.error(err)); // keep the chain alive if a transition fails
    }
  }
});

We can adjust the docs to state that order has to be preserved manually.

[rubas]

Makes sense, thanks. I changed the PR to a short docs note on onDocumentPatch, but also feel free to close it.