feat(brouter): disable animation on initial load when view transition is enabled bitfoundation#12746 (bitfoundation#12747)

Author: msynk

src/Brouter/Bit.Brouter/Brouter.cs

@@ -2285,7 +2285,12 @@ private async ValueTask ProcessNavigationAsync(BrouterLocation from, BrouterLoca
             // held across arbitrary awaits) and immediately before the renders below mutate the page.
             // The completion (which lets the browser animate to the new state) runs in
             // OnAfterRenderAsync once the new DOM is committed.
-            if (Options.ViewTransitions)
+            //
+            // The initial load (empty `from`, matching SaveScrollPositionAsync's convention) never
+            // animates: there is no meaningful outgoing page - just the blank document, or, after
+            // prerendering, static HTML visually identical to what the interactive pass is about to
+            // render, where a transition reads as a spurious double-render flash of the same page.
+            if (Options.ViewTransitions && string.IsNullOrEmpty(from.FullUri) is false)
             {
                 viewTransitionStarted = await service.BeginViewTransitionAsync(navType);
                 if (token.IsCancellationRequested || version != _navVersion) return;
@@ -2354,16 +2359,20 @@ private async ValueTask ProcessNavigationAsync(BrouterLocation from, BrouterLoca
             // supersession bail-outs above so an abandoned pipeline never strands stale arrivals.
             StageArrivals(ctx, matchedChain);
 
-            StateHasChanged();
-
-            // Hand the open transition to OnAfterRenderAsync: it completes once the render above has
-            // been applied to the DOM, which is exactly when the browser should snapshot the new state.
+            // Hand the open transition to OnAfterRenderAsync: it completes once the render below has
+            // been applied to the DOM, which is exactly when the browser should snapshot the new
+            // state. Staged BEFORE StateHasChanged: when every await in OnAfterRenderAsync completes
+            // synchronously (bUnit's mocked interop; any environment without a real yield), the
+            // whole OnAfterRenderAsync runs inside StateHasChanged - staging afterwards would let it
+            // consume a still-false flag and strand the transition until the JS watchdog frees it.
             if (viewTransitionStarted)
             {
                 viewTransitionStaged = true;
                 _pendingViewTransitionCompletion = true;
             }
 
+            StateHasChanged();
+
             ResolveNavigationOutcome(to.FullUri, BrouterNavigationOutcome.Success());
 
             // Stale-while-revalidate: some chain node rendered a stale cached result above - kick

src/Brouter/Bit.Brouter/BrouterOptions.cs

@@ -169,6 +169,9 @@ public sealed class BrouterOptions
     /// the outgoing and incoming pages by default and enabling per-element morph animations via the
     /// standard <c>view-transition-name</c> CSS property - no Blazor-specific animation code needed.
     /// Mirrors Angular's <c>withViewTransitions</c> and React Router's <c>viewTransition</c>.
+    /// Only actual navigations animate - the initial load never does (with prerendering it would
+    /// otherwise re-animate over static HTML identical to the interactive render, appearing as a
+    /// double render of the first page).
     /// Gracefully inert on browsers without the API, during prerender, and in non-browser hosts.
     /// Defaults to <c>false</c>. See also <see cref="ViewTransitionDefaultAnimations"/>.
     /// </summary>

src/Brouter/Demos/Core/Pages/LandingPage.razor

@@ -11,7 +11,7 @@
     <section class="bb-hero">
         <div class="bb-hero-copy">
             <span class="bb-hero-eyebrow">Open source · MIT · net8.0 / net9.0 / net10.0</span>
-            <h1>Client-side routing for Blazor,<br /><span class="bb-hero-accent">done right.</span></h1>
+            <h1>Routing for Blazor,<br /><span class="bb-hero-accent">done right!</span></h1>
             <p class="bb-hero-sub">
                 Brouter is a modern, declarative, nestable router with everything today's router
                 libraries are measured by: async guards, data loaders with stale-while-revalidate

src/Brouter/Demos/Core/Pages/TransitionsPage.razor

@@ -20,7 +20,9 @@
         navigations glide in, Back/Forward mirror the motion, replaces cross-fade - the router
         detects direction from the navigation type (<code>Push</code> / <code>Replace</code> /
         <code>Pop</code>) and exposes it as <code>data-brouter-nav</code> on the root element for
-        your own CSS. On browsers without the API everything is inert; nothing breaks.
+        your own CSS. On browsers without the API everything is inert; nothing breaks. Only actual
+        navigations animate - the initial load never does, so with prerendering the interactive
+        takeover doesn't replay the animation over the already-visible page.
     </p>
     <pre class="bb-code">services.AddBitBrouterServices(o =&gt;
 {

src/Brouter/README.md

@@ -590,6 +590,10 @@ animations out of the box (`o.ViewTransitionDefaultAnimations`, enabled by defau
   bypass it with `o.ViewTransitionRespectReducedMotion = false` - think twice, though: for
   motion-sensitive users `reduce` is a genuine request.
 
+Only actual navigations animate - the **initial load never does**. This matters with prerendering:
+the prerendered HTML is already on screen when the router becomes interactive, and animating the
+first (identical) interactive render would show an annoying double render of the same page.
+
 The defaults live in the CSS layer `bit-brouter`, so **any unlayered `::view-transition-*` rule in
 your own CSS overrides them automatically** - customize without specificity fights, or set
 `o.ViewTransitionDefaultAnimations = false` to opt out entirely. The current direction is exposed as

src/Brouter/Tests/Bit.Brouter.Tests/ViewTransitionTests.cs

@@ -18,8 +18,21 @@ private BunitJSModuleInterop SetupModule(bool beginReturns)
         return module;
     }
 
+    // Waits for a JS invocation that no render follows (e.g. the transition completion fired from
+    // OnAfterRenderAsync after the navigation's final render): render-driven WaitForAssertion never
+    // re-checks in that window, so poll the interop log instead.
+    private static async Task WaitForInvocationAsync(BunitJSModuleInterop module, string identifier)
+    {
+        var deadline = DateTime.UtcNow.AddSeconds(5);
+        while (module.Invocations.All(i => i.Identifier != identifier))
+        {
+            if (DateTime.UtcNow > deadline) Assert.Fail($"JS invocation '{identifier}' was never made.");
+            await Task.Delay(10);
+        }
+    }
+
     [TestMethod]
-    public void Navigation_with_ViewTransitions_enabled_runs_the_begin_complete_handshake()
+    public async Task Navigation_with_ViewTransitions_enabled_runs_the_begin_complete_handshake()
     {
         Services.Configure<BrouterOptions>(o => o.ViewTransitions = true);
         var module = SetupModule(beginReturns: true);
@@ -29,45 +42,71 @@ public void Navigation_with_ViewTransitions_enabled_runs_the_begin_complete_hand
         var cut = RenderComponent<NavigationTypeHost>();
         cut.WaitForAssertion(() => cut.Find("[data-testid=a]"));
 
+        var brouter = Services.GetRequiredService<IBrouter>();
+        await cut.InvokeAsync(() => brouter.Navigate("/b"));
+
+        cut.WaitForAssertion(() => cut.Find("[data-testid=b]"));
+
+        // Begin fired before the render, complete after it landed.
+        Assert.IsTrue(module.Invocations.Count(i => i.Identifier == "beginViewTransition") >= 1);
+        await WaitForInvocationAsync(module, "completeViewTransition");
+
+        // Begin carries the direction token (a programmatic Navigate is a push), the
+        // default-animations flag and the reduced-motion flag (both on by default), which
+        // drive the built-in direction-aware animations.
+        var begin = module.Invocations.First(i => i.Identifier == "beginViewTransition");
+        Assert.AreEqual("push", begin.Arguments[0]);
+        Assert.AreEqual(true, begin.Arguments[1]);
+        Assert.AreEqual(true, begin.Arguments[2]);
+    }
+
+    [TestMethod]
+    public void Unsupported_browser_skips_the_completion_round_trip()
+    {
+        Services.Configure<BrouterOptions>(o => o.ViewTransitions = true);
+        var module = SetupModule(beginReturns: false);
+
+        var nav = Services.GetRequiredService<BunitNavigationManager>();
+        nav.NavigateTo("http://localhost/a");
+        var cut = RenderComponent<NavigationTypeHost>();
+        cut.WaitForAssertion(() => cut.Find("[data-testid=a]"));
+
         var brouter = Services.GetRequiredService<IBrouter>();
         cut.InvokeAsync(() => brouter.Navigate("/b"));
 
         cut.WaitForAssertion(() =>
         {
             Assert.IsNotNull(cut.Find("[data-testid=b]"));
-            // Begin fired before the render, complete after it landed.
             Assert.IsTrue(module.Invocations.Count(i => i.Identifier == "beginViewTransition") >= 1);
-            Assert.IsTrue(module.Invocations.Count(i => i.Identifier == "completeViewTransition") >= 1);
-
-            // Begin carries the direction token (a programmatic Navigate is a push), the
-            // default-animations flag and the reduced-motion flag (both on by default), which
-            // drive the built-in direction-aware animations.
-            var begin = module.Invocations.First(i => i.Identifier == "beginViewTransition");
-            Assert.AreEqual("push", begin.Arguments[0]);
-            Assert.AreEqual(true, begin.Arguments[1]);
-            Assert.AreEqual(true, begin.Arguments[2]);
+            Assert.AreEqual(0, module.Invocations.Count(i => i.Identifier == "completeViewTransition"));
         });
     }
 
     [TestMethod]
-    public void Unsupported_browser_skips_the_completion_round_trip()
+    public void Initial_load_does_not_start_a_transition()
     {
         Services.Configure<BrouterOptions>(o => o.ViewTransitions = true);
-        var module = SetupModule(beginReturns: false);
+        var module = SetupModule(beginReturns: true);
 
         var nav = Services.GetRequiredService<BunitNavigationManager>();
         nav.NavigateTo("http://localhost/a");
         var cut = RenderComponent<NavigationTypeHost>();
         cut.WaitForAssertion(() => cut.Find("[data-testid=a]"));
 
+        // The first mount renders the initial route without any transition interop: there is no
+        // outgoing page to animate from, and after prerendering a transition here would replay the
+        // animation over the already-visible static HTML (a "double render" of the first page).
+        Assert.AreEqual(0, module.Invocations.Count(i => i.Identifier == "beginViewTransition"));
+        Assert.AreEqual(0, module.Invocations.Count(i => i.Identifier == "completeViewTransition"));
+
+        // A real navigation afterwards still animates.
         var brouter = Services.GetRequiredService<IBrouter>();
         cut.InvokeAsync(() => brouter.Navigate("/b"));
 
         cut.WaitForAssertion(() =>
         {
             Assert.IsNotNull(cut.Find("[data-testid=b]"));
             Assert.IsTrue(module.Invocations.Count(i => i.Identifier == "beginViewTransition") >= 1);
-            Assert.AreEqual(0, module.Invocations.Count(i => i.Identifier == "completeViewTransition"));
         });
     }