Add a turbo:reload event that returns the reason why turbo needed to do a hard reload.

src/core/drive/page_renderer.ts

@@ -1,11 +1,26 @@
 import { Renderer } from "../renderer"
 import { PageSnapshot } from "./page_snapshot"
+import { ReloadReason } from "../native/browser_adapter"
 
 export class PageRenderer extends Renderer<HTMLBodyElement, PageSnapshot> {
   get shouldRender() {
     return this.newSnapshot.isVisitable && this.trackedElementsAreIdentical
   }
 
+  get reloadReason(): ReloadReason {
+    if (!this.newSnapshot.isVisitable) {
+      return {
+        reason: "turbo_visit_control_is_reload"
+      }
+    }
+
+    if (!this.trackedElementsAreIdentical) {
+      return {
+        reason: "tracked_element_mismatch"
+      }
+    }
+  }
+
   prepareToRender() {
     this.mergeHead()
   }

src/core/native/adapter.ts

@@ -1,5 +1,6 @@
 import { Visit, VisitOptions } from "../drive/visit"
 import { FormSubmission } from "../drive/form_submission"
+import { ReloadReason } from "./browser_adapter"
 
 export interface Adapter {
   visitProposedToLocation(location: URL, options?: Partial<VisitOptions>): void
@@ -13,5 +14,5 @@ export interface Adapter {
   visitRendered(visit: Visit): void
   formSubmissionStarted?(formSubmission: FormSubmission): void
   formSubmissionFinished?(formSubmission: FormSubmission): void
-  pageInvalidated(): void
+  pageInvalidated(reason: ReloadReason): void
 }

src/core/native/browser_adapter.ts

@@ -3,7 +3,13 @@ import { ProgressBar } from "../drive/progress_bar"
 import { SystemStatusCode, Visit, VisitOptions } from "../drive/visit"
 import { FormSubmission } from "../drive/form_submission"
 import { Session } from "../session"
-import { uuid } from "../../util"
+import { uuid, dispatch } from "../../util"
+
+export type ReloadReason = StructuredReason | undefined
+interface StructuredReason {
+  reason: string
+  context?: {[key: string]: any}
+}
 
 export class BrowserAdapter implements Adapter {
   readonly session: Session
@@ -45,7 +51,12 @@ export class BrowserAdapter implements Adapter {
       case SystemStatusCode.networkFailure:
       case SystemStatusCode.timeoutFailure:
       case SystemStatusCode.contentTypeMismatch:
-        return this.reload()
+        return this.reload({
+          reason: "request_failed",
+          context: {
+            statusCode
+          }
+        })
       default:
         return visit.loadResponse()
     }
@@ -60,8 +71,8 @@ export class BrowserAdapter implements Adapter {
 
   }
 
-  pageInvalidated() {
-    this.reload()
+  pageInvalidated(reason: ReloadReason) {
+    this.reload(reason)
   }
 
   visitFailed(visit: Visit) {
@@ -114,7 +125,8 @@ export class BrowserAdapter implements Adapter {
     this.progressBar.show()
   }
 
-  reload() {
+  reload(reason: ReloadReason) {
+    dispatch("turbo:reload", { detail: reason })
     window.location.reload()
   }
 

src/core/renderer.ts

@@ -1,5 +1,6 @@
 import { Bardo } from "./bardo"
 import { Snapshot } from "./snapshot"
+import { ReloadReason } from "./native/browser_adapter"
 
 type ResolvingFunctions<T = unknown> = {
   resolve(value: T | PromiseLike<T>): void
@@ -26,6 +27,10 @@ export abstract class Renderer<E extends Element, S extends Snapshot<E> = Snapsh
     return true
   }
 
+  get reloadReason(): ReloadReason {
+    return
+  }
+
   prepareToRender() {
     return
   }

src/core/session.ts

@@ -1,5 +1,5 @@
 import { Adapter } from "./native/adapter"
-import { BrowserAdapter } from "./native/browser_adapter"
+import { BrowserAdapter, ReloadReason } from "./native/browser_adapter"
 import { CacheObserver } from "../observers/cache_observer"
 import { FormSubmitObserver, FormSubmitObserverDelegate } from "../observers/form_submit_observer"
 import { FrameRedirector } from "./frames/frame_redirector"
@@ -116,7 +116,9 @@ export class Session implements FormSubmitObserverDelegate, HistoryDelegate, Lin
     if (this.enabled) {
       this.navigator.startVisit(location, restorationIdentifier, { action: "restore", historyChanged: true })
     } else {
-      this.adapter.pageInvalidated()
+      this.adapter.pageInvalidated({
+        reason: "turbo_disabled"
+      })
     }
   }
 
@@ -250,8 +252,8 @@ export class Session implements FormSubmitObserverDelegate, HistoryDelegate, Lin
     this.notifyApplicationAfterRender()
   }
 
-  viewInvalidated() {
-    this.adapter.pageInvalidated()
+  viewInvalidated(reason: ReloadReason) {
+    this.adapter.pageInvalidated(reason)
   }
 
   // Frame element

src/core/view.ts

@@ -1,3 +1,4 @@
+import { ReloadReason } from "./native/browser_adapter"
 import { Renderer } from "./renderer"
 import { Snapshot } from "./snapshot"
 import { Position } from "./types"
@@ -6,7 +7,7 @@ import { getAnchor } from "./url"
 export interface ViewDelegate<S extends Snapshot> {
   allowsImmediateRender(snapshot: S, resume: (value: any) => void): boolean
   viewRenderedSnapshot(snapshot: S, isPreview: boolean): void
-  viewInvalidated(): void
+  viewInvalidated(reason: ReloadReason): void
 }
 
 export abstract class View<E extends Element, S extends Snapshot<E> = Snapshot<E>, R extends Renderer<E, S> = Renderer<E, S>, D extends ViewDelegate<S> = ViewDelegate<S>> {
@@ -90,12 +91,12 @@ export abstract class View<E extends Element, S extends Snapshot<E> = Snapshot<E
         delete this.renderPromise
       }
     } else {
-      this.invalidate()
+      this.invalidate(renderer.reloadReason)
     }
   }
 
-  invalidate() {
-    this.delegate.viewInvalidated()
+  invalidate(reason: ReloadReason) {
+    this.delegate.viewInvalidated(reason)
   }
 
   prepareToRenderSnapshot(renderer: R) {

src/tests/fixtures/test.js

@@ -31,4 +31,5 @@
   "turbo:visit",
   "turbo:frame-load",
   "turbo:frame-render",
+  "turbo:reload"
 ])

src/tests/functional/rendering_tests.ts

@@ -6,6 +6,10 @@ export class RenderingTests extends TurboDriveTestCase {
     await this.goToLocation("/src/tests/fixtures/rendering.html")
   }
 
+  async teardown() {
+    await this.remote.execute(() => localStorage.clear())
+  }
+
   async "test triggers before-render and render events"() {
     this.clickSelector("#same-origin-link")
     const { newBody } = await this.nextEventNamed("turbo:before-render")
@@ -35,10 +39,20 @@ export class RenderingTests extends TurboDriveTestCase {
   }
 
   async "test reloads when tracked elements change"() {
+    await this.remote.execute(() =>
+      window.addEventListener("turbo:reload", (e: any) => {
+        localStorage.setItem("reloadReason", e.detail.reason)
+      })
+    )
+
     this.clickSelector("#tracked-asset-change-link")
     await this.nextBody
+
+    const reason = await this.remote.execute(() => localStorage.getItem("reloadReason"))
+
     this.assert.equal(await this.pathname, "/src/tests/fixtures/tracked_asset_change.html")
     this.assert.equal(await this.visitAction, "load")
+    this.assert.equal(reason, "tracked_element_mismatch")
   }
 
   async "test wont reload when tracked elements has a nonce"() {
@@ -49,10 +63,20 @@ export class RenderingTests extends TurboDriveTestCase {
   }
 
   async "test reloads when turbo-visit-control setting is reload"() {
+    await this.remote.execute(() =>
+      window.addEventListener("turbo:reload", (e: any) => {
+        localStorage.setItem("reloadReason", e.detail.reason)
+      })
+    )
+
     this.clickSelector("#visit-control-reload-link")
     await this.nextBody
+
+    const reason = await this.remote.execute(() => localStorage.getItem("reloadReason"))
+
     this.assert.equal(await this.pathname, "/src/tests/fixtures/visit_control_reload.html")
     this.assert.equal(await this.visitAction, "load")
+    this.assert.equal(reason, "turbo_visit_control_is_reload")
   }
 
   async "test accumulates asset elements in head"() {