uicore-ts 1.1.385 → 1.1.387

package/compiledScripts/UICore.js

@@ -107,11 +107,8 @@ const _UICore = class extends import_UIObject.UIObject {
       });
     };
     window.addEventListener("scroll", didScroll, false);
-    const hashDidChange = () => {
-      this.reapplyCurrentRoute();
-    };
-    window.addEventListener("hashchange", hashDidChange, false);
-    hashDidChange();
+    import_UIRoute.UIRoute._installNativeHistoryNavigationGuard(() => this.reapplyCurrentRoute());
+    this.reapplyCurrentRoute();
   }
   reapplyCurrentRoute() {
     return __async(this, null, function* () {

package/compiledScripts/UICore.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../scripts/UICore.ts"],
-  "sourcesContent": ["import \"./UICoreExtensions\"\nimport { UILanguageService } from \"./UIInterfaces\"\nimport { nil, NO, UIObject } from \"./UIObject\"\nimport { UIRoute } from \"./UIRoute\"\nimport { UIView } from \"./UIView\"\nimport { UIViewController } from \"./UIViewController\"\n\n\nexport class UICore extends UIObject {\n\n    rootViewController: UIViewController\n\n\n\n    static RootViewControllerClass: typeof UIViewController\n    static main: UICore\n\n    static languageService: UILanguageService = nil\n\n    static readonly broadcastEventName = {\n\n        \"RouteDidChange\": \"RouteDidChange\",\n        \"WindowDidResize\": \"WindowDidResize\"\n\n    }\n\n    // See `reapplyCurrentRoute` for why these exist and why route application\n    // must always go through it rather than calling `rootViewController.handleRoute`\n    // or `handleRouteRecursively` directly.\n    _isApplyingRoute = false\n    _hasQueuedRouteChangeWhileApplying = false\n    _currentRouteApplicationPromise?: Promise<void>\n\n    constructor(rootDivElementID: string, rootViewControllerClass: typeof UIViewController, public paddingLength = 20) {\n        \n        super()\n        \n        UICore.RootViewControllerClass = rootViewControllerClass\n        UICore.main = UICore.main || this\n        \n        const rootViewElement = document.getElementById(rootDivElementID)\n        const rootView = new UIView(rootDivElementID, rootViewElement)\n        rootView.pausesPointerEvents = NO //YES;\n        rootView.core = this\n        \n        if (UICore.RootViewControllerClass) {\n            \n            if (!(UICore.RootViewControllerClass.prototype instanceof UIViewController) ||\n                (UICore.RootViewControllerClass as any) === UIViewController) {\n                \n                console.log(\n                    \"Error, UICore.RootViewControllerClass must be UIViewController or a subclass of UIViewController, \" +\n                    \"falling back to UIViewController.\"\n                )\n                \n                UICore.RootViewControllerClass = UIViewController\n                \n            }\n            \n            this.rootViewController = new UICore.RootViewControllerClass(rootView)\n            \n        }\n        else {\n            \n            this.rootViewController = new UIViewController(rootView)\n            \n        }\n        \n        this.rootViewController.viewWillAppear().then(() =>\n            this.rootViewController.viewDidAppear()\n        )\n        \n        \n        this.rootViewController.view.addTargetForControlEvent(\n            UIView.controlEvent.PointerUpInside,\n            (sender, event) => {\n\n                // Only dismiss focus for taps genuinely outside the focused element - not for\n                // the tap that just focused it (or a tap on one of its own children). Native\n                // controls like <select> gain focus on mousedown and open their own popup; if\n                // this handler blurs them on the very next PointerUpInside regardless of target,\n                // it closes that popup before the user can pick an option (macOS Chrome renders\n                // <select> popups as a native control that closes as soon as its anchor blurs).\n                const activeElement = document.activeElement as HTMLElement | null\n                const eventTarget = event?.target as Node | null\n\n                if (activeElement && eventTarget &&\n                    (activeElement === eventTarget || activeElement.contains(eventTarget))) {\n                    return\n                }\n\n                activeElement?.blur?.()\n\n            }\n        )\n        \n        \n        const windowDidResize = () => {\n            \n            UIView.resetLayoutCycleTrackingForAllViews()\n            \n            this.rootViewController.view.forEachViewInSubtree((view) => {\n                \n                view._frameCache = undefined\n                \n            })\n            // Doing layout two times to prevent page scrollbars from confusing the layout\n            this.rootViewController.view.setNeedsLayout()\n            this.rootViewController._triggerLayoutViewSubviews()\n            UIView.layoutViewsIfNeeded()\n            \n            this.rootViewController._triggerLayoutViewSubviews()\n            UIView.layoutViewsIfNeeded()\n            \n            this.rootViewController.view.broadcastEventInSubtree({\n                \n                name: UICore.broadcastEventName.WindowDidResize,\n                parameters: nil\n                \n            })\n            \n        }\n        \n        window.addEventListener(\"resize\", windowDidResize)\n        \n        const didScroll = () => {\n            \n            //code\n            \n            this.rootViewController.view.broadcastEventInSubtree({\n                \n                name: UIView.broadcastEventName.PageDidScroll,\n                parameters: nil\n                \n            })\n            \n            \n        }\n        \n        window.addEventListener(\"scroll\", didScroll, false)\n\n        const hashDidChange = () => {\n\n            //code\n\n            this.reapplyCurrentRoute()\n\n        }\n\n        window.addEventListener(\"hashchange\", hashDidChange, false)\n\n        hashDidChange()\n\n\n    }\n\n\n    /**\n     * Re-runs route handling for `UIRoute.currentRoute` against `rootViewController`,\n     * serialized against every other caller of this method (including the\n     * `hashchange` listener installed in the constructor).\n     *\n     * This is the ONLY correct way to force route handling to (re-)run - never\n     * call `rootViewController.handleRoute(...)` or `handleRouteRecursively(...)`\n     * directly. A route change can legitimately be requested twice in quick\n     * succession from independent, uncoordinated places (e.g. two related\n     * server-pushed broadcasts derived from one real-world event, each\n     * triggering its own re-apply). Without serialization, two concurrent,\n     * un-synchronized route applications race on shared root-view-controller\n     * state (`contentViewController`, `detailsViewController`) and whichever\n     * finishes last wins - regardless of which request was actually last, or\n     * which request even reflects the current, settled state. Serializing here\n     * instead coalesces a request that arrives mid-application into a single\n     * trailing re-run rather than starting a second, overlapping one, and that\n     * re-run re-reads `UIRoute.currentRoute` fresh once the burst has settled,\n     * so the final state always matches the truly-last route.\n     */\n    async reapplyCurrentRoute(): Promise<void> {\n\n        if (this._isApplyingRoute) {\n\n            // Joining an in-flight application: request one more loop pass\n            // (guaranteed to observe `UIRoute.currentRoute` fresh, since the\n            // owner below re-reads it at the top of every pass) and await the\n            // SAME promise the owner is already awaiting, rather than\n            // returning early - a caller of this method expects route\n            // handling to have actually run by the time it resolves.\n            this._hasQueuedRouteChangeWhileApplying = true\n            return this._currentRouteApplicationPromise\n\n        }\n\n        this._isApplyingRoute = true\n\n        this._currentRouteApplicationPromise = (async () => {\n\n            try {\n\n                do {\n\n                    this._hasQueuedRouteChangeWhileApplying = false\n\n                    await this.rootViewController.handleRouteRecursively(UIRoute.currentRoute)\n\n                    this.rootViewController.view.broadcastEventInSubtree({\n\n                        name: UICore.broadcastEventName.RouteDidChange,\n                        parameters: nil\n\n                    })\n\n                } while (this._hasQueuedRouteChangeWhileApplying)\n\n            }\n            finally {\n\n                this._isApplyingRoute = false\n                this._currentRouteApplicationPromise = undefined\n\n            }\n\n        })()\n\n        return this._currentRouteApplicationPromise\n\n    }\n\n\n}\n\n\nArray.prototype.indexOf || (Array.prototype.indexOf = function (d, e) {\n    let a\n    if (null == this) {\n        throw new TypeError(\"\\\"this\\\" is null or not defined\")\n    }\n    const c = Object(this),\n        b = c.length >>> 0\n    if (0 === b) {\n        return -1\n    }\n    // @ts-ignore\n    a = +e || 0\n    Infinity === Math.abs(a) && (a = 0)\n    if (a >= b) {\n        return -1\n    }\n    for (a = Math.max(0 <= a ? a : b - Math.abs(a), 0); a < b;) {\n        if (a in c && c[a] === d) {\n            return a\n        }\n        a++\n    }\n    return -1\n})\n\n\n\n\n\n\n\n\n\n\n"],
-  "mappings": "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",
+  "sourcesContent": ["import \"./UICoreExtensions\"\nimport { UILanguageService } from \"./UIInterfaces\"\nimport { nil, NO, UIObject } from \"./UIObject\"\nimport { UIRoute } from \"./UIRoute\"\nimport { UIView } from \"./UIView\"\nimport { UIViewController } from \"./UIViewController\"\n\n\nexport class UICore extends UIObject {\n\n    rootViewController: UIViewController\n\n\n\n    static RootViewControllerClass: typeof UIViewController\n    static main: UICore\n\n    static languageService: UILanguageService = nil\n\n    static readonly broadcastEventName = {\n\n        \"RouteDidChange\": \"RouteDidChange\",\n        \"WindowDidResize\": \"WindowDidResize\"\n\n    }\n\n    // See `reapplyCurrentRoute` for why these exist and why route application\n    // must always go through it rather than calling `rootViewController.handleRoute`\n    // or `handleRouteRecursively` directly.\n    _isApplyingRoute = false\n    _hasQueuedRouteChangeWhileApplying = false\n    _currentRouteApplicationPromise?: Promise<void>\n\n    constructor(rootDivElementID: string, rootViewControllerClass: typeof UIViewController, public paddingLength = 20) {\n        \n        super()\n        \n        UICore.RootViewControllerClass = rootViewControllerClass\n        UICore.main = UICore.main || this\n        \n        const rootViewElement = document.getElementById(rootDivElementID)\n        const rootView = new UIView(rootDivElementID, rootViewElement)\n        rootView.pausesPointerEvents = NO //YES;\n        rootView.core = this\n        \n        if (UICore.RootViewControllerClass) {\n            \n            if (!(UICore.RootViewControllerClass.prototype instanceof UIViewController) ||\n                (UICore.RootViewControllerClass as any) === UIViewController) {\n                \n                console.log(\n                    \"Error, UICore.RootViewControllerClass must be UIViewController or a subclass of UIViewController, \" +\n                    \"falling back to UIViewController.\"\n                )\n                \n                UICore.RootViewControllerClass = UIViewController\n                \n            }\n            \n            this.rootViewController = new UICore.RootViewControllerClass(rootView)\n            \n        }\n        else {\n            \n            this.rootViewController = new UIViewController(rootView)\n            \n        }\n        \n        this.rootViewController.viewWillAppear().then(() =>\n            this.rootViewController.viewDidAppear()\n        )\n        \n        \n        this.rootViewController.view.addTargetForControlEvent(\n            UIView.controlEvent.PointerUpInside,\n            (sender, event) => {\n\n                // Only dismiss focus for taps genuinely outside the focused element - not for\n                // the tap that just focused it (or a tap on one of its own children). Native\n                // controls like <select> gain focus on mousedown and open their own popup; if\n                // this handler blurs them on the very next PointerUpInside regardless of target,\n                // it closes that popup before the user can pick an option (macOS Chrome renders\n                // <select> popups as a native control that closes as soon as its anchor blurs).\n                const activeElement = document.activeElement as HTMLElement | null\n                const eventTarget = event?.target as Node | null\n\n                if (activeElement && eventTarget &&\n                    (activeElement === eventTarget || activeElement.contains(eventTarget))) {\n                    return\n                }\n\n                activeElement?.blur?.()\n\n            }\n        )\n        \n        \n        const windowDidResize = () => {\n            \n            UIView.resetLayoutCycleTrackingForAllViews()\n            \n            this.rootViewController.view.forEachViewInSubtree((view) => {\n                \n                view._frameCache = undefined\n                \n            })\n            // Doing layout two times to prevent page scrollbars from confusing the layout\n            this.rootViewController.view.setNeedsLayout()\n            this.rootViewController._triggerLayoutViewSubviews()\n            UIView.layoutViewsIfNeeded()\n            \n            this.rootViewController._triggerLayoutViewSubviews()\n            UIView.layoutViewsIfNeeded()\n            \n            this.rootViewController.view.broadcastEventInSubtree({\n                \n                name: UICore.broadcastEventName.WindowDidResize,\n                parameters: nil\n                \n            })\n            \n        }\n        \n        window.addEventListener(\"resize\", windowDidResize)\n        \n        const didScroll = () => {\n            \n            //code\n            \n            this.rootViewController.view.broadcastEventInSubtree({\n                \n                name: UIView.broadcastEventName.PageDidScroll,\n                parameters: nil\n                \n            })\n            \n            \n        }\n        \n        window.addEventListener(\"scroll\", didScroll, false)\n\n        // Native Back/Forward navigation fires `hashchange` directly, which\n        // would otherwise reapply the route unconditionally below with no\n        // chance for the app to veto it (e.g. to protect unsaved changes) the\n        // way `UIRoute.apply()` can. This makes native history traversal go\n        // through the same `UIRoute.shouldApplyRouteChange` check first.\n        UIRoute._installNativeHistoryNavigationGuard(() => this.reapplyCurrentRoute())\n\n        this.reapplyCurrentRoute()\n\n\n    }\n\n\n    /**\n     * Re-runs route handling for `UIRoute.currentRoute` against `rootViewController`,\n     * serialized against every other caller of this method (including the\n     * `hashchange` listener installed in the constructor).\n     *\n     * This is the ONLY correct way to force route handling to (re-)run - never\n     * call `rootViewController.handleRoute(...)` or `handleRouteRecursively(...)`\n     * directly. A route change can legitimately be requested twice in quick\n     * succession from independent, uncoordinated places (e.g. two related\n     * server-pushed broadcasts derived from one real-world event, each\n     * triggering its own re-apply). Without serialization, two concurrent,\n     * un-synchronized route applications race on shared root-view-controller\n     * state (`contentViewController`, `detailsViewController`) and whichever\n     * finishes last wins - regardless of which request was actually last, or\n     * which request even reflects the current, settled state. Serializing here\n     * instead coalesces a request that arrives mid-application into a single\n     * trailing re-run rather than starting a second, overlapping one, and that\n     * re-run re-reads `UIRoute.currentRoute` fresh once the burst has settled,\n     * so the final state always matches the truly-last route.\n     */\n    async reapplyCurrentRoute(): Promise<void> {\n\n        if (this._isApplyingRoute) {\n\n            // Joining an in-flight application: request one more loop pass\n            // (guaranteed to observe `UIRoute.currentRoute` fresh, since the\n            // owner below re-reads it at the top of every pass) and await the\n            // SAME promise the owner is already awaiting, rather than\n            // returning early - a caller of this method expects route\n            // handling to have actually run by the time it resolves.\n            this._hasQueuedRouteChangeWhileApplying = true\n            return this._currentRouteApplicationPromise\n\n        }\n\n        this._isApplyingRoute = true\n\n        this._currentRouteApplicationPromise = (async () => {\n\n            try {\n\n                do {\n\n                    this._hasQueuedRouteChangeWhileApplying = false\n\n                    await this.rootViewController.handleRouteRecursively(UIRoute.currentRoute)\n\n                    this.rootViewController.view.broadcastEventInSubtree({\n\n                        name: UICore.broadcastEventName.RouteDidChange,\n                        parameters: nil\n\n                    })\n\n                } while (this._hasQueuedRouteChangeWhileApplying)\n\n            }\n            finally {\n\n                this._isApplyingRoute = false\n                this._currentRouteApplicationPromise = undefined\n\n            }\n\n        })()\n\n        return this._currentRouteApplicationPromise\n\n    }\n\n\n}\n\n\nArray.prototype.indexOf || (Array.prototype.indexOf = function (d, e) {\n    let a\n    if (null == this) {\n        throw new TypeError(\"\\\"this\\\" is null or not defined\")\n    }\n    const c = Object(this),\n        b = c.length >>> 0\n    if (0 === b) {\n        return -1\n    }\n    // @ts-ignore\n    a = +e || 0\n    Infinity === Math.abs(a) && (a = 0)\n    if (a >= b) {\n        return -1\n    }\n    for (a = Math.max(0 <= a ? a : b - Math.abs(a), 0); a < b;) {\n        if (a in c && c[a] === d) {\n            return a\n        }\n        a++\n    }\n    return -1\n})\n\n\n\n\n\n\n\n\n\n\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,8BAAO;AAEP,sBAAkC;AAClC,qBAAwB;AACxB,oBAAuB;AACvB,8BAAiC;AAG1B,MAAM,UAAN,cAAqB,yBAAS;AAAA,EAyBjC,YAAY,kBAA0B,yBAAyD,gBAAgB,IAAI;AAE/G,UAAM;AAFqF;AAJ/F,4BAAmB;AACnB,8CAAqC;AAOjC,YAAO,0BAA0B;AACjC,YAAO,OAAO,QAAO,QAAQ;AAE7B,UAAM,kBAAkB,SAAS,eAAe,gBAAgB;AAChE,UAAM,WAAW,IAAI,qBAAO,kBAAkB,eAAe;AAC7D,aAAS,sBAAsB;AAC/B,aAAS,OAAO;AAEhB,QAAI,QAAO,yBAAyB;AAEhC,UAAI,EAAE,QAAO,wBAAwB,qBAAqB,6CACrD,QAAO,4BAAoC,0CAAkB;AAE9D,gBAAQ;AAAA,UACJ;AAAA,QAEJ;AAEA,gBAAO,0BAA0B;AAAA,MAErC;AAEA,WAAK,qBAAqB,IAAI,QAAO,wBAAwB,QAAQ;AAAA,IAEzE,OACK;AAED,WAAK,qBAAqB,IAAI,yCAAiB,QAAQ;AAAA,IAE3D;AAEA,SAAK,mBAAmB,eAAe,EAAE;AAAA,MAAK,MAC1C,KAAK,mBAAmB,cAAc;AAAA,IAC1C;AAGA,SAAK,mBAAmB,KAAK;AAAA,MACzB,qBAAO,aAAa;AAAA,MACpB,CAAC,QAAQ,UAAU;AA3E/B;AAmFgB,cAAM,gBAAgB,SAAS;AAC/B,cAAM,cAAc,+BAAO;AAE3B,YAAI,iBAAiB,gBAChB,kBAAkB,eAAe,cAAc,SAAS,WAAW,IAAI;AACxE;AAAA,QACJ;AAEA,6DAAe,SAAf;AAAA,MAEJ;AAAA,IACJ;AAGA,UAAM,kBAAkB,MAAM;AAE1B,2BAAO,oCAAoC;AAE3C,WAAK,mBAAmB,KAAK,qBAAqB,CAAC,SAAS;AAExD,aAAK,cAAc;AAAA,MAEvB,CAAC;AAED,WAAK,mBAAmB,KAAK,eAAe;AAC5C,WAAK,mBAAmB,2BAA2B;AACnD,2BAAO,oBAAoB;AAE3B,WAAK,mBAAmB,2BAA2B;AACnD,2BAAO,oBAAoB;AAE3B,WAAK,mBAAmB,KAAK,wBAAwB;AAAA,QAEjD,MAAM,QAAO,mBAAmB;AAAA,QAChC,YAAY;AAAA,MAEhB,CAAC;AAAA,IAEL;AAEA,WAAO,iBAAiB,UAAU,eAAe;AAEjD,UAAM,YAAY,MAAM;AAIpB,WAAK,mBAAmB,KAAK,wBAAwB;AAAA,QAEjD,MAAM,qBAAO,mBAAmB;AAAA,QAChC,YAAY;AAAA,MAEhB,CAAC;AAAA,IAGL;AAEA,WAAO,iBAAiB,UAAU,WAAW,KAAK;AAOlD,2BAAQ,qCAAqC,MAAM,KAAK,oBAAoB,CAAC;AAE7E,SAAK,oBAAoB;AAAA,EAG7B;AAAA,EAuBM,sBAAqC;AAAA;AAEvC,UAAI,KAAK,kBAAkB;AAQvB,aAAK,qCAAqC;AAC1C,eAAO,KAAK;AAAA,MAEhB;AAEA,WAAK,mBAAmB;AAExB,WAAK,mCAAmC,MAAY;AAEhD,YAAI;AAEA,aAAG;AAEC,iBAAK,qCAAqC;AAE1C,kBAAM,KAAK,mBAAmB,uBAAuB,uBAAQ,YAAY;AAEzE,iBAAK,mBAAmB,KAAK,wBAAwB;AAAA,cAEjD,MAAM,QAAO,mBAAmB;AAAA,cAChC,YAAY;AAAA,YAEhB,CAAC;AAAA,UAEL,SAAS,KAAK;AAAA,QAElB,UACA;AAEI,eAAK,mBAAmB;AACxB,eAAK,kCAAkC;AAAA,QAE3C;AAAA,MAEJ,IAAG;AAEH,aAAO,KAAK;AAAA,IAEhB;AAAA;AAGJ;AAzNO,IAAM,SAAN;AAAM,OASF,kBAAqC;AATnC,OAWO,qBAAqB;AAAA,EAEjC,kBAAkB;AAAA,EAClB,mBAAmB;AAEvB;AA4MJ,MAAM,UAAU,YAAY,MAAM,UAAU,UAAU,SAAU,GAAG,GAAG;AAClE,MAAI;AACJ,MAAI,QAAQ,MAAM;AACd,UAAM,IAAI,UAAU,+BAAiC;AAAA,EACzD;AACA,QAAM,IAAI,OAAO,IAAI,GACjB,IAAI,EAAE,WAAW;AACrB,MAAI,MAAM,GAAG;AACT,WAAO;AAAA,EACX;AAEA,MAAI,CAAC,KAAK;AACV,eAAa,KAAK,IAAI,CAAC,MAAM,IAAI;AACjC,MAAI,KAAK,GAAG;AACR,WAAO;AAAA,EACX;AACA,OAAK,IAAI,KAAK,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,KAAI;AACxD,QAAI,KAAK,KAAK,EAAE,OAAO,GAAG;AACtB,aAAO;AAAA,IACX;AACA;AAAA,EACJ;AACA,SAAO;AACX;",
   "names": []
 }

package/compiledScripts/UIRoute.d.ts

@@ -17,6 +17,11 @@ export interface UIRouteChangeDescriptor {
 export type UIRouteShouldApplyRouteChangeCallbackFunction = (routeChangeDescriptor: UIRouteChangeDescriptor) => boolean | Promise<boolean>;
 export declare class UIRoute extends Array<UIRouteComponent> {
     static shouldApplyRouteChange?: UIRouteShouldApplyRouteChangeCallbackFunction;
+    static _presentedRoute: UIRoute;
+    static _presentedHistoryPosition: number;
+    static _recordedHistoryLength: number;
+    static _selfInitiatedRouteChange?: UIRouteChangeDescriptor;
+    static _nativeHistoryNavigationGeneration: number;
     constructor(hash?: string);
     static get currentRoute(): UIRoute;
     /**
@@ -29,11 +34,11 @@ export declare class UIRoute extends Array<UIRouteComponent> {
      */
     apply(forcefully?: boolean): boolean | Promise<boolean>;
     /**
-     * Applies this route without consulting `UIRoute.routeApplicationShouldProceed`.
+     * Applies this route without consulting `UIRoute.shouldApplyRouteChange`.
      * Use this only for route changes that are internal bookkeeping or that already
      * passed a higher-level confirmation flow.
      */
-    applyWithoutRouteApplicationCheck(forcefully?: boolean): boolean;
+    applyWithoutRouteChangeApproval(forcefully?: boolean): boolean;
     /**
      * @param forcefully When `true`, replaces the current history entry with
      * this route even when the route is identical to the current URL hash.
@@ -42,14 +47,57 @@ export declare class UIRoute extends Array<UIRouteComponent> {
     applyByReplacingCurrentRouteInHistory(forcefully?: boolean): boolean | Promise<boolean>;
     /**
      * Replaces the current history entry without consulting
-     * `UIRoute.routeApplicationShouldProceed`.
+     * `UIRoute.shouldApplyRouteChange`.
      */
-    applyByReplacingCurrentRouteInHistoryWithoutRouteApplicationCheck(forcefully?: boolean): boolean;
-    _applyRouteAfterRouteApplicationCheck(forcefully: boolean, replacesCurrentRouteInHistory: boolean): boolean | Promise<boolean>;
-    _applyRouteIfAllowed(routeApplicationShouldProceed: boolean, forcefully: boolean, replacesCurrentRouteInHistory: boolean): boolean;
-    _applyRouteWithoutRouteApplicationCheck(forcefully: boolean, replacesCurrentRouteInHistory: boolean): boolean;
-    _needsRouteApplication(forcefully: boolean): boolean;
-    _routeApplication(forcefully: boolean, replacesCurrentRouteInHistory: boolean): UIRouteChangeDescriptor;
+    applyByReplacingCurrentRouteInHistoryWithoutRouteChangeApproval(forcefully?: boolean): boolean;
+    _applyRouteAfterRouteChangeApproval(forcefully: boolean, replacesCurrentRouteInHistory: boolean): boolean | Promise<boolean>;
+    _applyRouteIfAllowed(isRouteChangeApproved: boolean, forcefully: boolean, replacesCurrentRouteInHistory: boolean): boolean;
+    _applyRouteWithoutRouteChangeApproval(forcefully: boolean, replacesCurrentRouteInHistory: boolean): boolean;
+    _needsRouteChange(forcefully: boolean): boolean;
+    _routeChangeDescriptor(forcefully: boolean, replacesCurrentRouteInHistory: boolean): UIRouteChangeDescriptor;
+    /**
+     * Installs handling so that native browser Back/Forward navigation
+     * consults `shouldApplyRouteChange` the same way `apply()` does, instead
+     * of silently bypassing it. Call exactly once, from `UICore`'s
+     * constructor.
+     *
+     * @param reapplyCurrentRoute Re-runs route handling for `UIRoute.currentRoute`.
+     * Called once a native navigation is allowed to proceed (or is self-initiated),
+     * so its effect actually appears on screen.
+     */
+    static _installNativeHistoryNavigationGuard(reapplyCurrentRoute: () => void | Promise<void>): void;
+    static _historyPositionFromCurrentEntry(): number | undefined;
+    static _recordPresentedRouteAtHistoryPosition(route: UIRoute, historyPosition: number): void;
+    /**
+     * The single listener installed for every `hashchange` - self-initiated,
+     * native Back/Forward, or an untagged bypass (see the class-level comment
+     * above `_presentedRoute`) - and the point where those three cases are
+     * told apart.
+     *
+     * @param event The native event. Only used to call
+     * `stopImmediatePropagation()` when a native traversal needs to be held
+     * back pending `shouldApplyRouteChange`, so `UICore`'s own route handling
+     * doesn't run before that check settles.
+     * @param reapplyCurrentRoute Forwarded to `_applyHistoryNavigationToRouteAtPositionIfAllowed`
+     * - see its own doc comment.
+     */
+    static _hashDidChange(event: HashChangeEvent, reapplyCurrentRoute: () => void | Promise<void>): void;
+    /**
+     * Consults `shouldApplyRouteChange` for a native Back/Forward traversal,
+     * exactly like `apply()` does for a programmatic one, then either lets it
+     * through or reverts it with `history.go(...)`.
+     *
+     * @param targetRoute The route the native traversal is asking to move to.
+     * @param targetHistoryPosition That route's tagged position, used both to
+     * revert (`history.go`) and to detect a newer navigation arriving mid-check.
+     * @param navigationGeneration A token captured by the caller at dispatch
+     * time. If it no longer matches `_nativeHistoryNavigationGeneration` by
+     * the time `shouldApplyRouteChange` resolves, a newer navigation has
+     * superseded this one and this check's result is discarded.
+     * @param reapplyCurrentRoute Called once the navigation is approved, so
+     * `UIRoute.currentRoute`'s new value actually takes effect on screen.
+     */
+    static _applyHistoryNavigationToRouteAtPositionIfAllowed(targetRoute: UIRoute, targetHistoryPosition: number, navigationGeneration: number, reapplyCurrentRoute: () => void | Promise<void>): Promise<void>;
     copy(): UIRoute;
     routeByRemovingComponentsOtherThanOnesNamed(componentNames: string[]): UIRoute;
     routeByRemovingComponentNamed(componentName: string): UIRoute;

package/compiledScripts/UIRoute.js

@@ -16,13 +16,34 @@ var __copyProps = (to, from, except, desc) => {
   return to;
 };
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var __async = (__this, __arguments, generator) => {
+  return new Promise((resolve, reject) => {
+    var fulfilled = (value) => {
+      try {
+        step(generator.next(value));
+      } catch (e) {
+        reject(e);
+      }
+    };
+    var rejected = (value) => {
+      try {
+        step(generator.throw(value));
+      } catch (e) {
+        reject(e);
+      }
+    };
+    var step = (x) => x.done ? resolve(x.value) : Promise.resolve(x.value).then(fulfilled, rejected);
+    step((generator = generator.apply(__this, __arguments)).next());
+  });
+};
 var UIRoute_exports = {};
 __export(UIRoute_exports, {
   UIRoute: () => UIRoute
 });
 module.exports = __toCommonJS(UIRoute_exports);
 var import_UIObject = require("./UIObject");
-class UIRoute extends Array {
+const historyPositionStateKey = "uiRouteHistoryPosition";
+const _UIRoute = class extends Array {
   constructor(hash) {
     super();
     if (!hash || !hash.startsWith) {
@@ -56,35 +77,35 @@ class UIRoute extends Array {
     });
   }
   static get currentRoute() {
-    return new UIRoute(window.location.hash);
+    return new _UIRoute(window.location.hash);
   }
   apply(forcefully = import_UIObject.NO) {
-    return this._applyRouteAfterRouteApplicationCheck(forcefully, import_UIObject.NO);
+    return this._applyRouteAfterRouteChangeApproval(forcefully, import_UIObject.NO);
   }
-  applyWithoutRouteApplicationCheck(forcefully = import_UIObject.NO) {
-    return this._applyRouteWithoutRouteApplicationCheck(forcefully, import_UIObject.NO);
+  applyWithoutRouteChangeApproval(forcefully = import_UIObject.NO) {
+    return this._applyRouteWithoutRouteChangeApproval(forcefully, import_UIObject.NO);
   }
   applyByReplacingCurrentRouteInHistory(forcefully = import_UIObject.NO) {
-    return this._applyRouteAfterRouteApplicationCheck(forcefully, import_UIObject.YES);
+    return this._applyRouteAfterRouteChangeApproval(forcefully, import_UIObject.YES);
   }
-  applyByReplacingCurrentRouteInHistoryWithoutRouteApplicationCheck(forcefully = import_UIObject.NO) {
-    return this._applyRouteWithoutRouteApplicationCheck(forcefully, import_UIObject.YES);
+  applyByReplacingCurrentRouteInHistoryWithoutRouteChangeApproval(forcefully = import_UIObject.NO) {
+    return this._applyRouteWithoutRouteChangeApproval(forcefully, import_UIObject.YES);
   }
-  _applyRouteAfterRouteApplicationCheck(forcefully, replacesCurrentRouteInHistory) {
-    if (!this._needsRouteApplication(forcefully)) {
+  _applyRouteAfterRouteChangeApproval(forcefully, replacesCurrentRouteInHistory) {
+    if (!this._needsRouteChange(forcefully)) {
       return import_UIObject.NO;
     }
-    const routeApplicationShouldProceed = UIRoute.shouldApplyRouteChange;
-    if (!routeApplicationShouldProceed) {
-      return this._applyRouteWithoutRouteApplicationCheck(forcefully, replacesCurrentRouteInHistory);
+    const shouldApplyRouteChange = _UIRoute.shouldApplyRouteChange;
+    if (!shouldApplyRouteChange) {
+      return this._applyRouteWithoutRouteChangeApproval(forcefully, replacesCurrentRouteInHistory);
     }
-    const shouldProceed = routeApplicationShouldProceed(
-      this._routeApplication(forcefully, replacesCurrentRouteInHistory)
+    const shouldProceed = shouldApplyRouteChange(
+      this._routeChangeDescriptor(forcefully, replacesCurrentRouteInHistory)
     );
     if (shouldProceed instanceof Promise) {
-      return shouldProceed.then((routeApplicationShouldProceed2) => {
+      return shouldProceed.then((isRouteChangeApproved) => {
         return this._applyRouteIfAllowed(
-          routeApplicationShouldProceed2,
+          isRouteChangeApproved,
           forcefully,
           replacesCurrentRouteInHistory
         );
@@ -92,16 +113,17 @@ class UIRoute extends Array {
     }
     return this._applyRouteIfAllowed(shouldProceed, forcefully, replacesCurrentRouteInHistory);
   }
-  _applyRouteIfAllowed(routeApplicationShouldProceed, forcefully, replacesCurrentRouteInHistory) {
-    if (!routeApplicationShouldProceed) {
+  _applyRouteIfAllowed(isRouteChangeApproved, forcefully, replacesCurrentRouteInHistory) {
+    if (!isRouteChangeApproved) {
       return import_UIObject.NO;
     }
-    return this._applyRouteWithoutRouteApplicationCheck(forcefully, replacesCurrentRouteInHistory);
+    return this._applyRouteWithoutRouteChangeApproval(forcefully, replacesCurrentRouteInHistory);
   }
-  _applyRouteWithoutRouteApplicationCheck(forcefully, replacesCurrentRouteInHistory) {
-    if (!this._needsRouteApplication(forcefully)) {
+  _applyRouteWithoutRouteChangeApproval(forcefully, replacesCurrentRouteInHistory) {
+    if (!this._needsRouteChange(forcefully)) {
       return import_UIObject.NO;
     }
+    _UIRoute._selfInitiatedRouteChange = this._routeChangeDescriptor(forcefully, replacesCurrentRouteInHistory);
     if (replacesCurrentRouteInHistory) {
       window.location.replace(this.linkRepresentation);
     } else {
@@ -109,22 +131,111 @@ class UIRoute extends Array {
     }
     return import_UIObject.YES;
   }
-  _needsRouteApplication(forcefully) {
-    if (!forcefully && new UIRoute(window.location.hash).stringRepresentation == this.stringRepresentation) {
+  _needsRouteChange(forcefully) {
+    if (!forcefully && new _UIRoute(window.location.hash).stringRepresentation == this.stringRepresentation) {
       return import_UIObject.NO;
     }
     return import_UIObject.YES;
   }
-  _routeApplication(forcefully, replacesCurrentRouteInHistory) {
+  _routeChangeDescriptor(forcefully, replacesCurrentRouteInHistory) {
     return {
-      currentRoute: UIRoute.currentRoute,
+      currentRoute: _UIRoute.currentRoute,
       targetRoute: this.copy(),
       forcefully,
       replacesCurrentRouteInHistory
     };
   }
+  static _installNativeHistoryNavigationGuard(reapplyCurrentRoute) {
+    var _a;
+    _UIRoute._recordPresentedRouteAtHistoryPosition(
+      _UIRoute.currentRoute,
+      (_a = _UIRoute._historyPositionFromCurrentEntry()) != null ? _a : 0
+    );
+    window.addEventListener(
+      "hashchange",
+      (event) => _UIRoute._hashDidChange(event, reapplyCurrentRoute)
+    );
+  }
+  static _historyPositionFromCurrentEntry() {
+    var _a;
+    const historyPosition = (_a = window.history.state) == null ? void 0 : _a[historyPositionStateKey];
+    if (typeof historyPosition !== "number") {
+      return void 0;
+    }
+    return historyPosition;
+  }
+  static _recordPresentedRouteAtHistoryPosition(route, historyPosition) {
+    const historyState = Object.assign({}, window.history.state);
+    historyState[historyPositionStateKey] = historyPosition;
+    window.history.replaceState(historyState, "");
+    _UIRoute._presentedRoute = route.copy();
+    _UIRoute._presentedHistoryPosition = historyPosition;
+    _UIRoute._recordedHistoryLength = window.history.length;
+  }
+  static _hashDidChange(event, reapplyCurrentRoute) {
+    const targetRoute = _UIRoute.currentRoute;
+    const selfInitiatedRouteChange = _UIRoute._selfInitiatedRouteChange;
+    _UIRoute._selfInitiatedRouteChange = void 0;
+    if (selfInitiatedRouteChange && selfInitiatedRouteChange.targetRoute.stringRepresentation === targetRoute.stringRepresentation) {
+      let targetHistoryPosition2 = _UIRoute._presentedHistoryPosition;
+      if (!selfInitiatedRouteChange.replacesCurrentRouteInHistory) {
+        targetHistoryPosition2 = targetHistoryPosition2 + 1;
+      }
+      _UIRoute._recordPresentedRouteAtHistoryPosition(targetRoute, targetHistoryPosition2);
+      return;
+    }
+    const targetHistoryPosition = _UIRoute._historyPositionFromCurrentEntry();
+    if (targetHistoryPosition === void 0) {
+      let untaggedHistoryPosition = _UIRoute._presentedHistoryPosition;
+      if (window.history.length > _UIRoute._recordedHistoryLength) {
+        untaggedHistoryPosition = untaggedHistoryPosition + 1;
+      }
+      _UIRoute._recordPresentedRouteAtHistoryPosition(targetRoute, untaggedHistoryPosition);
+      return;
+    }
+    if (targetHistoryPosition === _UIRoute._presentedHistoryPosition) {
+      _UIRoute._recordPresentedRouteAtHistoryPosition(targetRoute, targetHistoryPosition);
+      return;
+    }
+    event.stopImmediatePropagation();
+    const navigationGeneration = ++_UIRoute._nativeHistoryNavigationGeneration;
+    _UIRoute._applyHistoryNavigationToRouteAtPositionIfAllowed(
+      targetRoute,
+      targetHistoryPosition,
+      navigationGeneration,
+      reapplyCurrentRoute
+    ).catch((error) => {
+      console.error("UIRoute: native history navigation check failed", error);
+    });
+  }
+  static _applyHistoryNavigationToRouteAtPositionIfAllowed(targetRoute, targetHistoryPosition, navigationGeneration, reapplyCurrentRoute) {
+    return __async(this, null, function* () {
+      const shouldApplyRouteChange = _UIRoute.shouldApplyRouteChange;
+      const isRouteChangeApproved = shouldApplyRouteChange ? yield shouldApplyRouteChange({
+        currentRoute: _UIRoute._presentedRoute.copy(),
+        targetRoute: targetRoute.copy(),
+        forcefully: import_UIObject.NO,
+        replacesCurrentRouteInHistory: import_UIObject.NO
+      }) : import_UIObject.YES;
+      if (navigationGeneration !== _UIRoute._nativeHistoryNavigationGeneration) {
+        return;
+      }
+      if (_UIRoute.currentRoute.stringRepresentation !== targetRoute.stringRepresentation || _UIRoute._historyPositionFromCurrentEntry() !== targetHistoryPosition) {
+        return;
+      }
+      if (isRouteChangeApproved) {
+        _UIRoute._recordPresentedRouteAtHistoryPosition(targetRoute, targetHistoryPosition);
+        yield reapplyCurrentRoute();
+        return;
+      }
+      const historyDelta = _UIRoute._presentedHistoryPosition - targetHistoryPosition;
+      if (historyDelta !== 0) {
+        window.history.go(historyDelta);
+      }
+    });
+  }
   copy() {
-    const result = new UIRoute(this.stringRepresentation);
+    const result = new _UIRoute(this.stringRepresentation);
     return result;
   }
   routeByRemovingComponentsOtherThanOnesNamed(componentNames) {
@@ -232,7 +343,12 @@ class UIRoute extends Array {
     });
     return result;
   }
-}
+};
+let UIRoute = _UIRoute;
+UIRoute._presentedRoute = new _UIRoute();
+UIRoute._presentedHistoryPosition = 0;
+UIRoute._recordedHistoryLength = 0;
+UIRoute._nativeHistoryNavigationGeneration = 0;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   UIRoute

package/compiledScripts/UIRoute.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../scripts/UIRoute.ts"],
-  "sourcesContent": ["import { IS_NIL, IS_NOT, NO, ValueOf, YES } from \"./UIObject\"\nimport { UIViewController } from \"./UIViewController\"\n\n\nexport type PropType<TObj, TProp extends keyof TObj> = TObj[TProp];\n\nexport type UIRouteParameters<T = any> = {\n    \n    [key: string]: string;\n    \n} | T;\n\n\nexport interface UIRouteComponent<T = any> {\n    \n    name: string;\n    parameters: UIRouteParameters<T>;\n    \n}\n\n\nexport interface UIRouteChangeDescriptor {\n    \n    currentRoute: UIRoute;\n    targetRoute: UIRoute;\n    forcefully: boolean;\n    replacesCurrentRouteInHistory: boolean;\n    \n}\n\n\nexport type UIRouteShouldApplyRouteChangeCallbackFunction = (\n    routeChangeDescriptor: UIRouteChangeDescriptor\n) => boolean | Promise<boolean>;\n\n\nexport class UIRoute extends Array<UIRouteComponent> {\n    \n    static shouldApplyRouteChange?: UIRouteShouldApplyRouteChangeCallbackFunction\n    \n    constructor(hash?: string) {\n        \n        super()\n        \n        if (!hash || !hash.startsWith) {\n            \n            return\n            \n        }\n        \n        if (hash.startsWith(\"#\")) {\n            hash = hash.slice(1)\n        }\n        \n        hash = decodeURIComponent(hash)\n        \n        const components = hash.split(\"]\")\n        components.forEach(component => {\n            \n            const componentName = component.split(\"[\")[0]\n            const parameters: Record<string, string> = {}\n            \n            if (!componentName) {\n                return\n            }\n            \n            const parametersString = component.split(\"[\")[1] || \"\"\n            const parameterPairStrings = parametersString.split(\",\") || []\n            \n            parameterPairStrings.forEach(pairString => {\n                \n                const keyAndValueArray = pairString.split(\":\")\n                const key = decodeURIComponent(keyAndValueArray[0])\n                const value = decodeURIComponent(keyAndValueArray[1])\n                \n                if (key) {\n                    parameters[key] = value\n                }\n                \n            })\n            \n            \n            this.push({\n                name: componentName,\n                parameters: parameters\n            })\n            \n        })\n        \n        \n    }\n    \n    \n    static get currentRoute() {\n        \n        return new UIRoute(window.location.hash)\n        \n    }\n    \n    \n    /**\n     * @param forcefully When `true`, applies the route even if its string\n     * representation is identical to the current URL hash, causing the browser\n     * to fire a `hashchange` event and re-run the full `handleRoute` flow.\n     * Use this only when you explicitly need re-entrant navigation (e.g. the\n     * \"tap the already-active tab to reset to root\" feature in TopBarView).\n     * Defaults to `false`.\n     */\n    apply(forcefully = NO): boolean | Promise<boolean> {\n        \n        return this._applyRouteAfterRouteApplicationCheck(forcefully, NO)\n        \n    }\n    \n    \n    /**\n     * Applies this route without consulting `UIRoute.routeApplicationShouldProceed`.\n     * Use this only for route changes that are internal bookkeeping or that already\n     * passed a higher-level confirmation flow.\n     */\n    applyWithoutRouteApplicationCheck(forcefully = NO): boolean {\n        \n        return this._applyRouteWithoutRouteApplicationCheck(forcefully, NO)\n        \n    }\n    \n    \n    /**\n     * @param forcefully When `true`, replaces the current history entry with\n     * this route even when the route is identical to the current URL hash.\n     * Defaults to `false`.\n     */\n    applyByReplacingCurrentRouteInHistory(forcefully = NO): boolean | Promise<boolean> {\n        \n        return this._applyRouteAfterRouteApplicationCheck(forcefully, YES)\n        \n    }\n    \n    \n    /**\n     * Replaces the current history entry without consulting\n     * `UIRoute.routeApplicationShouldProceed`.\n     */\n    applyByReplacingCurrentRouteInHistoryWithoutRouteApplicationCheck(forcefully = NO): boolean {\n        \n        return this._applyRouteWithoutRouteApplicationCheck(forcefully, YES)\n        \n    }\n    \n    \n    _applyRouteAfterRouteApplicationCheck(\n        forcefully: boolean,\n        replacesCurrentRouteInHistory: boolean\n    ): boolean | Promise<boolean> {\n        \n        if (!this._needsRouteApplication(forcefully)) {\n            return NO\n        }\n        \n        const routeApplicationShouldProceed = UIRoute.shouldApplyRouteChange\n        if (!routeApplicationShouldProceed) {\n            return this._applyRouteWithoutRouteApplicationCheck(forcefully, replacesCurrentRouteInHistory)\n        }\n        \n        const shouldProceed = routeApplicationShouldProceed(\n            this._routeApplication(forcefully, replacesCurrentRouteInHistory)\n        )\n        \n        if (shouldProceed instanceof Promise) {\n            return shouldProceed.then(routeApplicationShouldProceed => {\n                return this._applyRouteIfAllowed(\n                    routeApplicationShouldProceed,\n                    forcefully,\n                    replacesCurrentRouteInHistory\n                )\n            })\n        }\n        \n        return this._applyRouteIfAllowed(shouldProceed, forcefully, replacesCurrentRouteInHistory)\n        \n    }\n    \n    \n    _applyRouteIfAllowed(\n        routeApplicationShouldProceed: boolean,\n        forcefully: boolean,\n        replacesCurrentRouteInHistory: boolean\n    ): boolean {\n        \n        if (!routeApplicationShouldProceed) {\n            return NO\n        }\n        \n        return this._applyRouteWithoutRouteApplicationCheck(forcefully, replacesCurrentRouteInHistory)\n        \n    }\n    \n    \n    _applyRouteWithoutRouteApplicationCheck(\n        forcefully: boolean,\n        replacesCurrentRouteInHistory: boolean\n    ): boolean {\n        \n        if (!this._needsRouteApplication(forcefully)) {\n            return NO\n        }\n        \n        if (replacesCurrentRouteInHistory) {\n            window.location.replace(this.linkRepresentation)\n        }\n        else {\n            window.location.hash = this.stringRepresentation\n        }\n        \n        return YES\n        \n    }\n    \n    \n    _needsRouteApplication(forcefully: boolean): boolean {\n        \n        if (!forcefully && new UIRoute(window.location.hash).stringRepresentation == this.stringRepresentation) {\n            return NO\n        }\n        \n        return YES\n        \n    }\n    \n    \n    _routeApplication(forcefully: boolean, replacesCurrentRouteInHistory: boolean): UIRouteChangeDescriptor {\n        \n        return {\n            currentRoute: UIRoute.currentRoute,\n            targetRoute: this.copy(),\n            forcefully: forcefully,\n            replacesCurrentRouteInHistory: replacesCurrentRouteInHistory\n        }\n        \n    }\n    \n    \n    override copy() {\n        const result = new UIRoute(this.stringRepresentation)\n        return result\n    }\n    \n    \n    routeByRemovingComponentsOtherThanOnesNamed(componentNames: string[]) {\n        const result = this.copy()\n        const indexesToRemove: number[] = []\n        result.forEach(function (component, index, array) {\n            if (!componentNames.contains(component.name)) {\n                indexesToRemove.push(index)\n            }\n        })\n        indexesToRemove.forEach(function (indexToRemove, index, array) {\n            result.removeElementAtIndex(indexToRemove)\n        })\n        return result\n    }\n    \n    \n    routeByRemovingComponentNamed(componentName: string) {\n        const result = this.copy()\n        const componentIndex = result.findIndex(function (component, index) {\n            return (component.name == componentName)\n        })\n        if (componentIndex != -1) {\n            result.splice(componentIndex, 1)\n        }\n        return result\n    }\n    \n    \n    routeByRemovingParameterInComponent(componentName: string, parameterName: string, removeComponentIfEmpty = NO) {\n        let result = this.copy()\n        let parameters = result.componentWithName(componentName)?.parameters ?? {}\n        delete parameters[parameterName]\n        result = result.routeWithComponent(componentName, parameters)\n        if (removeComponentIfEmpty && Object.keys(parameters).length == 0) {\n            result = result.routeByRemovingComponentNamed(componentName)\n        }\n        return result\n    }\n    \n    routeBySettingParameterInComponent(componentName: string, parameterName: string, valueToSet: string) {\n        let result = this.copy()\n        if (IS_NIL(valueToSet) || IS_NIL(parameterName)) {\n            return result\n        }\n        let parameters = result.componentWithName(componentName)?.parameters\n        if (IS_NOT(parameters)) {\n            parameters = {}\n        }\n        parameters[parameterName] = valueToSet\n        result = result.routeWithComponent(componentName, parameters)\n        return result\n    }\n    \n    \n    routeWithViewControllerComponent<T extends typeof UIViewController>(\n        viewController: T,\n        parameters: UIRouteParameters<{ [P in keyof T[\"ParameterIdentifierName\"]]: string }>,\n        extendParameters: boolean = NO\n    ) {\n        \n        return this.routeWithComponent(viewController.routeComponentName, parameters, extendParameters)\n        \n    }\n    \n    routeWithComponent(name: string, parameters: UIRouteParameters, extendParameters: boolean = NO) {\n        \n        const result = this.copy()\n        let component = result.componentWithName(name)\n        if (IS_NOT(component)) {\n            component = {\n                name: name,\n                parameters: {}\n            }\n            result.push(component)\n        }\n        \n        if (IS_NOT(parameters)) {\n            \n            parameters = {}\n            \n        }\n        \n        if (extendParameters) {\n            component.parameters = Object.assign(component.parameters, parameters)\n        }\n        else {\n            component.parameters = parameters\n        }\n        \n        return result\n        \n    }\n    \n    navigateBySettingComponent(name: string, parameters: UIRouteParameters, extendParameters: boolean = NO) {\n        \n        return this.routeWithComponent(name, parameters, extendParameters).apply()\n        \n    }\n    \n    \n    componentWithViewController<T extends typeof UIViewController>(viewController: T): UIRouteComponent<{ [P in ValueOf<T[\"ParameterIdentifierName\"]>]: string }> | undefined {\n        \n        return this.componentWithName(viewController.routeComponentName)\n        \n    }\n    \n    componentWithName(name: string): UIRouteComponent | undefined {\n        let result\n        this.forEach(function (component, index, self) {\n            if (component.name == name) {\n                result = component\n            }\n        })\n        return result\n    }\n    \n    \n    get linkRepresentation() {\n        return \"#\" + this.stringRepresentation\n    }\n    \n    \n    get stringRepresentation() {\n        \n        let result = \"\"\n        this.forEach(function (component, index, self) {\n            result = result + component.name\n            const parameters = component.parameters\n            result = result + \"[\"\n            Object.keys(parameters).forEach(function (key, index, keys) {\n                if (index) {\n                    result = result + \",\"\n                }\n                result = result + encodeURIComponent(key) + \":\" + encodeURIComponent(parameters[key])\n            })\n            result = result + \"]\"\n        })\n        \n        return result\n        \n    }\n    \n    \n}\n"],
-  "mappings": "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",
-  "names": ["routeApplicationShouldProceed", "index"]
+  "sourcesContent": ["import { IS_NIL, IS_NOT, NO, ValueOf, YES } from \"./UIObject\"\nimport { UIViewController } from \"./UIViewController\"\n\n\nexport type PropType<TObj, TProp extends keyof TObj> = TObj[TProp];\n\nexport type UIRouteParameters<T = any> = {\n    \n    [key: string]: string;\n    \n} | T;\n\n\nexport interface UIRouteComponent<T = any> {\n    \n    name: string;\n    parameters: UIRouteParameters<T>;\n    \n}\n\n\nexport interface UIRouteChangeDescriptor {\n    \n    currentRoute: UIRoute;\n    targetRoute: UIRoute;\n    forcefully: boolean;\n    replacesCurrentRouteInHistory: boolean;\n    \n}\n\n\nexport type UIRouteShouldApplyRouteChangeCallbackFunction = (\n    routeChangeDescriptor: UIRouteChangeDescriptor\n) => boolean | Promise<boolean>;\n\n\nconst historyPositionStateKey = \"uiRouteHistoryPosition\"\n\n\nexport class UIRoute extends Array<UIRouteComponent> {\n    \n    static shouldApplyRouteChange?: UIRouteShouldApplyRouteChangeCallbackFunction\n    \n    // Native Back/Forward navigation fires `hashchange` directly, bypassing\n    // `apply()` and therefore `shouldApplyRouteChange` - the fields and\n    // methods below (installed via `_installNativeHistoryNavigationGuard`)\n    // close that gap by tagging every history entry with a running position,\n    // so a native traversal can be told apart from this class's own hash\n    // mutations and, when declined, undone with `history.go(...)`.\n    static _presentedRoute: UIRoute = new UIRoute()\n    static _presentedHistoryPosition = 0\n    static _recordedHistoryLength = 0\n    static _selfInitiatedRouteChange?: UIRouteChangeDescriptor\n    static _nativeHistoryNavigationGeneration = 0\n    \n    constructor(hash?: string) {\n        \n        super()\n        \n        if (!hash || !hash.startsWith) {\n            \n            return\n            \n        }\n        \n        if (hash.startsWith(\"#\")) {\n            hash = hash.slice(1)\n        }\n        \n        hash = decodeURIComponent(hash)\n        \n        const components = hash.split(\"]\")\n        components.forEach(component => {\n            \n            const componentName = component.split(\"[\")[0]\n            const parameters: Record<string, string> = {}\n            \n            if (!componentName) {\n                return\n            }\n            \n            const parametersString = component.split(\"[\")[1] || \"\"\n            const parameterPairStrings = parametersString.split(\",\") || []\n            \n            parameterPairStrings.forEach(pairString => {\n                \n                const keyAndValueArray = pairString.split(\":\")\n                const key = decodeURIComponent(keyAndValueArray[0])\n                const value = decodeURIComponent(keyAndValueArray[1])\n                \n                if (key) {\n                    parameters[key] = value\n                }\n                \n            })\n            \n            \n            this.push({\n                name: componentName,\n                parameters: parameters\n            })\n            \n        })\n        \n        \n    }\n    \n    \n    static get currentRoute() {\n\n        return new UIRoute(window.location.hash)\n\n    }\n\n\n    /**\n     * @param forcefully When `true`, applies the route even if its string\n     * representation is identical to the current URL hash, causing the browser\n     * to fire a `hashchange` event and re-run the full `handleRoute` flow.\n     * Use this only when you explicitly need re-entrant navigation (e.g. the\n     * \"tap the already-active tab to reset to root\" feature in TopBarView).\n     * Defaults to `false`.\n     */\n    apply(forcefully = NO): boolean | Promise<boolean> {\n        \n        return this._applyRouteAfterRouteChangeApproval(forcefully, NO)\n        \n    }\n    \n    \n    /**\n     * Applies this route without consulting `UIRoute.shouldApplyRouteChange`.\n     * Use this only for route changes that are internal bookkeeping or that already\n     * passed a higher-level confirmation flow.\n     */\n    applyWithoutRouteChangeApproval(forcefully = NO): boolean {\n        \n        return this._applyRouteWithoutRouteChangeApproval(forcefully, NO)\n        \n    }\n    \n    \n    /**\n     * @param forcefully When `true`, replaces the current history entry with\n     * this route even when the route is identical to the current URL hash.\n     * Defaults to `false`.\n     */\n    applyByReplacingCurrentRouteInHistory(forcefully = NO): boolean | Promise<boolean> {\n        \n        return this._applyRouteAfterRouteChangeApproval(forcefully, YES)\n        \n    }\n    \n    \n    /**\n     * Replaces the current history entry without consulting\n     * `UIRoute.shouldApplyRouteChange`.\n     */\n    applyByReplacingCurrentRouteInHistoryWithoutRouteChangeApproval(forcefully = NO): boolean {\n        \n        return this._applyRouteWithoutRouteChangeApproval(forcefully, YES)\n        \n    }\n    \n    \n    _applyRouteAfterRouteChangeApproval(\n        forcefully: boolean,\n        replacesCurrentRouteInHistory: boolean\n    ): boolean | Promise<boolean> {\n        \n        if (!this._needsRouteChange(forcefully)) {\n            return NO\n        }\n        \n        const shouldApplyRouteChange = UIRoute.shouldApplyRouteChange\n        if (!shouldApplyRouteChange) {\n            return this._applyRouteWithoutRouteChangeApproval(forcefully, replacesCurrentRouteInHistory)\n        }\n        \n        const shouldProceed = shouldApplyRouteChange(\n            this._routeChangeDescriptor(forcefully, replacesCurrentRouteInHistory)\n        )\n        \n        if (shouldProceed instanceof Promise) {\n            return shouldProceed.then(isRouteChangeApproved => {\n                return this._applyRouteIfAllowed(\n                    isRouteChangeApproved,\n                    forcefully,\n                    replacesCurrentRouteInHistory\n                )\n            })\n        }\n        \n        return this._applyRouteIfAllowed(shouldProceed, forcefully, replacesCurrentRouteInHistory)\n        \n    }\n    \n    \n    _applyRouteIfAllowed(\n        isRouteChangeApproved: boolean,\n        forcefully: boolean,\n        replacesCurrentRouteInHistory: boolean\n    ): boolean {\n        \n        if (!isRouteChangeApproved) {\n            return NO\n        }\n        \n        return this._applyRouteWithoutRouteChangeApproval(forcefully, replacesCurrentRouteInHistory)\n        \n    }\n    \n    \n    _applyRouteWithoutRouteChangeApproval(\n        forcefully: boolean,\n        replacesCurrentRouteInHistory: boolean\n    ): boolean {\n        \n        if (!this._needsRouteChange(forcefully)) {\n            return NO\n        }\n\n        // Tags the hashchange this is about to cause as this class's own\n        // doing, so `_hashDidChange` can tell it apart from a native\n        // Back/Forward traversal instead of falling back to guessing from\n        // `window.history.length`.\n        UIRoute._selfInitiatedRouteChange = this._routeChangeDescriptor(forcefully, replacesCurrentRouteInHistory)\n\n        if (replacesCurrentRouteInHistory) {\n            window.location.replace(this.linkRepresentation)\n        }\n        else {\n            window.location.hash = this.stringRepresentation\n        }\n\n        return YES\n\n    }\n    \n    \n    _needsRouteChange(forcefully: boolean): boolean {\n        \n        if (!forcefully && new UIRoute(window.location.hash).stringRepresentation == this.stringRepresentation) {\n            return NO\n        }\n        \n        return YES\n        \n    }\n    \n    \n    _routeChangeDescriptor(forcefully: boolean, replacesCurrentRouteInHistory: boolean): UIRouteChangeDescriptor {\n        \n        return {\n            currentRoute: UIRoute.currentRoute,\n            targetRoute: this.copy(),\n            forcefully: forcefully,\n            replacesCurrentRouteInHistory: replacesCurrentRouteInHistory\n        }\n\n    }\n\n\n    /**\n     * Installs handling so that native browser Back/Forward navigation\n     * consults `shouldApplyRouteChange` the same way `apply()` does, instead\n     * of silently bypassing it. Call exactly once, from `UICore`'s\n     * constructor.\n     *\n     * @param reapplyCurrentRoute Re-runs route handling for `UIRoute.currentRoute`.\n     * Called once a native navigation is allowed to proceed (or is self-initiated),\n     * so its effect actually appears on screen.\n     */\n    static _installNativeHistoryNavigationGuard(reapplyCurrentRoute: () => void | Promise<void>) {\n\n        UIRoute._recordPresentedRouteAtHistoryPosition(\n            UIRoute.currentRoute,\n            UIRoute._historyPositionFromCurrentEntry() ?? 0\n        )\n\n        window.addEventListener(\"hashchange\", event =>\n            UIRoute._hashDidChange(event, reapplyCurrentRoute)\n        )\n\n    }\n\n\n    static _historyPositionFromCurrentEntry(): number | undefined {\n\n        const historyPosition = (window.history.state as Record<string, unknown> | null)?.[historyPositionStateKey]\n        if (typeof historyPosition !== \"number\") {\n            return undefined\n        }\n        return historyPosition\n\n    }\n\n\n    static _recordPresentedRouteAtHistoryPosition(route: UIRoute, historyPosition: number) {\n\n        const historyState = Object.assign({}, window.history.state)\n        historyState[historyPositionStateKey] = historyPosition\n        window.history.replaceState(historyState, \"\")\n\n        UIRoute._presentedRoute = route.copy()\n        UIRoute._presentedHistoryPosition = historyPosition\n        UIRoute._recordedHistoryLength = window.history.length\n\n    }\n\n\n    /**\n     * The single listener installed for every `hashchange` - self-initiated,\n     * native Back/Forward, or an untagged bypass (see the class-level comment\n     * above `_presentedRoute`) - and the point where those three cases are\n     * told apart.\n     *\n     * @param event The native event. Only used to call\n     * `stopImmediatePropagation()` when a native traversal needs to be held\n     * back pending `shouldApplyRouteChange`, so `UICore`'s own route handling\n     * doesn't run before that check settles.\n     * @param reapplyCurrentRoute Forwarded to `_applyHistoryNavigationToRouteAtPositionIfAllowed`\n     * - see its own doc comment.\n     */\n    static _hashDidChange(event: HashChangeEvent, reapplyCurrentRoute: () => void | Promise<void>) {\n\n        const targetRoute = UIRoute.currentRoute\n        const selfInitiatedRouteChange = UIRoute._selfInitiatedRouteChange\n        UIRoute._selfInitiatedRouteChange = undefined\n\n        if (\n            selfInitiatedRouteChange &&\n            selfInitiatedRouteChange.targetRoute.stringRepresentation === targetRoute.stringRepresentation\n        ) {\n\n            let targetHistoryPosition = UIRoute._presentedHistoryPosition\n            if (!selfInitiatedRouteChange.replacesCurrentRouteInHistory) {\n                targetHistoryPosition = targetHistoryPosition + 1\n            }\n            UIRoute._recordPresentedRouteAtHistoryPosition(targetRoute, targetHistoryPosition)\n            return\n\n        }\n\n        const targetHistoryPosition = UIRoute._historyPositionFromCurrentEntry()\n        if (targetHistoryPosition === undefined) {\n\n            // A hash mutation that bypassed this class entirely (e.g. a\n            // direct `window.location.hash = ...` assignment) produces an\n            // untagged entry. A larger native history length means it was\n            // pushed; an unchanged length means the current entry was\n            // replaced. Preserve both established escape hatches while\n            // bringing the entry into this sequence.\n            let untaggedHistoryPosition = UIRoute._presentedHistoryPosition\n            if (window.history.length > UIRoute._recordedHistoryLength) {\n                untaggedHistoryPosition = untaggedHistoryPosition + 1\n            }\n            UIRoute._recordPresentedRouteAtHistoryPosition(targetRoute, untaggedHistoryPosition)\n            return\n\n        }\n        if (targetHistoryPosition === UIRoute._presentedHistoryPosition) {\n            UIRoute._recordPresentedRouteAtHistoryPosition(targetRoute, targetHistoryPosition)\n            return\n        }\n\n        event.stopImmediatePropagation()\n        const navigationGeneration = ++UIRoute._nativeHistoryNavigationGeneration\n        UIRoute._applyHistoryNavigationToRouteAtPositionIfAllowed(\n            targetRoute,\n            targetHistoryPosition,\n            navigationGeneration,\n            reapplyCurrentRoute\n        ).catch(error => {\n            console.error(\"UIRoute: native history navigation check failed\", error)\n        })\n\n    }\n\n\n    /**\n     * Consults `shouldApplyRouteChange` for a native Back/Forward traversal,\n     * exactly like `apply()` does for a programmatic one, then either lets it\n     * through or reverts it with `history.go(...)`.\n     *\n     * @param targetRoute The route the native traversal is asking to move to.\n     * @param targetHistoryPosition That route's tagged position, used both to\n     * revert (`history.go`) and to detect a newer navigation arriving mid-check.\n     * @param navigationGeneration A token captured by the caller at dispatch\n     * time. If it no longer matches `_nativeHistoryNavigationGeneration` by\n     * the time `shouldApplyRouteChange` resolves, a newer navigation has\n     * superseded this one and this check's result is discarded.\n     * @param reapplyCurrentRoute Called once the navigation is approved, so\n     * `UIRoute.currentRoute`'s new value actually takes effect on screen.\n     */\n    static async _applyHistoryNavigationToRouteAtPositionIfAllowed(\n        targetRoute: UIRoute,\n        targetHistoryPosition: number,\n        navigationGeneration: number,\n        reapplyCurrentRoute: () => void | Promise<void>\n    ) {\n\n        const shouldApplyRouteChange = UIRoute.shouldApplyRouteChange\n        const isRouteChangeApproved = shouldApplyRouteChange\n            ? await shouldApplyRouteChange({\n                currentRoute: UIRoute._presentedRoute.copy(),\n                targetRoute: targetRoute.copy(),\n                forcefully: NO,\n                replacesCurrentRouteInHistory: NO\n            })\n            : YES\n\n        if (navigationGeneration !== UIRoute._nativeHistoryNavigationGeneration) {\n            return\n        }\n        if (\n            UIRoute.currentRoute.stringRepresentation !== targetRoute.stringRepresentation ||\n            UIRoute._historyPositionFromCurrentEntry() !== targetHistoryPosition\n        ) {\n            return\n        }\n\n        if (isRouteChangeApproved) {\n            UIRoute._recordPresentedRouteAtHistoryPosition(targetRoute, targetHistoryPosition)\n            await reapplyCurrentRoute()\n            return\n        }\n\n        const historyDelta = UIRoute._presentedHistoryPosition - targetHistoryPosition\n        if (historyDelta !== 0) {\n            window.history.go(historyDelta)\n        }\n\n    }\n\n\n    override copy() {\n        const result = new UIRoute(this.stringRepresentation)\n        return result\n    }\n    \n    \n    routeByRemovingComponentsOtherThanOnesNamed(componentNames: string[]) {\n        const result = this.copy()\n        const indexesToRemove: number[] = []\n        result.forEach(function (component, index, array) {\n            if (!componentNames.contains(component.name)) {\n                indexesToRemove.push(index)\n            }\n        })\n        indexesToRemove.forEach(function (indexToRemove, index, array) {\n            result.removeElementAtIndex(indexToRemove)\n        })\n        return result\n    }\n    \n    \n    routeByRemovingComponentNamed(componentName: string) {\n        const result = this.copy()\n        const componentIndex = result.findIndex(function (component, index) {\n            return (component.name == componentName)\n        })\n        if (componentIndex != -1) {\n            result.splice(componentIndex, 1)\n        }\n        return result\n    }\n    \n    \n    routeByRemovingParameterInComponent(componentName: string, parameterName: string, removeComponentIfEmpty = NO) {\n        let result = this.copy()\n        let parameters = result.componentWithName(componentName)?.parameters ?? {}\n        delete parameters[parameterName]\n        result = result.routeWithComponent(componentName, parameters)\n        if (removeComponentIfEmpty && Object.keys(parameters).length == 0) {\n            result = result.routeByRemovingComponentNamed(componentName)\n        }\n        return result\n    }\n    \n    routeBySettingParameterInComponent(componentName: string, parameterName: string, valueToSet: string) {\n        let result = this.copy()\n        if (IS_NIL(valueToSet) || IS_NIL(parameterName)) {\n            return result\n        }\n        let parameters = result.componentWithName(componentName)?.parameters\n        if (IS_NOT(parameters)) {\n            parameters = {}\n        }\n        parameters[parameterName] = valueToSet\n        result = result.routeWithComponent(componentName, parameters)\n        return result\n    }\n    \n    \n    routeWithViewControllerComponent<T extends typeof UIViewController>(\n        viewController: T,\n        parameters: UIRouteParameters<{ [P in keyof T[\"ParameterIdentifierName\"]]: string }>,\n        extendParameters: boolean = NO\n    ) {\n        \n        return this.routeWithComponent(viewController.routeComponentName, parameters, extendParameters)\n        \n    }\n    \n    routeWithComponent(name: string, parameters: UIRouteParameters, extendParameters: boolean = NO) {\n        \n        const result = this.copy()\n        let component = result.componentWithName(name)\n        if (IS_NOT(component)) {\n            component = {\n                name: name,\n                parameters: {}\n            }\n            result.push(component)\n        }\n        \n        if (IS_NOT(parameters)) {\n            \n            parameters = {}\n            \n        }\n        \n        if (extendParameters) {\n            component.parameters = Object.assign(component.parameters, parameters)\n        }\n        else {\n            component.parameters = parameters\n        }\n        \n        return result\n        \n    }\n    \n    navigateBySettingComponent(name: string, parameters: UIRouteParameters, extendParameters: boolean = NO) {\n        \n        return this.routeWithComponent(name, parameters, extendParameters).apply()\n        \n    }\n    \n    \n    componentWithViewController<T extends typeof UIViewController>(viewController: T): UIRouteComponent<{ [P in ValueOf<T[\"ParameterIdentifierName\"]>]: string }> | undefined {\n        \n        return this.componentWithName(viewController.routeComponentName)\n        \n    }\n    \n    componentWithName(name: string): UIRouteComponent | undefined {\n        let result\n        this.forEach(function (component, index, self) {\n            if (component.name == name) {\n                result = component\n            }\n        })\n        return result\n    }\n    \n    \n    get linkRepresentation() {\n        return \"#\" + this.stringRepresentation\n    }\n    \n    \n    get stringRepresentation() {\n        \n        let result = \"\"\n        this.forEach(function (component, index, self) {\n            result = result + component.name\n            const parameters = component.parameters\n            result = result + \"[\"\n            Object.keys(parameters).forEach(function (key, index, keys) {\n                if (index) {\n                    result = result + \",\"\n                }\n                result = result + encodeURIComponent(key) + \":\" + encodeURIComponent(parameters[key])\n            })\n            result = result + \"]\"\n        })\n        \n        return result\n        \n    }\n    \n    \n}\n"],
+  "mappings": "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",
+  "names": ["targetHistoryPosition", "index"]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uicore-ts",
-  "version": "1.1.385",
+  "version": "1.1.387",
   "description": "UICore is a library to build native-like user interfaces using pure Typescript. No HTML is needed at all. Components are described as TS classes and all user interactions are handled explicitly. This library is strongly inspired by the UIKit framework that is used in IOS. In addition, UICore has tools to handle URL based routing, array sorting and filtering and adds a number of other utilities for convenience.",
   "main": "compiledScripts/index.js",
   "types": "compiledScripts/index.d.ts",

package/scripts/UICore.ts

@@ -139,17 +139,14 @@ export class UICore extends UIObject {
         
         window.addEventListener("scroll", didScroll, false)
 
-        const hashDidChange = () => {
-
-            //code
-
-            this.reapplyCurrentRoute()
-
-        }
-
-        window.addEventListener("hashchange", hashDidChange, false)
-
-        hashDidChange()
+        // Native Back/Forward navigation fires `hashchange` directly, which
+        // would otherwise reapply the route unconditionally below with no
+        // chance for the app to veto it (e.g. to protect unsaved changes) the
+        // way `UIRoute.apply()` can. This makes native history traversal go
+        // through the same `UIRoute.shouldApplyRouteChange` check first.
+        UIRoute._installNativeHistoryNavigationGuard(() => this.reapplyCurrentRoute())
+
+        this.reapplyCurrentRoute()
 
 
     }

package/scripts/UIRoute.ts

@@ -34,10 +34,25 @@ export type UIRouteShouldApplyRouteChangeCallbackFunction = (
 ) => boolean | Promise<boolean>;
 
 
+const historyPositionStateKey = "uiRouteHistoryPosition"
+
+
 export class UIRoute extends Array<UIRouteComponent> {
     
     static shouldApplyRouteChange?: UIRouteShouldApplyRouteChangeCallbackFunction
     
+    // Native Back/Forward navigation fires `hashchange` directly, bypassing
+    // `apply()` and therefore `shouldApplyRouteChange` - the fields and
+    // methods below (installed via `_installNativeHistoryNavigationGuard`)
+    // close that gap by tagging every history entry with a running position,
+    // so a native traversal can be told apart from this class's own hash
+    // mutations and, when declined, undone with `history.go(...)`.
+    static _presentedRoute: UIRoute = new UIRoute()
+    static _presentedHistoryPosition = 0
+    static _recordedHistoryLength = 0
+    static _selfInitiatedRouteChange?: UIRouteChangeDescriptor
+    static _nativeHistoryNavigationGeneration = 0
+    
     constructor(hash?: string) {
         
         super()
@@ -92,12 +107,12 @@ export class UIRoute extends Array<UIRouteComponent> {
     
     
     static get currentRoute() {
-        
+
         return new UIRoute(window.location.hash)
-        
+
     }
-    
-    
+
+
     /**
      * @param forcefully When `true`, applies the route even if its string
      * representation is identical to the current URL hash, causing the browser
@@ -108,19 +123,19 @@ export class UIRoute extends Array<UIRouteComponent> {
      */
     apply(forcefully = NO): boolean | Promise<boolean> {
         
-        return this._applyRouteAfterRouteApplicationCheck(forcefully, NO)
+        return this._applyRouteAfterRouteChangeApproval(forcefully, NO)
         
     }
     
     
     /**
-     * Applies this route without consulting `UIRoute.routeApplicationShouldProceed`.
+     * Applies this route without consulting `UIRoute.shouldApplyRouteChange`.
      * Use this only for route changes that are internal bookkeeping or that already
      * passed a higher-level confirmation flow.
      */
-    applyWithoutRouteApplicationCheck(forcefully = NO): boolean {
+    applyWithoutRouteChangeApproval(forcefully = NO): boolean {
         
-        return this._applyRouteWithoutRouteApplicationCheck(forcefully, NO)
+        return this._applyRouteWithoutRouteChangeApproval(forcefully, NO)
         
     }
     
@@ -132,44 +147,44 @@ export class UIRoute extends Array<UIRouteComponent> {
      */
     applyByReplacingCurrentRouteInHistory(forcefully = NO): boolean | Promise<boolean> {
         
-        return this._applyRouteAfterRouteApplicationCheck(forcefully, YES)
+        return this._applyRouteAfterRouteChangeApproval(forcefully, YES)
         
     }
     
     
     /**
      * Replaces the current history entry without consulting
-     * `UIRoute.routeApplicationShouldProceed`.
+     * `UIRoute.shouldApplyRouteChange`.
      */
-    applyByReplacingCurrentRouteInHistoryWithoutRouteApplicationCheck(forcefully = NO): boolean {
+    applyByReplacingCurrentRouteInHistoryWithoutRouteChangeApproval(forcefully = NO): boolean {
         
-        return this._applyRouteWithoutRouteApplicationCheck(forcefully, YES)
+        return this._applyRouteWithoutRouteChangeApproval(forcefully, YES)
         
     }
     
     
-    _applyRouteAfterRouteApplicationCheck(
+    _applyRouteAfterRouteChangeApproval(
         forcefully: boolean,
         replacesCurrentRouteInHistory: boolean
     ): boolean | Promise<boolean> {
         
-        if (!this._needsRouteApplication(forcefully)) {
+        if (!this._needsRouteChange(forcefully)) {
             return NO
         }
         
-        const routeApplicationShouldProceed = UIRoute.shouldApplyRouteChange
-        if (!routeApplicationShouldProceed) {
-            return this._applyRouteWithoutRouteApplicationCheck(forcefully, replacesCurrentRouteInHistory)
+        const shouldApplyRouteChange = UIRoute.shouldApplyRouteChange
+        if (!shouldApplyRouteChange) {
+            return this._applyRouteWithoutRouteChangeApproval(forcefully, replacesCurrentRouteInHistory)
         }
         
-        const shouldProceed = routeApplicationShouldProceed(
-            this._routeApplication(forcefully, replacesCurrentRouteInHistory)
+        const shouldProceed = shouldApplyRouteChange(
+            this._routeChangeDescriptor(forcefully, replacesCurrentRouteInHistory)
         )
         
         if (shouldProceed instanceof Promise) {
-            return shouldProceed.then(routeApplicationShouldProceed => {
+            return shouldProceed.then(isRouteChangeApproved => {
                 return this._applyRouteIfAllowed(
-                    routeApplicationShouldProceed,
+                    isRouteChangeApproved,
                     forcefully,
                     replacesCurrentRouteInHistory
                 )
@@ -182,42 +197,48 @@ export class UIRoute extends Array<UIRouteComponent> {
     
     
     _applyRouteIfAllowed(
-        routeApplicationShouldProceed: boolean,
+        isRouteChangeApproved: boolean,
         forcefully: boolean,
         replacesCurrentRouteInHistory: boolean
     ): boolean {
         
-        if (!routeApplicationShouldProceed) {
+        if (!isRouteChangeApproved) {
             return NO
         }
         
-        return this._applyRouteWithoutRouteApplicationCheck(forcefully, replacesCurrentRouteInHistory)
+        return this._applyRouteWithoutRouteChangeApproval(forcefully, replacesCurrentRouteInHistory)
         
     }
     
     
-    _applyRouteWithoutRouteApplicationCheck(
+    _applyRouteWithoutRouteChangeApproval(
         forcefully: boolean,
         replacesCurrentRouteInHistory: boolean
     ): boolean {
         
-        if (!this._needsRouteApplication(forcefully)) {
+        if (!this._needsRouteChange(forcefully)) {
             return NO
         }
-        
+
+        // Tags the hashchange this is about to cause as this class's own
+        // doing, so `_hashDidChange` can tell it apart from a native
+        // Back/Forward traversal instead of falling back to guessing from
+        // `window.history.length`.
+        UIRoute._selfInitiatedRouteChange = this._routeChangeDescriptor(forcefully, replacesCurrentRouteInHistory)
+
         if (replacesCurrentRouteInHistory) {
             window.location.replace(this.linkRepresentation)
         }
         else {
             window.location.hash = this.stringRepresentation
         }
-        
+
         return YES
-        
+
     }
     
     
-    _needsRouteApplication(forcefully: boolean): boolean {
+    _needsRouteChange(forcefully: boolean): boolean {
         
         if (!forcefully && new UIRoute(window.location.hash).stringRepresentation == this.stringRepresentation) {
             return NO
@@ -228,7 +249,7 @@ export class UIRoute extends Array<UIRouteComponent> {
     }
     
     
-    _routeApplication(forcefully: boolean, replacesCurrentRouteInHistory: boolean): UIRouteChangeDescriptor {
+    _routeChangeDescriptor(forcefully: boolean, replacesCurrentRouteInHistory: boolean): UIRouteChangeDescriptor {
         
         return {
             currentRoute: UIRoute.currentRoute,
@@ -236,10 +257,183 @@ export class UIRoute extends Array<UIRouteComponent> {
             forcefully: forcefully,
             replacesCurrentRouteInHistory: replacesCurrentRouteInHistory
         }
-        
+
     }
-    
-    
+
+
+    /**
+     * Installs handling so that native browser Back/Forward navigation
+     * consults `shouldApplyRouteChange` the same way `apply()` does, instead
+     * of silently bypassing it. Call exactly once, from `UICore`'s
+     * constructor.
+     *
+     * @param reapplyCurrentRoute Re-runs route handling for `UIRoute.currentRoute`.
+     * Called once a native navigation is allowed to proceed (or is self-initiated),
+     * so its effect actually appears on screen.
+     */
+    static _installNativeHistoryNavigationGuard(reapplyCurrentRoute: () => void | Promise<void>) {
+
+        UIRoute._recordPresentedRouteAtHistoryPosition(
+            UIRoute.currentRoute,
+            UIRoute._historyPositionFromCurrentEntry() ?? 0
+        )
+
+        window.addEventListener("hashchange", event =>
+            UIRoute._hashDidChange(event, reapplyCurrentRoute)
+        )
+
+    }
+
+
+    static _historyPositionFromCurrentEntry(): number | undefined {
+
+        const historyPosition = (window.history.state as Record<string, unknown> | null)?.[historyPositionStateKey]
+        if (typeof historyPosition !== "number") {
+            return undefined
+        }
+        return historyPosition
+
+    }
+
+
+    static _recordPresentedRouteAtHistoryPosition(route: UIRoute, historyPosition: number) {
+
+        const historyState = Object.assign({}, window.history.state)
+        historyState[historyPositionStateKey] = historyPosition
+        window.history.replaceState(historyState, "")
+
+        UIRoute._presentedRoute = route.copy()
+        UIRoute._presentedHistoryPosition = historyPosition
+        UIRoute._recordedHistoryLength = window.history.length
+
+    }
+
+
+    /**
+     * The single listener installed for every `hashchange` - self-initiated,
+     * native Back/Forward, or an untagged bypass (see the class-level comment
+     * above `_presentedRoute`) - and the point where those three cases are
+     * told apart.
+     *
+     * @param event The native event. Only used to call
+     * `stopImmediatePropagation()` when a native traversal needs to be held
+     * back pending `shouldApplyRouteChange`, so `UICore`'s own route handling
+     * doesn't run before that check settles.
+     * @param reapplyCurrentRoute Forwarded to `_applyHistoryNavigationToRouteAtPositionIfAllowed`
+     * - see its own doc comment.
+     */
+    static _hashDidChange(event: HashChangeEvent, reapplyCurrentRoute: () => void | Promise<void>) {
+
+        const targetRoute = UIRoute.currentRoute
+        const selfInitiatedRouteChange = UIRoute._selfInitiatedRouteChange
+        UIRoute._selfInitiatedRouteChange = undefined
+
+        if (
+            selfInitiatedRouteChange &&
+            selfInitiatedRouteChange.targetRoute.stringRepresentation === targetRoute.stringRepresentation
+        ) {
+
+            let targetHistoryPosition = UIRoute._presentedHistoryPosition
+            if (!selfInitiatedRouteChange.replacesCurrentRouteInHistory) {
+                targetHistoryPosition = targetHistoryPosition + 1
+            }
+            UIRoute._recordPresentedRouteAtHistoryPosition(targetRoute, targetHistoryPosition)
+            return
+
+        }
+
+        const targetHistoryPosition = UIRoute._historyPositionFromCurrentEntry()
+        if (targetHistoryPosition === undefined) {
+
+            // A hash mutation that bypassed this class entirely (e.g. a
+            // direct `window.location.hash = ...` assignment) produces an
+            // untagged entry. A larger native history length means it was
+            // pushed; an unchanged length means the current entry was
+            // replaced. Preserve both established escape hatches while
+            // bringing the entry into this sequence.
+            let untaggedHistoryPosition = UIRoute._presentedHistoryPosition
+            if (window.history.length > UIRoute._recordedHistoryLength) {
+                untaggedHistoryPosition = untaggedHistoryPosition + 1
+            }
+            UIRoute._recordPresentedRouteAtHistoryPosition(targetRoute, untaggedHistoryPosition)
+            return
+
+        }
+        if (targetHistoryPosition === UIRoute._presentedHistoryPosition) {
+            UIRoute._recordPresentedRouteAtHistoryPosition(targetRoute, targetHistoryPosition)
+            return
+        }
+
+        event.stopImmediatePropagation()
+        const navigationGeneration = ++UIRoute._nativeHistoryNavigationGeneration
+        UIRoute._applyHistoryNavigationToRouteAtPositionIfAllowed(
+            targetRoute,
+            targetHistoryPosition,
+            navigationGeneration,
+            reapplyCurrentRoute
+        ).catch(error => {
+            console.error("UIRoute: native history navigation check failed", error)
+        })
+
+    }
+
+
+    /**
+     * Consults `shouldApplyRouteChange` for a native Back/Forward traversal,
+     * exactly like `apply()` does for a programmatic one, then either lets it
+     * through or reverts it with `history.go(...)`.
+     *
+     * @param targetRoute The route the native traversal is asking to move to.
+     * @param targetHistoryPosition That route's tagged position, used both to
+     * revert (`history.go`) and to detect a newer navigation arriving mid-check.
+     * @param navigationGeneration A token captured by the caller at dispatch
+     * time. If it no longer matches `_nativeHistoryNavigationGeneration` by
+     * the time `shouldApplyRouteChange` resolves, a newer navigation has
+     * superseded this one and this check's result is discarded.
+     * @param reapplyCurrentRoute Called once the navigation is approved, so
+     * `UIRoute.currentRoute`'s new value actually takes effect on screen.
+     */
+    static async _applyHistoryNavigationToRouteAtPositionIfAllowed(
+        targetRoute: UIRoute,
+        targetHistoryPosition: number,
+        navigationGeneration: number,
+        reapplyCurrentRoute: () => void | Promise<void>
+    ) {
+
+        const shouldApplyRouteChange = UIRoute.shouldApplyRouteChange
+        const isRouteChangeApproved = shouldApplyRouteChange
+            ? await shouldApplyRouteChange({
+                currentRoute: UIRoute._presentedRoute.copy(),
+                targetRoute: targetRoute.copy(),
+                forcefully: NO,
+                replacesCurrentRouteInHistory: NO
+            })
+            : YES
+
+        if (navigationGeneration !== UIRoute._nativeHistoryNavigationGeneration) {
+            return
+        }
+        if (
+            UIRoute.currentRoute.stringRepresentation !== targetRoute.stringRepresentation ||
+            UIRoute._historyPositionFromCurrentEntry() !== targetHistoryPosition
+        ) {
+            return
+        }
+
+        if (isRouteChangeApproved) {
+            UIRoute._recordPresentedRouteAtHistoryPosition(targetRoute, targetHistoryPosition)
+            await reapplyCurrentRoute()
+            return
+        }
+
+        const historyDelta = UIRoute._presentedHistoryPosition - targetHistoryPosition
+        if (historyDelta !== 0) {
+            window.history.go(historyDelta)
+        }
+
+    }
+
+
     override copy() {
         const result = new UIRoute(this.stringRepresentation)
         return result