Unify back navigation across subpages

eslint.config.mjs

@@ -111,7 +111,17 @@ export default tseslint.config(
       "no-bitwise": "error",
       "no-console": "error",
       "no-restricted-globals": [2, "event"],
-      "no-restricted-syntax": ["error", "LabeledStatement", "WithStatement"],
+      "no-restricted-syntax": [
+        "error",
+        "LabeledStatement",
+        "WithStatement",
+        {
+          selector:
+            "CallExpression[callee.property.name=/^(push|replace)State$/]",
+          message:
+            "Use navigate(), updateHistoryState() or replaceCurrentUrl() from common/navigate. History entries carry the app's own bookkeeping, which a raw pushState/replaceState drops.",
+        },
+      ],
       "wc/no-self-class": "off",
 
       // import-x rules
@@ -222,6 +232,24 @@ export default tseslint.config(
       ],
     },
   },
+  {
+    // These own history entries themselves: the navigation helpers, the dialog
+    // stack, the boot paths that run before the app has any state to keep, and
+    // the tests that fabricate entries to simulate a document load.
+    files: [
+      "src/common/navigate.ts",
+      "src/dialogs/make-dialog-manager.ts",
+      "src/state/url-sync-mixin.ts",
+      "src/panels/config/automation/add-automation-element-dialog.ts",
+      "src/entrypoints/core.ts",
+      "src/onboarding/**/*.ts",
+      "cast/**/*.ts",
+      "test/**/*.ts",
+    ],
+    rules: {
+      "no-restricted-syntax": ["error", "LabeledStatement", "WithStatement"],
+    },
+  },
   {
     files: ["src/util/recorder-worklet.js"],
     languageOptions: {

src/common/decorators/restore-scroll.ts

@@ -1,8 +1,9 @@
 import type { ReactiveElement } from "lit";
+import { updateHistoryState } from "../navigate";
 import { throttle } from "../util/throttle";
 
 const throttleReplaceState = throttle((value) => {
-  history.replaceState({ scrollPosition: value }, "");
+  updateHistoryState({ scrollPosition: value });
 }, 300);
 
 export function restoreScroll(selector: string) {

src/common/navigate.ts

@@ -1,6 +1,7 @@
 import { closeAllDialogs } from "../dialogs/make-dialog-manager";
 import { fireEvent } from "./dom/fire_event";
 import { mainWindow } from "./dom/get_main_window";
+import { currentPath } from "./url/current-path";
 
 declare global {
   // for fire event
@@ -17,6 +18,26 @@ export interface NavigateOptions {
 // max time to wait for dialogs to close before navigating
 const DIALOG_WAIT_TIMEOUT = 500;
 
+/**
+ * Merge into the current history entry's state, keeping what is already there.
+ * Entries carry the app's own bookkeeping (`from`, `root`, dialog state), so
+ * they must never be replaced wholesale.
+ */
+export const updateHistoryState = (patch: Record<string, unknown>) => {
+  mainWindow.history.replaceState(
+    { ...mainWindow.history.state, ...patch },
+    ""
+  );
+};
+
+/**
+ * Rewrite the URL of the current history entry without navigating and without
+ * touching its state. For query parameter cleanup.
+ */
+export const replaceCurrentUrl = (url: string) => {
+  mainWindow.history.replaceState(mainWindow.history.state, "", url);
+};
+
 /**
  * Stash a destination URL in the current history entry's state. If the page
  * is refreshed while a dialog is open, urlSyncMixin will navigate to this URL
@@ -24,10 +45,7 @@ const DIALOG_WAIT_TIMEOUT = 500;
  * The current URL is not changed.
  */
 export const setRefreshUrl = (path: string) => {
-  mainWindow.history.replaceState(
-    { ...mainWindow.history.state, refreshUrl: path },
-    ""
-  );
+  updateHistoryState({ refreshUrl: path });
 };
 
 /**
@@ -63,37 +81,32 @@ export const navigate = async (path: string, options?: NavigateOptions) => {
   }
   const replace = options?.replace || false;
 
-  if (__DEMO__) {
-    if (!path.includes("#")) {
-      // The demo routes with the hash instead of the pathname. Resolve the
-      // path like the browser would do for pushState, and keep the query
-      // parameters in the URL query instead of inside the hash.
-      const url = new URL(
-        path,
-        `${mainWindow.location.origin}${mainWindow.location.hash.substring(1)}`
-      );
-      path = `${mainWindow.location.pathname}${url.search}#${url.pathname}`;
-    }
-    if (replace) {
-      mainWindow.history.replaceState(
-        mainWindow.history.state?.root
-          ? { root: true }
-          : (options?.data ?? null),
-        "",
-        path
-      );
-    } else {
-      mainWindow.history.pushState(options?.data ?? null, "", path);
-    }
-  } else if (replace) {
-    mainWindow.history.replaceState(
-      mainWindow.history.state?.root ? { root: true } : (options?.data ?? null),
+  if (__DEMO__ && !path.includes("#")) {
+    // The demo routes with the hash instead of the pathname. Resolve the
+    // path like the browser would do for pushState, and keep the query
+    // parameters in the URL query instead of inside the hash.
+    const url = new URL(
+      path,
+      `${mainWindow.location.origin}${mainWindow.location.hash.substring(1)}`
+    );
+    path = `${mainWindow.location.pathname}${url.search}#${url.pathname}`;
+  }
+
+  const { history } = mainWindow;
+
+  if (replace) {
+    // A replaced entry keeps its predecessor, so it keeps `from`.
+    const { root, from } = history.state ?? {};
+    const state = root ? { root: true } : (options?.data ?? null);
+    history.replaceState(
+      from === undefined ? state : { ...state, from },
       "",
       path
     );
   } else {
-    mainWindow.history.pushState(options?.data ?? null, "", path);
+    history.pushState({ ...options?.data, from: currentPath() }, "", path);
   }
+
   fireEvent(mainWindow, "location-changed", {
     replace,
   });
@@ -101,8 +114,17 @@ export const navigate = async (path: string, options?: NavigateOptions) => {
 };
 
 /**
- * Navigate back in history, with fallback to a default path if no history exists.
- * This prevents a user from getting stuck when they navigate directly to a page with no history.
+ * Whether the previous history entry is a page this app navigated away from.
+ * `history.length` cannot answer this: a login redirect goes through
+ * `location.assign`, which leaves /auth/authorize right behind the requested
+ * page, and going back there would bounce the user out of the app.
+ */
+export const canGoBack = (): boolean =>
+  mainWindow.history.state?.from !== undefined;
+
+/**
+ * Navigate back to the page we came from, falling back to a path when the
+ * previous entry is not ours (deep link, login redirect, fresh tab).
  */
 export const goBack = async (fallbackPath?: string): Promise<void> => {
   const canProceed = await ensureDialogsClosed(Date.now());
@@ -110,14 +132,12 @@ export const goBack = async (fallbackPath?: string): Promise<void> => {
     return;
   }
 
-  // Check if we have history to go back to
-  const { history } = mainWindow;
-  if (history.length > 1) {
-    history.back();
+  // Read after closing dialogs: their history entries are popped by then, so
+  // this is the state of the page entry.
+  if (canGoBack()) {
+    mainWindow.history.back();
     return;
   }
 
-  // No history available, navigate to fallback path
-  const fallback = fallbackPath || "/";
-  navigate(fallback, { replace: true });
+  navigate(fallbackPath || "/", { replace: true });
 };

src/common/url/current-path.ts

@@ -0,0 +1,10 @@
+import { mainWindow } from "../dom/get_main_window";
+
+/**
+ * The path of the page currently shown by the app. The demo routes with the
+ * hash instead of the pathname, see navigate().
+ */
+export const currentPath = (): string =>
+  __DEMO__
+    ? mainWindow.location.hash.substring(1)
+    : mainWindow.location.pathname;

src/dialogs/more-info/ha-more-info-dialog.ts

@@ -40,7 +40,7 @@ import {
   getEntityEntryContext,
 } from "../../common/entity/context/get_entity_context";
 import { shouldHandleRequestSelectedEvent } from "../../common/mwc/handle-request-selected-event";
-import { navigate } from "../../common/navigate";
+import { navigate, updateHistoryState } from "../../common/navigate";
 import type { LocalizeKeys } from "../../common/translations/localize";
 import { computeRTL } from "../../common/util/compute_rtl";
 import { withViewTransition } from "../../common/util/view-transition";
@@ -268,16 +268,12 @@ export class MoreInfoDialog extends DirtyStateProviderMixin<
   }
 
   private _setView(view: MoreInfoView) {
-    history.replaceState(
-      {
-        ...history.state,
-        dialogParams: {
-          ...history.state?.dialogParams,
-          view,
-        },
+    updateHistoryState({
+      dialogParams: {
+        ...history.state?.dialogParams,
+        view,
       },
-      ""
-    );
+    });
     this._currView = view;
   }
 

src/layouts/hass-subpage.ts

@@ -4,6 +4,7 @@ import { customElement, eventOptions, property } from "lit/decorators";
 import { classMap } from "lit/directives/class-map";
 import { restoreScroll } from "../common/decorators/restore-scroll";
 import type { HASSDomTargetEvent } from "../common/dom/fire_event";
+import { isNavigationClick } from "../common/dom/is-navigation-click";
 import { goBack } from "../common/navigate";
 import { sanitizeNavigationPath } from "../common/url/sanitize-navigation-path";
 import "../components/ha-icon-button-arrow-prev";
@@ -37,19 +38,14 @@ class HassSubpage extends LitElement {
       <div class="toolbar ${classMap({ narrow: this.narrow })}">
         <div class="toolbar-content">
           ${
-            this.mainPage || history.state?.root
+            this.mainPage || (!backPath && history.state?.root)
               ? html`<ha-menu-button></ha-menu-button>`
-              : backPath
-                ? html`
-                    <ha-icon-button-arrow-prev
-                      href=${backPath}
-                    ></ha-icon-button-arrow-prev>
-                  `
-                : html`
-                    <ha-icon-button-arrow-prev
-                      @click=${this._backTapped}
-                    ></ha-icon-button-arrow-prev>
-                  `
+              : html`
+                  <ha-icon-button-arrow-prev
+                    .href=${backPath}
+                    @click=${this._backTapped}
+                  ></ha-icon-button-arrow-prev>
+                `
           }
 
           <div class="main-title">
@@ -79,12 +75,21 @@ class HassSubpage extends LitElement {
     this._savedScrollPos = (e.target as HTMLDivElement).scrollTop;
   }
 
-  private _backTapped(): void {
+  private _backTapped(ev: MouseEvent): void {
+    const backPath = sanitizeNavigationPath(this.backPath);
+
+    // Middle click, ctrl and cmd open the parent in a new tab, let the anchor
+    // handle those.
+    if (backPath && !isNavigationClick(ev)) {
+      return;
+    }
+
     if (this.backCallback) {
       this.backCallback();
       return;
     }
-    goBack();
+
+    goBack(backPath);
   }
 
   static get styles(): CSSResultGroup {

src/layouts/hass-tabs-subpage.ts

@@ -175,17 +175,12 @@ export class HassTabsSubpage extends LitElement {
             ${
               this.mainPage || (!backPath && history.state?.root)
                 ? html`<ha-menu-button></ha-menu-button>`
-                : backPath
-                  ? html`
-                      <ha-icon-button-arrow-prev
-                        .href=${backPath}
-                      ></ha-icon-button-arrow-prev>
-                    `
-                  : html`
-                      <ha-icon-button-arrow-prev
-                        @click=${this._backTapped}
-                      ></ha-icon-button-arrow-prev>
-                    `
+                : html`
+                    <ha-icon-button-arrow-prev
+                      .href=${backPath}
+                      @click=${this._backTapped}
+                    ></ha-icon-button-arrow-prev>
+                  `
             }
             ${
               this._narrow || !this.showTabs
@@ -246,12 +241,21 @@ export class HassTabsSubpage extends LitElement {
     this._content.focus({ preventScroll: true });
   }
 
-  private _backTapped(): void {
+  private _backTapped(ev: MouseEvent): void {
+    const backPath = sanitizeNavigationPath(this.backPath);
+
+    // Middle click, ctrl and cmd open the parent in a new tab, let the anchor
+    // handle those.
+    if (backPath && !isNavigationClick(ev)) {
+      return;
+    }
+
     if (this.backCallback) {
       this.backCallback();
       return;
     }
-    goBack();
+
+    goBack(backPath);
   }
 
   private _isActiveTabPath(tabPath: string, currentPath: string): boolean {

src/panels/config/areas/ha-config-area-page.ts

@@ -644,6 +644,7 @@ class HaConfigAreaPage extends LitElement {
       <hass-subpage
         .hass=${this.hass}
         .narrow=${this.narrow}
+        back-path="/config/areas/dashboard"
         .header=${html`${
           area.icon
             ? html`<ha-icon

src/panels/config/areas/ha-config-areas-dashboard.ts

@@ -86,8 +86,6 @@ export class HaConfigAreasDashboard extends LitElement {
 
   @state() private _hierarchy?: AreasFloorHierarchy;
 
-  private _searchParms = new URLSearchParams(window.location.search);
-
   private _blockHierarchyUpdate = false;
 
   private _blockHierarchyUpdateTimeout?: number;
@@ -168,9 +166,7 @@ export class HaConfigAreasDashboard extends LitElement {
       <hass-tabs-subpage
         .hass=${this.hass}
         .isWide=${this.isWide}
-        .backPath=${
-          this._searchParms.has("historyBack") ? undefined : "/config"
-        }
+        back-path="/config"
         .tabs=${configSections.areas}
         .route=${this.route}
         has-fab

src/panels/config/automation/ha-automation-picker.ts

@@ -443,9 +443,7 @@ class HaAutomationPicker extends SubscribeMixin(LitElement) {
       <hass-tabs-subpage-data-table
         .hass=${this.hass}
         .narrow=${this.narrow}
-        .backPath=${
-          this._searchParms.has("historyBack") ? undefined : "/config"
-        }
+        back-path="/config"
         id="entity_id"
         .route=${this.route}
         .tabs=${configSections.automations}

src/panels/config/automation/ha-automation-trace.ts

@@ -14,7 +14,7 @@ import { css, html, LitElement, nothing } from "lit";
 import { customElement, property, query, state } from "lit/decorators";
 import { isComponentLoaded } from "../../../common/config/is_component_loaded";
 import { fireEvent } from "../../../common/dom/fire_event";
-import { navigate } from "../../../common/navigate";
+import { navigate, replaceCurrentUrl } from "../../../common/navigate";
 import { computeRTL } from "../../../common/util/compute_rtl";
 import "../../../components/ha-button";
 import "../../../components/ha-dropdown";
@@ -110,6 +110,7 @@ export class HaAutomationTrace extends LitElement {
       <hass-subpage
         .hass=${this.hass}
         .narrow=${this.narrow}
+        back-path="/config/automation/dashboard"
         .header=${title}
         .scrollable=${this.narrow}
       >
@@ -452,11 +453,7 @@ export class HaAutomationTrace extends LitElement {
       if (runId) {
         const params = new URLSearchParams(location.search);
         params.delete("run_id");
-        history.replaceState(
-          null,
-          "",
-          `${location.pathname}?${params.toString()}`
-        );
+        replaceCurrentUrl(`${location.pathname}?${params.toString()}`);
       }
 
       await showAlertDialog(this, {

src/panels/config/automation/ha-manual-editor-mixin.ts

@@ -11,6 +11,7 @@ import { property, query, state } from "lit/decorators";
 import { classMap } from "lit/directives/class-map";
 import { storage } from "../../../common/decorators/storage";
 import { fireEvent } from "../../../common/dom/fire_event";
+import { replaceCurrentUrl } from "../../../common/navigate";
 import { constructUrlCurrentPath } from "../../../common/url/construct-url";
 import {
   extractSearchParam,
@@ -171,11 +172,7 @@ export const ManualEditorMixin = <TConfig>(
     }
 
     protected clearParam(param: string) {
-      window.history.replaceState(
-        null,
-        "",
-        constructUrlCurrentPath(removeSearchParam(param))
-      );
+      replaceCurrentUrl(constructUrlCurrentPath(removeSearchParam(param)));
     }
 
     protected async openSidebar(ev: CustomEvent<SidebarConfig>) {

src/panels/config/backup/ha-config-backup-overview.ts

@@ -74,8 +74,6 @@ class HaConfigBackupOverview extends LitElement {
 
   @state() private _config?: BackupConfig;
 
-  private _searchParms = new URLSearchParams(window.location.search);
-
   protected willUpdate(changedProperties: PropertyValues<this>): void {
     super.willUpdate(changedProperties);
     if (changedProperties.has("config") && !this._config) {
@@ -206,9 +204,7 @@ class HaConfigBackupOverview extends LitElement {
 
     return html`
       <hass-subpage
-        .backPath=${
-          this._searchParms.has("historyBack") ? undefined : "/config/system"
-        }
+        back-path="/config/system"
         .hass=${this.hass}
         .narrow=${this.narrow}
         .header=${this.hass.localize("ui.panel.config.backup.overview.header")}

src/panels/config/backup/ha-config-backup-settings.ts

@@ -4,6 +4,7 @@ import { css, html, LitElement, nothing } from "lit";
 import { customElement, property, state } from "lit/decorators";
 import { isComponentLoaded } from "../../../common/config/is_component_loaded";
 import { fireEvent } from "../../../common/dom/fire_event";
+import { replaceCurrentUrl } from "../../../common/navigate";
 import { debounce } from "../../../common/util/debounce";
 import { nextRender } from "../../../common/util/render-status";
 import "../../../components/ha-alert";
@@ -118,7 +119,7 @@ class HaConfigBackupSettings extends LitElement {
   }
 
   private _clearHash() {
-    history.replaceState(null, "", window.location.pathname);
+    replaceCurrentUrl(window.location.pathname);
   }
 
   protected render() {

src/panels/config/cloud/account/cloud-account.ts

@@ -68,7 +68,6 @@ export class CloudAccount extends SubscribeMixin(LitElement) {
       <hass-subpage
         .hass=${this.hass}
         .narrow=${this.narrow}
-        back-path="/config"
         header="Home Assistant Cloud"
       >
         <ha-dropdown slot="toolbar-icon" @wa-select=${this._handleMenuAction}>

src/panels/config/cloud/forgot-password/cloud-forgot-password.ts

@@ -21,6 +21,7 @@ export class CloudForgotPassword extends LitElement {
       <hass-subpage
         .hass=${this.hass}
         .narrow=${this.narrow}
+        back-path="/config"
         .header=${this.hass.localize(
           "ui.panel.config.cloud.forgot_password.title"
         )}

src/panels/config/cloud/login/cloud-login-panel.ts

@@ -45,6 +45,7 @@ export class CloudLoginPanel extends LitElement {
       <hass-subpage
         .hass=${this.hass}
         .narrow=${this.narrow}
+        back-path="/config"
         header="Home Assistant Cloud"
       >
         <ha-dropdown slot="toolbar-icon" @wa-select=${this._handleMenuAction}>

src/panels/config/cloud/register/cloud-register.ts

@@ -38,6 +38,7 @@ export class CloudRegister extends LitElement {
       <hass-subpage
         .hass=${this.hass}
         .narrow=${this.narrow}
+        back-path="/config"
         .header=${this.hass.localize("ui.panel.config.cloud.register.title")}
       >
         <div class="content">

src/panels/config/core/ha-config-section-updates.ts

@@ -66,8 +66,6 @@ class HaConfigSectionUpdates extends LitElement {
 
   @property({ type: Boolean }) public narrow = false;
 
-  @state() private _searchParms = new URLSearchParams(window.location.search);
-
   @state() private _showSkipped = false;
 
   @state() private _supervisorInfo?: HassioSupervisorInfo;
@@ -155,9 +153,7 @@ class HaConfigSectionUpdates extends LitElement {
 
     return html`
       <hass-subpage
-        .backPath=${
-          this._searchParms.has("historyBack") ? undefined : "/config/system"
-        }
+        back-path="/config/system"
         .hass=${this.hass}
         .narrow=${this.narrow}
         .header=${this.hass.localize("ui.panel.config.updates.caption")}

src/panels/config/devices/ha-config-device-page.ts

@@ -986,6 +986,7 @@ export class HaConfigDevicePage extends LitElement {
     return html`<hass-subpage
       .hass=${this.hass}
       .narrow=${this.narrow}
+      back-path="/config/devices/dashboard"
       .header=${deviceName}
     >
       <ha-tooltip for="edit-settings-button" slot="toolbar-icon">

src/panels/config/devices/ha-config-devices-dashboard.ts

@@ -23,7 +23,7 @@ import {
   PROTOCOL_INTEGRATIONS,
   protocolIntegrationPicked,
 } from "../../../common/integrations/protocolIntegrationPicked";
-import { navigate } from "../../../common/navigate";
+import { navigate, updateHistoryState } from "../../../common/navigate";
 import type { LocalizeFunc } from "../../../common/translations/localize";
 import {
   hasRejectedItems,
@@ -778,9 +778,7 @@ export class HaConfigDeviceDashboard extends LitElement {
       <hass-tabs-subpage-data-table
         .hass=${this.hass}
         .narrow=${this.narrow}
-        .backPath=${
-          this._searchParms.has("historyBack") ? undefined : "/config"
-        }
+        back-path="/config"
         .tabs=${configSections.devices}
         .route=${this.route}
         .searchLabel=${this.hass.localize(
@@ -1043,7 +1041,7 @@ export class HaConfigDeviceDashboard extends LitElement {
 
   private _handleSearchChange(ev: CustomEvent) {
     this._filter = ev.detail.value;
-    history.replaceState({ filter: this._filter }, "");
+    updateHistoryState({ filter: this._filter });
   }
 
   private _addDevice() {

src/panels/config/energy/ha-config-energy.ts

@@ -78,8 +78,6 @@ class HaConfigEnergy extends LitElement {
 
   @property({ attribute: false }) public route!: Route;
 
-  @state() private _searchParms = new URLSearchParams(window.location.search);
-
   @state() private _info?: EnergyInfo;
 
   @state() private _preferences?: EnergyPreferences;
@@ -126,11 +124,7 @@ class HaConfigEnergy extends LitElement {
     return html`
       <hass-tabs-subpage
         .hass=${this.hass}
-        .backPath=${
-          this._searchParms.has("historyBack")
-            ? undefined
-            : "/config/lovelace/dashboards"
-        }
+        back-path="/config/lovelace/dashboards"
         .route=${this.route}
         .tabs=${TABS}
       >

src/panels/config/entities/ha-config-entities.ts

@@ -39,6 +39,7 @@ import {
   PROTOCOL_INTEGRATIONS,
   protocolIntegrationPicked,
 } from "../../../common/integrations/protocolIntegrationPicked";
+import { updateHistoryState } from "../../../common/navigate";
 import { slugify } from "../../../common/string/slugify";
 import type { LocalizeFunc } from "../../../common/translations/localize";
 import {
@@ -810,9 +811,7 @@ export class HaConfigEntities extends LitElement {
       <hass-tabs-subpage-data-table
         .hass=${this.hass}
         .narrow=${this.narrow}
-        .backPath=${
-          this._searchParms.has("historyBack") ? undefined : "/config"
-        }
+        back-path="/config"
         .route=${this.route}
         .tabs=${configSections.devices}
         .columns=${this._columns(this.hass.localize, filteredEntities)}
@@ -1246,7 +1245,7 @@ export class HaConfigEntities extends LitElement {
 
   private _handleSearchChange(ev: CustomEvent) {
     this._filter = ev.detail.value;
-    history.replaceState({ filter: this._filter }, "");
+    updateHistoryState({ filter: this._filter });
   }
 
   private _handleSelectionChanged(

src/panels/config/helpers/ha-config-helpers.ts

@@ -644,9 +644,7 @@ export class HaConfigHelpers extends SubscribeMixin(LitElement) {
       <hass-tabs-subpage-data-table
         .hass=${this.hass}
         .narrow=${this.narrow}
-        .backPath=${
-          this._searchParms.has("historyBack") ? undefined : "/config"
-        }
+        back-path="/config"
         .route=${this.route}
         .tabs=${configSections.devices}
         .searchLabel=${this.hass.localize(

src/panels/config/integrations/ha-config-integration-page.ts

@@ -373,7 +373,11 @@ class HaConfigIntegrationPage extends SubscribeMixin(LitElement) {
       : this._manifest?.documentation;
 
     return html`
-      <hass-subpage .hass=${this.hass} .narrow=${this.narrow}>
+      <hass-subpage
+        .hass=${this.hass}
+        .narrow=${this.narrow}
+        back-path="/config/integrations/dashboard"
+      >
         ${
           documentationLink
             ? html`

src/panels/config/integrations/ha-config-integrations-dashboard.ts

@@ -13,7 +13,7 @@ import {
   PROTOCOL_INTEGRATIONS,
   protocolIntegrationPicked,
 } from "../../../common/integrations/protocolIntegrationPicked";
-import { navigate } from "../../../common/navigate";
+import { navigate, updateHistoryState } from "../../../common/navigate";
 import { caseInsensitiveStringCompare } from "../../../common/string/compare";
 import { extractSearchParam } from "../../../common/url/search-params";
 import { nextRender } from "../../../common/util/render-status";
@@ -158,8 +158,6 @@ class HaConfigIntegrationsDashboard extends KeyboardShortcutMixin(
     window.location.hash.substring(1)
   );
 
-  @state() private _searchParams = new URLSearchParams(window.location.search);
-
   @state() private _filter: string = history.state?.filter || "";
 
   @state() private _logInfos?: Record<string, IntegrationLogInfo>;
@@ -503,9 +501,7 @@ class HaConfigIntegrationsDashboard extends KeyboardShortcutMixin(
     return html`
       <hass-tabs-subpage
         .hass=${this.hass}
-        .backPath=${
-          this._searchParams.has("historyBack") ? undefined : "/config"
-        }
+        back-path="/config"
         .route=${this.route}
         .tabs=${configSections.devices}
         has-fab
@@ -862,7 +858,7 @@ class HaConfigIntegrationsDashboard extends KeyboardShortcutMixin(
 
   private _handleSearchChange(ev: InputEvent) {
     this._filter = (ev.target as HaInputSearch).value ?? "";
-    history.replaceState({ filter: this._filter }, "");
+    updateHistoryState({ filter: this._filter });
   }
 
   private async _highlightEntry() {

src/panels/config/integrations/integration-panels/dhcp/dhcp-config-panel.ts

@@ -95,6 +95,7 @@ export class DHCPConfigPanel extends SubscribeMixin(LitElement) {
         .hass=${this.hass}
         .narrow=${this.narrow}
         .route=${this.route}
+        back-path="/config/integrations/integration/dhcp"
         .columns=${this._columns(this.hass.localize)}
         .data=${this._dataWithIds(this._data)}
         .noDataText=${this.hass.localize(

src/panels/config/integrations/integration-panels/mqtt/mqtt-config-panel.ts

@@ -61,7 +61,11 @@ export class MQTTConfigPanel extends LitElement {
 
   protected render(): TemplateResult {
     return html`
-      <hass-subpage .narrow=${this.narrow} .hass=${this.hass}>
+      <hass-subpage
+        .narrow=${this.narrow}
+        .hass=${this.hass}
+        back-path="/config/integrations/integration/mqtt"
+      >
         <div class="content">
           <ha-card
             .header=${this.hass.localize("ui.panel.config.mqtt.settings_title")}

src/panels/config/integrations/integration-panels/ssdp/ssdp-config-panel.ts

@@ -99,6 +99,7 @@ export class SSDPConfigPanel extends SubscribeMixin(LitElement) {
         .hass=${this.hass}
         .narrow=${this.narrow}
         .route=${this.route}
+        back-path="/config/integrations/integration/ssdp"
         .columns=${this._columns(this.hass.localize)}
         .initialGroupColumn=${this._activeGrouping}
         .initialCollapsedGroups=${this._activeCollapsed}

src/panels/config/integrations/integration-panels/zeroconf/zeroconf-config-panel.ts

@@ -106,6 +106,7 @@ export class ZeroconfConfigPanel extends SubscribeMixin(LitElement) {
         .hass=${this.hass}
         .narrow=${this.narrow}
         .route=${this.route}
+        back-path="/config/integrations/integration/zeroconf"
         .columns=${this._columns(this.hass.localize)}
         .initialGroupColumn=${this._activeGrouping}
         .initialCollapsedGroups=${this._activeCollapsed}

src/panels/config/integrations/integration-panels/zha/zha-add-devices-page.ts

@@ -76,6 +76,7 @@ class ZHAAddDevicesPage extends LitElement {
       <hass-subpage
         .hass=${this.hass}
         .narrow=${this.narrow}
+        back-path="/config/zha/dashboard"
         .header=${this.hass.localize("ui.panel.config.zha.add_device")}
       >
         <ha-button

src/panels/config/integrations/integration-panels/zha/zha-network-visualization-page.ts

@@ -55,6 +55,7 @@ export class ZHANetworkVisualizationPage extends LitElement {
       <hass-subpage
         .hass=${this.hass}
         .narrow=${this.narrow}
+        back-path="/config/zha/dashboard"
         .header=${this.hass.localize(
           "ui.panel.config.zha.visualization.header"
         )}

src/panels/config/integrations/integration-panels/zwave_js/zwave_js-config-entry-picker.ts

@@ -34,7 +34,12 @@ class ZWaveJSConfigEntryPicker extends LitElement {
 
     if (this._configEntries.length === 0) {
       return html`
-        <hass-subpage header="Z-Wave" .narrow=${this.narrow} .hass=${this.hass}>
+        <hass-subpage
+          header="Z-Wave"
+          .narrow=${this.narrow}
+          .hass=${this.hass}
+          back-path="/config/integrations/integration/zwave_js"
+        >
           <div class="content">
             <ha-card>
               <div class="card-content">
@@ -51,7 +56,12 @@ class ZWaveJSConfigEntryPicker extends LitElement {
     }
 
     return html`
-      <hass-subpage header="Z-Wave" .narrow=${this.narrow} .hass=${this.hass}>
+      <hass-subpage
+        header="Z-Wave"
+        .narrow=${this.narrow}
+        .hass=${this.hass}
+        back-path="/config/integrations/integration/zwave_js"
+      >
         <div class="content">
           <ha-card
             .header=${this.hass.localize(

src/panels/config/lovelace/resources/ha-config-lovelace-resources.ts

@@ -175,6 +175,7 @@ export class HaConfigLovelaceResources extends LitElement {
         .hass=${this.hass}
         .narrow=${this.narrow}
         .route=${this.route}
+        back-path="/config/lovelace/dashboards"
         .tabs=${lovelaceResourcesTabs}
         .columns=${this._columns(this.hass.language, this.hass.localize)}
         .data=${this._resources}

src/panels/config/repairs/ha-config-repairs-dashboard.ts

@@ -32,8 +32,6 @@ class HaConfigRepairsDashboard extends SubscribeMixin(LitElement) {
 
   @state() private _repairsIssues: RepairsIssue[] = [];
 
-  @state() private _searchParms = new URLSearchParams(window.location.search);
-
   @state() private _showIgnored = false;
 
   private _getFilteredIssues = memoizeOne(
@@ -77,9 +75,7 @@ class HaConfigRepairsDashboard extends SubscribeMixin(LitElement) {
 
     return html`
       <hass-subpage
-        .backPath=${
-          this._searchParms.has("historyBack") ? undefined : "/config/system"
-        }
+        back-path="/config/system"
         .hass=${this.hass}
         .narrow=${this.narrow}
         .header=${this.hass.localize("ui.panel.config.repairs.caption")}

src/panels/config/scene/ha-scene-dashboard.ts

@@ -459,9 +459,7 @@ class HaSceneDashboard extends SubscribeMixin(LitElement) {
       <hass-tabs-subpage-data-table
         .hass=${this.hass}
         .narrow=${this.narrow}
-        .backPath=${
-          this._searchParms.has("historyBack") ? undefined : "/config"
-        }
+        back-path="/config"
         .route=${this.route}
         .tabs=${configSections.automations}
         .searchLabel=${this.hass.localize(

src/panels/config/script/ha-script-picker.ts

@@ -430,9 +430,7 @@ class HaScriptPicker extends SubscribeMixin(LitElement) {
       <hass-tabs-subpage-data-table
         .hass=${this.hass}
         .narrow=${this.narrow}
-        .backPath=${
-          this._searchParms.has("historyBack") ? undefined : "/config"
-        }
+        back-path="/config"
         .route=${this.route}
         .tabs=${configSections.automations}
         .searchLabel=${this.hass.localize(

src/panels/config/script/ha-script-trace.ts

@@ -14,7 +14,7 @@ import { css, html, LitElement, nothing } from "lit";
 import { customElement, property, query, state } from "lit/decorators";
 import { isComponentLoaded } from "../../../common/config/is_component_loaded";
 import { fireEvent } from "../../../common/dom/fire_event";
-import { navigate } from "../../../common/navigate";
+import { navigate, replaceCurrentUrl } from "../../../common/navigate";
 import "../../../components/ha-button";
 import "../../../components/ha-dropdown";
 import type { HaDropdownSelectEvent } from "../../../components/ha-dropdown";
@@ -106,6 +106,7 @@ export class HaScriptTrace extends LitElement {
       <hass-subpage
         .hass=${this.hass}
         .narrow=${this.narrow}
+        back-path="/config/script/dashboard"
         .header=${title}
         .scrollable=${this.narrow}
       >
@@ -433,11 +434,7 @@ export class HaScriptTrace extends LitElement {
       if (runId) {
         const params = new URLSearchParams(location.search);
         params.delete("run_id");
-        history.replaceState(
-          null,
-          "",
-          `${location.pathname}?${params.toString()}`
-        );
+        replaceCurrentUrl(`${location.pathname}?${params.toString()}`);
       }
 
       await showAlertDialog(this, {

src/panels/config/voice-assistants/assist/ha-config-voice-assistants-assist-devices.ts

@@ -128,6 +128,7 @@ class AssistDevicesPage extends LitElement {
       <hass-subpage
         .hass=${this.hass}
         .narrow=${this.narrow}
+        back-path="/config/voice-assistants/assistants"
         .header=${this.hass.localize(
           "ui.panel.config.voice_assistants.assistants.pipeline.devices.title"
         )}

src/panels/config/voice-assistants/debug/assist-pipeline-debug.ts

@@ -51,6 +51,7 @@ export class AssistPipelineDebug extends LitElement {
     return html`<hass-subpage
       .narrow=${this.narrow}
       .hass=${this.hass}
+      back-path="/config/voice-assistants/debug"
       .header=${this.hass.localize(
         "ui.panel.config.voice_assistants.debug.header"
       )}

src/panels/config/voice-assistants/debug/assist-pipeline-run-debug.ts

@@ -60,6 +60,7 @@ export class AssistPipelineRunDebug extends LitElement {
       <hass-subpage
         .narrow=${this.narrow}
         .hass=${this.hass}
+        back-path="/config/voice-assistants/assistants"
         .header=${this.hass.localize(
           "ui.panel.config.voice_assistants.debug.pipeline.header"
         )}

src/panels/config/voice-assistants/ha-config-voice-assistants-assistants.ts

@@ -29,8 +29,6 @@ export class HaConfigVoiceAssistantsAssistants extends LitElement {
 
   @property({ attribute: false }) public route!: Route;
 
-  private _searchParms = new URLSearchParams(window.location.search);
-
   protected render() {
     if (!this.hass) {
       return html`<hass-loading-screen></hass-loading-screen>`;
@@ -39,9 +37,7 @@ export class HaConfigVoiceAssistantsAssistants extends LitElement {
     return html`
       <hass-tabs-subpage
         .hass=${this.hass}
-        .backPath=${
-          this._searchParms.has("historyBack") ? undefined : "/config"
-        }
+        back-path="/config"
         .route=${this.route}
         .tabs=${voiceAssistantTabs}
       >

src/panels/config/voice-assistants/ha-config-voice-assistants-expose.ts

@@ -492,9 +492,7 @@ export class VoiceAssistantsExpose extends LitElement {
       <hass-tabs-subpage-data-table
         .hass=${this.hass}
         .narrow=${this.narrow}
-        .backPath=${
-          this._searchParms.has("historyBack") ? undefined : "/config"
-        }
+        back-path="/config"
         .route=${this.route}
         .tabs=${voiceAssistantTabs}
         .columns=${this._columns(

src/panels/config/zone/ha-config-zone.ts

@@ -57,8 +57,6 @@ export class HaConfigZone extends SubscribeMixin(LitElement) {
 
   @property({ attribute: false }) public route!: Route;
 
-  @state() private _searchParms = new URLSearchParams(window.location.search);
-
   @state() private _storageItems?: Zone[];
 
   @state() private _stateItems?: HassEntity[];
@@ -248,9 +246,7 @@ export class HaConfigZone extends SubscribeMixin(LitElement) {
       <hass-tabs-subpage
         .hass=${this.hass}
         .route=${this.route}
-        .backPath=${
-          this._searchParms.has("historyBack") ? undefined : "/config"
-        }
+        back-path="/config"
         .tabs=${configSections.areas}
         has-fab
       >

src/panels/lovelace/ha-panel-lovelace.ts

@@ -4,7 +4,7 @@ import type { PropertyValues, TemplateResult } from "lit";
 import { html, LitElement } from "lit";
 import { customElement, property, state } from "lit/decorators";
 import memoizeOne from "memoize-one";
-import { navigate } from "../../common/navigate";
+import { navigate, replaceCurrentUrl } from "../../common/navigate";
 import type { LocalizeFunc } from "../../common/translations/localize";
 import { constructUrlCurrentPath } from "../../common/url/construct-url";
 import {
@@ -509,9 +509,7 @@ export class LovelacePanel extends LitElement {
     };
 
     if ("editMode" in props) {
-      window.history.replaceState(
-        null,
-        "",
+      replaceCurrentUrl(
         constructUrlCurrentPath(
           props.editMode
             ? addSearchParam({ edit: "1" })

src/panels/lovelace/hui-root.ts

@@ -28,7 +28,7 @@ import { isComponentLoaded } from "../../common/config/is_component_loaded";
 import { UndoRedoController } from "../../common/controllers/undo-redo-controller";
 import { fireEvent } from "../../common/dom/fire_event";
 import { isNavigationClick } from "../../common/dom/is-navigation-click";
-import { goBack, navigate } from "../../common/navigate";
+import { goBack, navigate, replaceCurrentUrl } from "../../common/navigate";
 import type { LocalizeKeys } from "../../common/translations/localize";
 import { constructUrlCurrentPath } from "../../common/url/construct-url";
 import { sanitizeNavigationPath } from "../../common/url/sanitize-navigation-path";
@@ -677,11 +677,7 @@ class HUIRoot extends LitElement {
     );
 
   private _clearParam(param: string) {
-    window.history.replaceState(
-      null,
-      "",
-      constructUrlCurrentPath(removeSearchParam(param))
-    );
+    replaceCurrentUrl(constructUrlCurrentPath(removeSearchParam(param)));
   }
 
   protected firstUpdated(changedProps: PropertyValues<this>) {
@@ -894,22 +890,10 @@ class HUIRoot extends LitElement {
 
   private _goBack(): void {
     const views = this.lovelace?.config.views ?? [];
-    const curViewConfig =
-      typeof this._curView === "number" ? views[this._curView] : undefined;
+    // Falling back to the first view only makes sense when it is a real view.
+    const fallbackPath = views[0]?.subview ? undefined : this.route?.prefix;
 
-    const backPath = sanitizeNavigationPath(
-      curViewConfig?.back_path ?? this.backPath
-    );
-
-    if (backPath) {
-      navigate(backPath, { replace: true });
-    } else if (history.length > 1) {
-      goBack();
-    } else if (!views[0].subview) {
-      navigate(this.route!.prefix, { replace: true });
-    } else {
-      navigate("/");
-    }
+    goBack(this._backPath ?? fallbackPath);
   }
 
   private _handleBackClick(ev: MouseEvent): void {

src/panels/lovelace/views/hui-sections-view.ts

@@ -9,6 +9,7 @@ import { repeat } from "lit/directives/repeat";
 import { styleMap } from "lit/directives/style-map";
 import memoizeOne from "memoize-one";
 import { clamp } from "../../../common/number/clamp";
+import { updateHistoryState } from "../../../common/navigate";
 import "../../../components/ha-icon-button";
 import "../../../components/ha-ripple";
 import "../../../components/ha-sortable";
@@ -494,10 +495,7 @@ export class SectionsView extends LitElement implements LovelaceViewElement {
     this._sidebarTabActive = !this._sidebarTabActive;
 
     // Add sidebar state to history
-    window.history.replaceState(
-      { ...window.history.state, sidebar: this._sidebarTabActive },
-      ""
-    );
+    updateHistoryState({ sidebar: this._sidebarTabActive });
 
     // Restore scroll position after view updates
     this.updateComplete.then(() => {

src/panels/profile/ha-profile-section-general.ts

@@ -4,6 +4,7 @@ import { css, html, LitElement, nothing } from "lit";
 import { customElement, property, state } from "lit/decorators";
 import { isComponentLoaded } from "../../common/config/is_component_loaded";
 import { fireEvent } from "../../common/dom/fire_event";
+import { replaceCurrentUrl } from "../../common/navigate";
 import { nextRender } from "../../common/util/render-status";
 import "../../components/ha-button";
 import "../../components/ha-card";
@@ -90,7 +91,7 @@ class HaProfileSectionGeneral extends LitElement {
   }
 
   private _clearHash() {
-    history.replaceState(null, "", window.location.pathname);
+    replaceCurrentUrl(window.location.pathname);
   }
 
   protected render(): TemplateResult {

src/state/url-sync-mixin.ts

@@ -2,6 +2,7 @@
 import type { ReactiveElement, PropertyValues } from "lit";
 import { fireEvent } from "../common/dom/fire_event";
 import { mainWindow } from "../common/dom/get_main_window";
+import { updateHistoryState } from "../common/navigate";
 import { closeLastDialog } from "../dialogs/make-dialog-manager";
 import type { ProvideHassElement } from "../mixins/provide-hass-lit-mixin";
 import type { Constructor } from "../types";
@@ -20,10 +21,7 @@ export const urlSyncMixin = <
         public connectedCallback(): void {
           super.connectedCallback();
           if (mainWindow.history.length === 1) {
-            mainWindow.history.replaceState(
-              { ...mainWindow.history.state, root: true },
-              ""
-            );
+            updateHistoryState({ root: true });
           }
           mainWindow.addEventListener("popstate", this._popstateChangeListener);
         }

test/common/navigate.test.ts

@@ -0,0 +1,88 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { canGoBack, goBack, navigate } from "../../src/common/navigate";
+
+// navigate() closes open dialogs before touching history.
+vi.mock("../../src/dialogs/make-dialog-manager", () => ({
+  closeAllDialogs: vi.fn(async () => true),
+}));
+
+// Sets up a raw entry the way a document load does, which is exactly what the
+// helpers in common/navigate refuse to produce.
+const setEntry = (path: string, state: unknown = null) => {
+  window.history.replaceState(state, "", path);
+};
+
+describe("navigate", () => {
+  beforeEach(() => {
+    setEntry("/config");
+  });
+
+  it("stamps the path we came from on pushed entries", async () => {
+    await navigate("/config/devices/dashboard");
+
+    expect(window.location.pathname).toEqual("/config/devices/dashboard");
+    expect(window.history.state).toMatchObject({ from: "/config" });
+  });
+
+  it("keeps caller data alongside the stamp", async () => {
+    await navigate("/config/areas", { data: { scrollPosition: 42 } });
+
+    expect(window.history.state).toMatchObject({
+      scrollPosition: 42,
+      from: "/config",
+    });
+  });
+
+  it("keeps the stamp when replacing, the predecessor is unchanged", async () => {
+    await navigate("/config/cloud");
+    await navigate("/config/cloud/account", { replace: true });
+
+    expect(window.location.pathname).toEqual("/config/cloud/account");
+    expect(window.history.state).toMatchObject({ from: "/config" });
+  });
+
+  it("does not stamp an entry the app did not push", () => {
+    expect(window.history.state).toBeNull();
+    expect(canGoBack()).toBe(false);
+  });
+});
+
+describe("goBack", () => {
+  beforeEach(() => {
+    setEntry("/config/cloud/remote");
+    vi.restoreAllMocks();
+  });
+
+  it("goes back when we came from another page in the app", async () => {
+    const back = vi
+      .spyOn(window.history, "back")
+      .mockImplementation(() => undefined);
+    await navigate("/config/cloud/remote");
+
+    await goBack("/config/cloud/account");
+
+    expect(back).toHaveBeenCalledOnce();
+  });
+
+  it("falls back to the given path when the previous entry is not ours", async () => {
+    // A login redirect lands on the page through location.assign, leaving
+    // /auth/authorize behind: going back there would leave the app.
+    const back = vi
+      .spyOn(window.history, "back")
+      .mockImplementation(() => undefined);
+
+    await goBack("/config/cloud/account");
+
+    expect(back).not.toHaveBeenCalled();
+    expect(window.location.pathname).toEqual("/config/cloud/account");
+  });
+
+  it("falls back to the root when no path is given", async () => {
+    vi.spyOn(window.history, "back").mockImplementation(() => undefined);
+
+    await goBack();
+
+    expect(window.location.pathname).toEqual("/");
+  });
+});

test/layouts/hass-subpage.test.ts

@@ -28,7 +28,7 @@ afterEach(() => {
 describe("hass-subpage back path", () => {
   it("links to a path on the current origin", async () => {
     const backButton = await mount("/config/system");
-    expect(backButton!.getAttribute("href")).toEqual("/config/system");
+    expect(backButton!.href).toEqual("/config/system");
   });
 
   // eslint-disable-next-line no-script-url
@@ -36,7 +36,7 @@ describe("hass-subpage back path", () => {
     "does not link to %s",
     async (backPath) => {
       const backButton = await mount(backPath);
-      expect(backButton!.hasAttribute("href")).toBe(false);
+      expect(backButton!.href).toBeUndefined();
     }
   );
 });