chayns-api 3.1.0-beta.0 → 3.1.0-beta.1

package/dist/cjs/utils/history/BlockRegistry.js

@@ -8,10 +8,11 @@ const BLOCK_TIMEOUT_MS = 30000;
 let _nextId = 1;
 class BlockRegistry {
   layerBlocks = new Map();
+  changeListeners = new Set();
   beforeUnloadCount = 0;
   beforeUnloadHandler = e => {
     e.preventDefault();
-    e.returnValue = '';
+    Reflect.set(e, 'returnValue', '');
   };
   add(layer, callback, opts = {}) {
     var _opts$scope, _opts$isBeforeUnload;
@@ -32,16 +33,19 @@ class BlockRegistry {
     if (entry.opts.isBeforeUnload) {
       this.incrementBeforeUnload();
     }
+    this.notifyChange();
     return () => this.remove(layer.id, entry);
   }
   remove(layerId, entry) {
     const set = this.layerBlocks.get(layerId);
     if (!set) return;
-    set.delete(entry);
+    const didDelete = set.delete(entry);
+    if (!didDelete) return;
     if (set.size === 0) this.layerBlocks.delete(layerId);
     if (entry.opts.isBeforeUnload) {
       this.decrementBeforeUnload();
     }
+    this.notifyChange();
   }
   removeAllForLayer(layerId) {
     const set = this.layerBlocks.get(layerId);
@@ -50,6 +54,13 @@ class BlockRegistry {
       if (entry.opts.isBeforeUnload) this.decrementBeforeUnload();
     }
     this.layerBlocks.delete(layerId);
+    this.notifyChange();
+  }
+  subscribeToChanges(listener) {
+    this.changeListeners.add(listener);
+    return () => {
+      this.changeListeners.delete(listener);
+    };
   }
   collectApplicableBlocks(targetLayer) {
     const result = [];
@@ -62,6 +73,20 @@ class BlockRegistry {
     this.collectGlobalFromActiveDescendants(targetLayer, result);
     return result;
   }
+  hasActiveBlocks(rootLayer) {
+    return this.collectActiveChainBlocks(rootLayer).length > 0;
+  }
+  async checkActiveBlocks(rootLayer) {
+    const blocks = this.collectActiveChainBlocks(rootLayer);
+    if (blocks.length === 0) return true;
+    const results = await Promise.all(blocks.map(b => this.runBlock(b)));
+    return results.every(Boolean);
+  }
+  collectActiveChainBlocks(rootLayer) {
+    const result = [];
+    this.collectFromActiveChain(rootLayer, result);
+    return result;
+  }
   collectGlobalFromActiveDescendants(layer, out) {
     const activeChildId = layer.getActiveChildId();
     if (!activeChildId) return;
@@ -77,6 +102,19 @@ class BlockRegistry {
     }
     this.collectGlobalFromActiveDescendants(child, out);
   }
+  collectFromActiveChain(layer, out) {
+    const set = this.layerBlocks.get(layer.id);
+    if (set) {
+      for (const entry of set) {
+        out.push(entry);
+      }
+    }
+    const activeChildId = layer.getActiveChildId();
+    if (!activeChildId) return;
+    const child = layer.getChildLayer(activeChildId);
+    if (!child) return;
+    this.collectFromActiveChain(child, out);
+  }
   async checkBlocks(targetLayer) {
     const blocks = this.collectApplicableBlocks(targetLayer);
     if (blocks.length === 0) return true;
@@ -89,7 +127,7 @@ class BlockRegistry {
         resolve(false);
       }, BLOCK_TIMEOUT_MS))]);
       return result;
-    } catch (err) {
+    } catch {
       return false;
     }
   }
@@ -106,5 +144,10 @@ class BlockRegistry {
       window.removeEventListener('beforeunload', this.beforeUnloadHandler);
     }
   }
+  notifyChange() {
+    for (const listener of this.changeListeners) {
+      listener();
+    }
+  }
 }
 exports.BlockRegistry = BlockRegistry;

package/dist/cjs/utils/history/NavigationQueue.js

@@ -60,7 +60,6 @@ class NavigationQueue {
         return this.processPopstate(op);
       default:
         {
-          const _exhaustive = op;
           return {
             isOk: false,
             reason: 'error',
@@ -296,7 +295,7 @@ class NavigationQueue {
       changedLayerIds.add(this.deps.getRoot().id);
     }
     const target = this.resolveLowestCommonLayer(changedLayerIds);
-    if (target) {
+    if (target && op.skipBlockCheck !== true) {
       const allowed = await this.deps.checkBlocks(target);
       if (!allowed) {
         await this.deps.silentGo(+1);
@@ -367,6 +366,7 @@ class NavigationQueue {
     return lca;
   }
   commit(isReplace) {
+    var _this$deps$onCommit, _this$deps;
     if (!(0, _window.hasWindowHistory)()) return;
     const url = this.deps.projectUrl();
     const state = this.deps.projectState();
@@ -383,6 +383,7 @@ class NavigationQueue {
     } else {
       window.history.pushState(stateWithMeta, '', url);
     }
+    (_this$deps$onCommit = (_this$deps = this.deps).onCommit) === null || _this$deps$onCommit === void 0 || _this$deps$onCommit.call(_this$deps);
   }
 }
 exports.NavigationQueue = NavigationQueue;

package/dist/cjs/utils/history/nativeBackHandling.js

@@ -0,0 +1,61 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.NativeBackHandler = void 0;
+var _calls = require("../../calls");
+var _IChaynsReact = require("../../types/IChaynsReact");
+var _navigationIndex = require("./navigationIndex");
+var _window = require("./window");
+const DISABLE_SWIPE_BACK_GESTURE_ACTION = 249;
+class NativeBackHandler {
+  bypassNextPopstateBlockCheck = false;
+  constructor(opts) {
+    this.opts = opts;
+  }
+  sync = () => {
+    if (!(0, _window.hasWindowHistory)() || !NativeBackHandler.isSupported()) {
+      return;
+    }
+    const next = this.shouldEnableInterception();
+    if (this.isInterceptionEnabled === next) {
+      return;
+    }
+    void (0, _calls.invokeCall)({
+      action: DISABLE_SWIPE_BACK_GESTURE_ACTION,
+      value: {
+        enabled: next
+      }
+    }, next ? this.handleNativeBack : undefined);
+    this.isInterceptionEnabled = next;
+  };
+  consumeBypassFlag() {
+    if (!this.bypassNextPopstateBlockCheck) return false;
+    this.bypassNextPopstateBlockCheck = false;
+    return true;
+  }
+  static isSupported() {
+    try {
+      var _getDevice$app;
+      return ((_getDevice$app = (0, _calls.getDevice)().app) === null || _getDevice$app === void 0 ? void 0 : _getDevice$app.flavor) === _IChaynsReact.AppFlavor.Chayns;
+    } catch {
+      return false;
+    }
+  }
+  shouldEnableInterception() {
+    return this.opts.blockRegistry.hasActiveBlocks(this.opts.rootLayer) || (0, _navigationIndex.getCurrentIdx)() > 0;
+  }
+  handleNativeBack = () => {
+    void this.runNativeBack();
+  };
+  async runNativeBack() {
+    const isAllowed = await this.opts.blockRegistry.checkActiveBlocks(this.opts.rootLayer);
+    if (!isAllowed || !(0, _window.hasWindowHistory)()) {
+      return;
+    }
+    this.bypassNextPopstateBlockCheck = true;
+    window.history.back();
+  }
+}
+exports.NativeBackHandler = NativeBackHandler;

package/dist/cjs/utils/history/navigationIndex.js

@@ -4,10 +4,14 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.consumeSilent = consumeSilent;
+exports.extractHistoryIndex = extractHistoryIndex;
 exports.getCurrentIdx = getCurrentIdx;
 exports.incrementIdx = incrementIdx;
+exports.setCurrentIdx = setCurrentIdx;
 exports.silentGo = silentGo;
+exports.syncCurrentIdxFromState = syncCurrentIdxFromState;
 var _window = require("./window");
+const CHAYNS_HISTORY_STATE_KEY = '__chaynsHistory';
 let currentIdx = 0;
 let pendingSilentCount = 0;
 let silentResolve = null;
@@ -17,6 +21,34 @@ function incrementIdx() {
 function getCurrentIdx() {
   return currentIdx;
 }
+function setCurrentIdx(idx) {
+  if (!Number.isInteger(idx) || idx < 0) {
+    return;
+  }
+  currentIdx = idx;
+}
+function extractHistoryIndex(raw) {
+  if (!raw || typeof raw !== 'object') {
+    return null;
+  }
+  const chaynsHistory = raw[CHAYNS_HISTORY_STATE_KEY];
+  if (!chaynsHistory || typeof chaynsHistory !== 'object') {
+    return null;
+  }
+  const idx = chaynsHistory.__idx;
+  if (typeof idx !== 'number' || !Number.isInteger(idx) || idx < 0) {
+    return null;
+  }
+  return idx;
+}
+function syncCurrentIdxFromState(raw) {
+  const idx = extractHistoryIndex(raw);
+  if (idx === null) {
+    return null;
+  }
+  currentIdx = idx;
+  return idx;
+}
 function silentGo(delta) {
   if (!(0, _window.hasWindowHistory)()) return Promise.resolve();
   return new Promise(resolve => {

package/dist/cjs/utils/history/rootLayer.js

@@ -17,6 +17,7 @@ var _window = require("./window");
 var _equality = require("../equality");
 var _calls = require("../../calls");
 var _segments = require("./segments");
+var _nativeBackHandling = require("./nativeBackHandling");
 function getInitialPathname(overrideUrl) {
   if (overrideUrl) {
     try {
@@ -48,21 +49,30 @@ function resolveSegmentsFrom(overrideUrl, startIndex) {
 function initRootChaynsHistoryLayer(opts = {}) {
   var _opts$segmentCount;
   const blockRegistry = new _BlockRegistry.BlockRegistry();
-  let rootLayer;
-  let queue;
+  let queueRef = null;
   const deps = {
     getRoot: () => rootLayer,
-    getQueue: () => queue,
+    getQueue: () => {
+      if (!queueRef) {
+        throw new Error('[chaynsHistory] NavigationQueue not initialized yet.');
+      }
+      return queueRef;
+    },
     getBlockRegistry: () => blockRegistry
   };
-  rootLayer = new _HistoryLayer.ChaynsHistoryLayer({
+  const rootLayer = new _HistoryLayer.ChaynsHistoryLayer({
     id: 'root',
     parent: null,
     deps,
     segmentCount: (_opts$segmentCount = opts.segmentCount) !== null && _opts$segmentCount !== void 0 ? _opts$segmentCount : 0,
     segments: opts.segmentCount ? resolveInitialSegments(opts.url, opts.segmentCount) : []
   });
-  queue = new _NavigationQueue.NavigationQueue({
+  const nativeBackHandler = new _nativeBackHandling.NativeBackHandler({
+    rootLayer,
+    blockRegistry
+  });
+  const syncNativeHandling = nativeBackHandler.sync;
+  const queue = new _NavigationQueue.NavigationQueue({
     getRoot: () => rootLayer,
     findLayer: id => (0, _layerTree.findChaynsHistoryLayerById)(rootLayer, id),
     checkBlocks: target => blockRegistry.checkBlocks(target),
@@ -80,6 +90,7 @@ function initRootChaynsHistoryLayer(opts = {}) {
     silentGo: delta => (0, _navigationIndex.silentGo)(delta),
     getCurrentIdx: () => (0, _navigationIndex.getCurrentIdx)(),
     incrementIdx: () => (0, _navigationIndex.incrementIdx)(),
+    onCommit: syncNativeHandling,
     applyUrlSegments: () => {
       if (!(0, _window.hasWindowHistory)()) return {
         changedLayerIds: new Set()
@@ -103,7 +114,9 @@ function initRootChaynsHistoryLayer(opts = {}) {
       };
     }
   });
+  queueRef = queue;
   const existingState = (0, _window.hasWindowHistory)() ? window.history.state : null;
+  (0, _navigationIndex.syncCurrentIdxFromState)(existingState);
   if (!(0, _stateProjector.hasChaynsHistoryState)(existingState)) {
     var _opts$segmentCount2, _opts$url;
     const segmentCount = (_opts$segmentCount2 = opts.segmentCount) !== null && _opts$segmentCount2 !== void 0 ? _opts$segmentCount2 : 0;
@@ -137,7 +150,7 @@ function initRootChaynsHistoryLayer(opts = {}) {
       };
       delete foreign.__chaynsHistory;
       const initialState = (0, _stateProjector.projectToState)(rootLayer, foreign);
-      const idx = (0, _navigationIndex.incrementIdx)();
+      const idx = (0, _navigationIndex.getCurrentIdx)();
       window.history.replaceState({
         ...initialState,
         __chaynsHistory: {
@@ -147,17 +160,42 @@ function initRootChaynsHistoryLayer(opts = {}) {
       }, '', window.location.href);
     } else {
       (0, _stateProjector.applyStateToTree)(rootLayer, existing);
+      if ((0, _navigationIndex.syncCurrentIdxFromState)(existing) === null) {
+        const foreign = {
+          ...(existing !== null && existing !== void 0 ? existing : {})
+        };
+        delete foreign.__chaynsHistory;
+        const currentState = (0, _stateProjector.projectToState)(rootLayer, foreign);
+        const idx = (0, _navigationIndex.getCurrentIdx)();
+        window.history.replaceState({
+          ...currentState,
+          __chaynsHistory: {
+            ...currentState.__chaynsHistory,
+            __idx: idx
+          }
+        }, '', window.location.href);
+      }
     }
+    blockRegistry.subscribeToChanges(syncNativeHandling);
     window.addEventListener('popstate', event => {
-      if ((0, _navigationIndex.consumeSilent)()) return;
+      (0, _navigationIndex.syncCurrentIdxFromState)(event.state);
+      if ((0, _navigationIndex.consumeSilent)()) {
+        syncNativeHandling();
+        return;
+      }
       const raw = event.state;
-      if (!(0, _stateProjector.hasChaynsHistoryState)(raw)) {} else {
+      if (!(0, _stateProjector.hasChaynsHistoryState)(raw)) {
+        syncNativeHandling();
+      } else {
+        const skipBlockCheck = nativeBackHandler.consumeBypassFlag();
         void queue.enqueue({
           kind: 'popstate',
-          rawState: raw
-        });
+          rawState: raw,
+          skipBlockCheck
+        }).finally(syncNativeHandling);
       }
     });
+    syncNativeHandling();
   }
   return {
     rootLayer

package/dist/esm/utils/history/BlockRegistry.js

@@ -6,10 +6,11 @@ let _nextId = 1;
 export class BlockRegistry {
   constructor() {
     _defineProperty(this, "layerBlocks", new Map());
+    _defineProperty(this, "changeListeners", new Set());
     _defineProperty(this, "beforeUnloadCount", 0);
     _defineProperty(this, "beforeUnloadHandler", e => {
       e.preventDefault();
-      e.returnValue = '';
+      Reflect.set(e, 'returnValue', '');
     });
   }
   add(layer, callback, opts = {}) {
@@ -31,16 +32,19 @@ export class BlockRegistry {
     if (entry.opts.isBeforeUnload) {
       this.incrementBeforeUnload();
     }
+    this.notifyChange();
     return () => this.remove(layer.id, entry);
   }
   remove(layerId, entry) {
     const set = this.layerBlocks.get(layerId);
     if (!set) return;
-    set.delete(entry);
+    const didDelete = set.delete(entry);
+    if (!didDelete) return;
     if (set.size === 0) this.layerBlocks.delete(layerId);
     if (entry.opts.isBeforeUnload) {
       this.decrementBeforeUnload();
     }
+    this.notifyChange();
   }
   removeAllForLayer(layerId) {
     const set = this.layerBlocks.get(layerId);
@@ -49,6 +53,13 @@ export class BlockRegistry {
       if (entry.opts.isBeforeUnload) this.decrementBeforeUnload();
     }
     this.layerBlocks.delete(layerId);
+    this.notifyChange();
+  }
+  subscribeToChanges(listener) {
+    this.changeListeners.add(listener);
+    return () => {
+      this.changeListeners.delete(listener);
+    };
   }
   collectApplicableBlocks(targetLayer) {
     const result = [];
@@ -61,6 +72,20 @@ export class BlockRegistry {
     this.collectGlobalFromActiveDescendants(targetLayer, result);
     return result;
   }
+  hasActiveBlocks(rootLayer) {
+    return this.collectActiveChainBlocks(rootLayer).length > 0;
+  }
+  async checkActiveBlocks(rootLayer) {
+    const blocks = this.collectActiveChainBlocks(rootLayer);
+    if (blocks.length === 0) return true;
+    const results = await Promise.all(blocks.map(b => this.runBlock(b)));
+    return results.every(Boolean);
+  }
+  collectActiveChainBlocks(rootLayer) {
+    const result = [];
+    this.collectFromActiveChain(rootLayer, result);
+    return result;
+  }
   collectGlobalFromActiveDescendants(layer, out) {
     const activeChildId = layer.getActiveChildId();
     if (!activeChildId) return;
@@ -76,6 +101,19 @@ export class BlockRegistry {
     }
     this.collectGlobalFromActiveDescendants(child, out);
   }
+  collectFromActiveChain(layer, out) {
+    const set = this.layerBlocks.get(layer.id);
+    if (set) {
+      for (const entry of set) {
+        out.push(entry);
+      }
+    }
+    const activeChildId = layer.getActiveChildId();
+    if (!activeChildId) return;
+    const child = layer.getChildLayer(activeChildId);
+    if (!child) return;
+    this.collectFromActiveChain(child, out);
+  }
   async checkBlocks(targetLayer) {
     const blocks = this.collectApplicableBlocks(targetLayer);
     if (blocks.length === 0) return true;
@@ -88,7 +126,7 @@ export class BlockRegistry {
         resolve(false);
       }, BLOCK_TIMEOUT_MS))]);
       return result;
-    } catch (err) {
+    } catch {
       return false;
     }
   }
@@ -105,4 +143,9 @@ export class BlockRegistry {
       window.removeEventListener('beforeunload', this.beforeUnloadHandler);
     }
   }
+  notifyChange() {
+    for (const listener of this.changeListeners) {
+      listener();
+    }
+  }
 }

package/dist/esm/utils/history/NavigationQueue.js

@@ -58,7 +58,6 @@ export class NavigationQueue {
         return this.processPopstate(op);
       default:
         {
-          const _exhaustive = op;
           return {
             isOk: false,
             reason: 'error',
@@ -294,7 +293,7 @@ export class NavigationQueue {
       changedLayerIds.add(this.deps.getRoot().id);
     }
     const target = this.resolveLowestCommonLayer(changedLayerIds);
-    if (target) {
+    if (target && op.skipBlockCheck !== true) {
       const allowed = await this.deps.checkBlocks(target);
       if (!allowed) {
         await this.deps.silentGo(+1);
@@ -365,6 +364,7 @@ export class NavigationQueue {
     return lca;
   }
   commit(isReplace) {
+    var _this$deps$onCommit, _this$deps;
     if (!hasWindowHistory()) return;
     const url = this.deps.projectUrl();
     const state = this.deps.projectState();
@@ -381,5 +381,6 @@ export class NavigationQueue {
     } else {
       window.history.pushState(stateWithMeta, '', url);
     }
+    (_this$deps$onCommit = (_this$deps = this.deps).onCommit) === null || _this$deps$onCommit === void 0 || _this$deps$onCommit.call(_this$deps);
   }
 }

package/dist/esm/utils/history/nativeBackHandling.js

@@ -0,0 +1,59 @@
+function _defineProperty(e, r, t) { return (r = _toPropertyKey(r)) in e ? Object.defineProperty(e, r, { value: t, enumerable: !0, configurable: !0, writable: !0 }) : e[r] = t, e; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
+function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+import { getDevice, invokeCall } from '../../calls';
+import { AppFlavor } from '../../types/IChaynsReact';
+import { getCurrentIdx } from './navigationIndex';
+import { hasWindowHistory } from './window';
+const DISABLE_SWIPE_BACK_GESTURE_ACTION = 249;
+export class NativeBackHandler {
+  constructor(opts) {
+    _defineProperty(this, "opts", void 0);
+    _defineProperty(this, "isInterceptionEnabled", void 0);
+    _defineProperty(this, "bypassNextPopstateBlockCheck", false);
+    _defineProperty(this, "sync", () => {
+      if (!hasWindowHistory() || !NativeBackHandler.isSupported()) {
+        return;
+      }
+      const next = this.shouldEnableInterception();
+      if (this.isInterceptionEnabled === next) {
+        return;
+      }
+      void invokeCall({
+        action: DISABLE_SWIPE_BACK_GESTURE_ACTION,
+        value: {
+          enabled: next
+        }
+      }, next ? this.handleNativeBack : undefined);
+      this.isInterceptionEnabled = next;
+    });
+    _defineProperty(this, "handleNativeBack", () => {
+      void this.runNativeBack();
+    });
+    this.opts = opts;
+  }
+  consumeBypassFlag() {
+    if (!this.bypassNextPopstateBlockCheck) return false;
+    this.bypassNextPopstateBlockCheck = false;
+    return true;
+  }
+  static isSupported() {
+    try {
+      var _getDevice$app;
+      return ((_getDevice$app = getDevice().app) === null || _getDevice$app === void 0 ? void 0 : _getDevice$app.flavor) === AppFlavor.Chayns;
+    } catch {
+      return false;
+    }
+  }
+  shouldEnableInterception() {
+    return this.opts.blockRegistry.hasActiveBlocks(this.opts.rootLayer) || getCurrentIdx() > 0;
+  }
+  async runNativeBack() {
+    const isAllowed = await this.opts.blockRegistry.checkActiveBlocks(this.opts.rootLayer);
+    if (!isAllowed || !hasWindowHistory()) {
+      return;
+    }
+    this.bypassNextPopstateBlockCheck = true;
+    window.history.back();
+  }
+}

package/dist/esm/utils/history/navigationIndex.js

@@ -1,4 +1,5 @@
 import { hasWindowHistory } from './window';
+const CHAYNS_HISTORY_STATE_KEY = '__chaynsHistory';
 let currentIdx = 0;
 let pendingSilentCount = 0;
 let silentResolve = null;
@@ -8,6 +9,34 @@ export function incrementIdx() {
 export function getCurrentIdx() {
   return currentIdx;
 }
+export function setCurrentIdx(idx) {
+  if (!Number.isInteger(idx) || idx < 0) {
+    return;
+  }
+  currentIdx = idx;
+}
+export function extractHistoryIndex(raw) {
+  if (!raw || typeof raw !== 'object') {
+    return null;
+  }
+  const chaynsHistory = raw[CHAYNS_HISTORY_STATE_KEY];
+  if (!chaynsHistory || typeof chaynsHistory !== 'object') {
+    return null;
+  }
+  const idx = chaynsHistory.__idx;
+  if (typeof idx !== 'number' || !Number.isInteger(idx) || idx < 0) {
+    return null;
+  }
+  return idx;
+}
+export function syncCurrentIdxFromState(raw) {
+  const idx = extractHistoryIndex(raw);
+  if (idx === null) {
+    return null;
+  }
+  currentIdx = idx;
+  return idx;
+}
 export function silentGo(delta) {
   if (!hasWindowHistory()) return Promise.resolve();
   return new Promise(resolve => {

package/dist/esm/utils/history/rootLayer.js

@@ -4,11 +4,12 @@ import { BlockRegistry } from './BlockRegistry';
 import { findChaynsHistoryLayerById } from './layerTree';
 import { projectToUrl, parseFromUrl } from './url';
 import { projectToState, applyStateToTree, diffIncomingState, hasChaynsHistoryState } from './stateProjector';
-import { silentGo, consumeSilent, incrementIdx, getCurrentIdx } from './navigationIndex';
+import { silentGo, consumeSilent, incrementIdx, getCurrentIdx, syncCurrentIdxFromState } from './navigationIndex';
 import { hasWindowHistory } from './window';
 import { shallowEqualArr } from '../equality';
-import { getSite } from "../../calls";
+import { getSite } from '../../calls';
 import { normalizeHistorySegments } from './segments';
+import { NativeBackHandler } from './nativeBackHandling';
 function getInitialPathname(overrideUrl) {
   if (overrideUrl) {
     try {
@@ -40,21 +41,30 @@ export function resolveSegmentsFrom(overrideUrl, startIndex) {
 export function initRootChaynsHistoryLayer(opts = {}) {
   var _opts$segmentCount;
   const blockRegistry = new BlockRegistry();
-  let rootLayer;
-  let queue;
+  let queueRef = null;
   const deps = {
     getRoot: () => rootLayer,
-    getQueue: () => queue,
+    getQueue: () => {
+      if (!queueRef) {
+        throw new Error('[chaynsHistory] NavigationQueue not initialized yet.');
+      }
+      return queueRef;
+    },
     getBlockRegistry: () => blockRegistry
   };
-  rootLayer = new ChaynsHistoryLayer({
+  const rootLayer = new ChaynsHistoryLayer({
     id: 'root',
     parent: null,
     deps,
     segmentCount: (_opts$segmentCount = opts.segmentCount) !== null && _opts$segmentCount !== void 0 ? _opts$segmentCount : 0,
     segments: opts.segmentCount ? resolveInitialSegments(opts.url, opts.segmentCount) : []
   });
-  queue = new NavigationQueue({
+  const nativeBackHandler = new NativeBackHandler({
+    rootLayer,
+    blockRegistry
+  });
+  const syncNativeHandling = nativeBackHandler.sync;
+  const queue = new NavigationQueue({
     getRoot: () => rootLayer,
     findLayer: id => findChaynsHistoryLayerById(rootLayer, id),
     checkBlocks: target => blockRegistry.checkBlocks(target),
@@ -72,6 +82,7 @@ export function initRootChaynsHistoryLayer(opts = {}) {
     silentGo: delta => silentGo(delta),
     getCurrentIdx: () => getCurrentIdx(),
     incrementIdx: () => incrementIdx(),
+    onCommit: syncNativeHandling,
     applyUrlSegments: () => {
       if (!hasWindowHistory()) return {
         changedLayerIds: new Set()
@@ -95,7 +106,9 @@ export function initRootChaynsHistoryLayer(opts = {}) {
       };
     }
   });
+  queueRef = queue;
   const existingState = hasWindowHistory() ? window.history.state : null;
+  syncCurrentIdxFromState(existingState);
   if (!hasChaynsHistoryState(existingState)) {
     var _opts$segmentCount2, _opts$url;
     const segmentCount = (_opts$segmentCount2 = opts.segmentCount) !== null && _opts$segmentCount2 !== void 0 ? _opts$segmentCount2 : 0;
@@ -129,7 +142,7 @@ export function initRootChaynsHistoryLayer(opts = {}) {
       };
       delete foreign.__chaynsHistory;
       const initialState = projectToState(rootLayer, foreign);
-      const idx = incrementIdx();
+      const idx = getCurrentIdx();
       window.history.replaceState({
         ...initialState,
         __chaynsHistory: {
@@ -139,17 +152,42 @@ export function initRootChaynsHistoryLayer(opts = {}) {
       }, '', window.location.href);
     } else {
       applyStateToTree(rootLayer, existing);
+      if (syncCurrentIdxFromState(existing) === null) {
+        const foreign = {
+          ...(existing !== null && existing !== void 0 ? existing : {})
+        };
+        delete foreign.__chaynsHistory;
+        const currentState = projectToState(rootLayer, foreign);
+        const idx = getCurrentIdx();
+        window.history.replaceState({
+          ...currentState,
+          __chaynsHistory: {
+            ...currentState.__chaynsHistory,
+            __idx: idx
+          }
+        }, '', window.location.href);
+      }
     }
+    blockRegistry.subscribeToChanges(syncNativeHandling);
     window.addEventListener('popstate', event => {
-      if (consumeSilent()) return;
+      syncCurrentIdxFromState(event.state);
+      if (consumeSilent()) {
+        syncNativeHandling();
+        return;
+      }
       const raw = event.state;
-      if (!hasChaynsHistoryState(raw)) {} else {
+      if (!hasChaynsHistoryState(raw)) {
+        syncNativeHandling();
+      } else {
+        const skipBlockCheck = nativeBackHandler.consumeBypassFlag();
         void queue.enqueue({
           kind: 'popstate',
-          rawState: raw
-        });
+          rawState: raw,
+          skipBlockCheck
+        }).finally(syncNativeHandling);
       }
     });
+    syncNativeHandling();
   }
   return {
     rootLayer

package/dist/types/utils/history/BlockRegistry.d.ts

@@ -8,6 +8,7 @@ interface BlockEntry {
 export declare class BlockRegistry {
     /** Per-layer block list. */
     private readonly layerBlocks;
+    private readonly changeListeners;
     /** Number of blocks with `isBeforeUnload: true`. When > 0, listener is attached. */
     private beforeUnloadCount;
     private readonly beforeUnloadHandler;
@@ -15,6 +16,7 @@ export declare class BlockRegistry {
     remove(layerId: string, entry: BlockEntry): void;
     /** Remove all blocks registered for a layer (called on destroy). */
     removeAllForLayer(layerId: string): void;
+    subscribeToChanges(listener: () => void): () => void;
     /**
      * Collects all blocks applicable to a navigation targeting `targetLayer`.
      *
@@ -24,7 +26,11 @@ export declare class BlockRegistry {
      *   **active-chain descendants** (not inactive subtrees).
      */
     collectApplicableBlocks(targetLayer: ChaynsHistoryLayer): BlockEntry[];
+    hasActiveBlocks(rootLayer: ChaynsHistoryLayer): boolean;
+    checkActiveBlocks(rootLayer: ChaynsHistoryLayer): Promise<boolean>;
+    private collectActiveChainBlocks;
     private collectGlobalFromActiveDescendants;
+    private collectFromActiveChain;
     /**
      * Runs all applicable block callbacks in parallel.
      * Returns `true` if navigation is allowed (no block), `false` otherwise.
@@ -34,5 +40,6 @@ export declare class BlockRegistry {
     private runBlock;
     private incrementBeforeUnload;
     private decrementBeforeUnload;
+    private notifyChange;
 }
 export {};

package/dist/types/utils/history/NavigationQueue.d.ts

@@ -48,6 +48,13 @@ export type NavOp = {
 } | {
     kind: 'popstate';
     rawState: unknown;
+    /**
+     * @internal Skips the block check pipeline for this popstate. Used when
+     * the popstate was triggered by us right after a native-back callback
+     * that already ran `checkActiveBlocks` — re-running it would prompt the
+     * user twice.
+     */
+    skipBlockCheck?: boolean;
 };
 export type NavResult = ChaynsHistoryActionResult;
 export interface NavigationQueueDeps {
@@ -78,6 +85,8 @@ export interface NavigationQueueDeps {
     getCurrentIdx: () => number;
     /** Increments the navigation index and returns the new value. */
     incrementIdx: () => number;
+    /** Called after a browser history commit finished. */
+    onCommit?: () => void;
     /**
      * Re-parse segments from `window.location.pathname` and apply them to each
      * layer in the active chain based on its `segmentCount`. Called after

package/dist/types/utils/history/nativeBackHandling.d.ts

@@ -0,0 +1,47 @@
+import type { ChaynsHistoryLayer } from '../../handler/history/HistoryLayer';
+import type { BlockRegistry } from './BlockRegistry';
+export interface NativeBackHandlerOptions {
+    rootLayer: ChaynsHistoryLayer;
+    blockRegistry: BlockRegistry;
+}
+/**
+ * Coordinates the native swipe-back gesture (Chayns app action 249) with the
+ * JS history queue.
+ *
+ * Why we disable the gesture as soon as the user has navigated inside the app
+ * (`getCurrentIdx() > 0`) and not only while a block is registered:
+ *   The native swipe animation runs independently of our JS handling. Without
+ *   intercepting it, a swipe-back would (a) play the native pop animation,
+ *   (b) pop the browser entry, (c) fire popstate, and only THEN would the
+ *   queue evaluate the block and silently push forward again — producing the
+ *   "navigate back, then snap forward" jitter described in the bug report.
+ *   By intercepting from the first own history entry on, every back must come
+ *   through the registered callback where we can resolve blocks before
+ *   mutating history.
+ *
+ * Instances are scoped to a single root layer; module-level state is avoided
+ * so re-inits (HMR, tests, multiple roots) cannot desynchronise.
+ */
+export declare class NativeBackHandler {
+    private readonly opts;
+    private isInterceptionEnabled;
+    /**
+     * Set to `true` right before `history.back()` is triggered from
+     * {@link handleNativeBack}. Consumed by the popstate listener so the
+     * queue can skip the duplicate block check (we already ran it).
+     */
+    private bypassNextPopstateBlockCheck;
+    constructor(opts: NativeBackHandlerOptions);
+    /** Re-evaluates the desired native gesture state and pushes it to the app. */
+    sync: () => void;
+    /**
+     * Returns `true` exactly once after a {@link handleNativeBack}-initiated
+     * `history.back()`. The popstate listener uses this so the queue can skip
+     * the (already performed) block check.
+     */
+    consumeBypassFlag(): boolean;
+    private static isSupported;
+    private shouldEnableInterception;
+    private handleNativeBack;
+    private runNativeBack;
+}

package/dist/types/utils/history/navigationIndex.d.ts

@@ -2,6 +2,9 @@
 export declare function incrementIdx(): number;
 /** Get current index for stamping real entries or direction comparison. */
 export declare function getCurrentIdx(): number;
+export declare function setCurrentIdx(idx: number): void;
+export declare function extractHistoryIndex(raw: unknown): number | null;
+export declare function syncCurrentIdxFromState(raw: unknown): number | null;
 /**
  * Performs a `history.go(delta)` that is silently ignored by our popstate handler.
  * Returns a promise that resolves when the popstate for this go() fires.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "chayns-api",
-    "version": "3.1.0-beta.0",
+    "version": "3.1.0-beta.1",
     "description": "new chayns api",
     "main": "dist/cjs/index.js",
     "module": "dist/esm/index.js",