@absolutejs/absolute 0.20.0-beta.58 → 0.20.0-beta.59

package/dist/mobile/shellBootstrap.js

@@ -458,7 +458,11 @@ var createAbsoluteMobilePageRequest = (manifest, path, options = {}) => {
   headers.set(MOBILE_PAGE_REQUEST_HEADERS.pageId, page.pageId);
   headers.set(MOBILE_PAGE_REQUEST_HEADERS.protocol, String(ABSOLUTE_MOBILE_PAGE_PROTOCOL_VERSION));
   headers.set(MOBILE_PAGE_REQUEST_HEADERS.runtime, manifest.runtime);
-  return new Request(url, { headers, method: "GET" });
+  return new Request(url, {
+    headers,
+    method: "GET",
+    ...options.signal ? { signal: options.signal } : {}
+  });
 };
 var fetchAbsoluteMobilePage = async (manifest, path, options = {}) => {
   const request = createAbsoluteMobilePageRequest(manifest, path, options);
@@ -1143,9 +1147,268 @@ var installAbsoluteMobileAdaptiveShell = async (devices = defaultDevices) => {
   };
 };
 
+// src/mobile/navigationLifecycle.ts
+var isAbortError = (error) => error instanceof DOMException ? error.name === "AbortError" : error instanceof Error && error.name === "AbortError";
+var cancelledResult = { kind: "cancelled" };
+var committedResult = { kind: "committed" };
+var failedResult = (error, phase) => ({ error, kind: "failed", phase });
+var createAbsoluteMobileNavigationCoordinator = (options) => {
+  let activeLoad;
+  let commitQueue = Promise.resolve();
+  let disposed = false;
+  let generation = 0;
+  let lifecyclePhase = "idle";
+  const navigate = async (request) => {
+    if (disposed)
+      return cancelledResult;
+    const ownGeneration = generation += 1;
+    activeLoad?.abort();
+    const controller = new AbortController;
+    activeLoad = controller;
+    lifecyclePhase = "loading";
+    options.onStart?.(request);
+    let payload;
+    try {
+      payload = await options.load(request, controller.signal);
+    } catch (error) {
+      if (controller.signal.aborted || isAbortError(error) || ownGeneration !== generation || disposed) {
+        if (ownGeneration === generation)
+          lifecyclePhase = "idle";
+        return cancelledResult;
+      }
+      lifecyclePhase = "idle";
+      options.onFailure?.(error, "load", request);
+      return failedResult(error, "load");
+    }
+    if (ownGeneration !== generation || disposed)
+      return cancelledResult;
+    if (activeLoad === controller)
+      activeLoad = undefined;
+    lifecyclePhase = "queued";
+    const execute = async () => {
+      if (ownGeneration !== generation || disposed) {
+        if (ownGeneration === generation)
+          lifecyclePhase = "idle";
+        return cancelledResult;
+      }
+      lifecyclePhase = "committing";
+      try {
+        await options.commit(payload, request);
+        options.onCommit?.(request);
+      } catch (error) {
+        if (ownGeneration === generation) {
+          lifecyclePhase = "idle";
+          options.onFailure?.(error, "commit", request);
+        }
+        return failedResult(error, "commit");
+      }
+      if (ownGeneration !== generation || disposed) {
+        return cancelledResult;
+      }
+      lifecyclePhase = "idle";
+      options.onSuccess?.(request);
+      return committedResult;
+    };
+    const result = commitQueue.then(execute, execute);
+    commitQueue = result.then(() => {
+      return;
+    }, () => {
+      return;
+    });
+    return result;
+  };
+  return {
+    cancelPending: () => {
+      if (disposed || lifecyclePhase !== "loading" && lifecyclePhase !== "queued")
+        return false;
+      generation += 1;
+      activeLoad?.abort();
+      activeLoad = undefined;
+      lifecyclePhase = "idle";
+      return true;
+    },
+    dispose: () => {
+      if (disposed)
+        return;
+      disposed = true;
+      generation += 1;
+      activeLoad?.abort();
+      activeLoad = undefined;
+      lifecyclePhase = "idle";
+    },
+    navigate: (request) => navigate(request),
+    phase: () => lifecyclePhase
+  };
+};
+
+// src/mobile/navigationState.ts
+var CONTROL_SELECTOR = 'input, textarea, select, details, [contenteditable="true"]';
+var FOCUS_SELECTOR = '[data-absolute-navigation-focus], button, a[href], input, textarea, select, [tabindex]:not([tabindex="-1"])';
+var SCROLL_SELECTOR = "[data-absolute-app-main], [data-absolute-scroll-restoration]";
+var SENSITIVE_AUTOCOMPLETE = new Set([
+  "cc-csc",
+  "cc-number",
+  "current-password",
+  "new-password",
+  "one-time-code"
+]);
+var locatorFor = (element, elements) => {
+  if (element.id)
+    return { kind: "id", value: element.id };
+  const name = element.getAttribute("name");
+  if (name) {
+    const matching = elements.filter((candidate) => candidate.getAttribute("name") === name);
+    return { index: matching.indexOf(element), kind: "name", value: name };
+  }
+  return { index: elements.indexOf(element), kind: "index" };
+};
+var resolveLocator = (locator, selector) => {
+  if (locator.kind === "id") {
+    return document.getElementById(locator.value) ?? undefined;
+  }
+  if (locator.kind === "name") {
+    return [...document.querySelectorAll(selector)].filter((element) => element.getAttribute("name") === locator.value)[locator.index];
+  }
+  return document.querySelectorAll(selector)[locator.index];
+};
+var shouldCaptureControl = (element) => {
+  if (element.closest('[data-absolute-navigation-preserve="off"]'))
+    return false;
+  if (!(element instanceof HTMLInputElement))
+    return true;
+  if (element.type === "file" || element.type === "hidden" || element.type === "password")
+    return false;
+  return !SENSITIVE_AUTOCOMPLETE.has(element.autocomplete.toLowerCase());
+};
+var captureControl = (element, locator) => {
+  const snapshot = {
+    locator,
+    tag: element.tagName.toLowerCase()
+  };
+  if (element instanceof HTMLInputElement) {
+    if (element.type === "checkbox" || element.type === "radio") {
+      snapshot.checked = element.checked;
+    } else {
+      snapshot.value = element.value;
+      if (element.selectionStart !== null)
+        snapshot.selectionStart = element.selectionStart;
+      if (element.selectionEnd !== null)
+        snapshot.selectionEnd = element.selectionEnd;
+    }
+  } else if (element instanceof HTMLTextAreaElement) {
+    snapshot.value = element.value;
+    snapshot.selectionStart = element.selectionStart;
+    snapshot.selectionEnd = element.selectionEnd;
+  } else if (element instanceof HTMLSelectElement) {
+    snapshot.values = [...element.selectedOptions].map(({ value }) => value);
+  } else if (element instanceof HTMLDetailsElement) {
+    snapshot.open = element.open;
+  } else if (element.getAttribute("contenteditable") === "true") {
+    snapshot.value = element.textContent ?? "";
+  }
+  return snapshot;
+};
+var restoreControl = (snapshot) => {
+  const element = resolveLocator(snapshot.locator, CONTROL_SELECTOR);
+  if (!element || element.tagName.toLowerCase() !== snapshot.tag)
+    return;
+  if (element instanceof HTMLInputElement) {
+    if (snapshot.checked !== undefined)
+      element.checked = snapshot.checked;
+    else if (snapshot.value !== undefined)
+      element.value = snapshot.value;
+    if (snapshot.selectionStart !== undefined && snapshot.selectionEnd !== undefined) {
+      try {
+        element.setSelectionRange(snapshot.selectionStart, snapshot.selectionEnd);
+      } catch {}
+    }
+  } else if (element instanceof HTMLTextAreaElement) {
+    if (snapshot.value !== undefined)
+      element.value = snapshot.value;
+    if (snapshot.selectionStart !== undefined && snapshot.selectionEnd !== undefined)
+      element.setSelectionRange(snapshot.selectionStart, snapshot.selectionEnd);
+  } else if (element instanceof HTMLSelectElement && snapshot.values) {
+    for (const option of element.options) {
+      option.selected = snapshot.values.includes(option.value);
+    }
+  } else if (element instanceof HTMLDetailsElement && snapshot.open !== undefined) {
+    element.open = snapshot.open;
+  } else if (element.getAttribute("contenteditable") === "true" && snapshot.value !== undefined) {
+    element.textContent = snapshot.value;
+  }
+};
+var focusElement = (element) => {
+  if (!(element instanceof HTMLElement))
+    return false;
+  if (!element.matches(FOCUS_SELECTOR))
+    element.tabIndex = -1;
+  element.focus({ preventScroll: true });
+  return document.activeElement === element;
+};
+var createAbsoluteMobileHistoryEntry = (path, index, entryId = crypto.randomUUID()) => ({
+  absoluteMobile: true,
+  entryId,
+  index,
+  path
+});
+var readAbsoluteMobileHistoryEntry = (value) => {
+  if (typeof value !== "object" || value === null)
+    return;
+  if (Reflect.get(value, "absoluteMobile") !== true || typeof Reflect.get(value, "entryId") !== "string" || !Number.isSafeInteger(Reflect.get(value, "index")) || typeof Reflect.get(value, "path") !== "string")
+    return;
+  return {
+    absoluteMobile: true,
+    entryId: Reflect.get(value, "entryId"),
+    index: Reflect.get(value, "index"),
+    path: Reflect.get(value, "path")
+  };
+};
+var captureAbsoluteMobileDocumentState = () => {
+  const controls = [
+    ...document.querySelectorAll(CONTROL_SELECTOR)
+  ].filter(shouldCaptureControl);
+  const focusable = [...document.querySelectorAll(FOCUS_SELECTOR)];
+  const scrollable = [...document.querySelectorAll(SCROLL_SELECTOR)];
+  const active = document.activeElement;
+  return {
+    controls: controls.map((element) => captureControl(element, locatorFor(element, controls))),
+    ...active instanceof Element && focusable.includes(active) ? { focus: locatorFor(active, focusable) } : {},
+    scroll: scrollable.map((element) => ({
+      left: element.scrollLeft,
+      locator: locatorFor(element, scrollable),
+      top: element.scrollTop
+    })),
+    window: { x: window.scrollX, y: window.scrollY }
+  };
+};
+var restoreAbsoluteMobileDocumentState = (snapshot) => {
+  for (const control of snapshot.controls)
+    restoreControl(control);
+  const focus = snapshot.focus ? resolveLocator(snapshot.focus, FOCUS_SELECTOR) : undefined;
+  focusElement(focus);
+  for (const scroll of snapshot.scroll) {
+    const element = resolveLocator(scroll.locator, SCROLL_SELECTOR);
+    if (element)
+      element.scrollTo(scroll.left, scroll.top);
+  }
+  window.scrollTo(snapshot.window.x, snapshot.window.y);
+};
+var resetAbsoluteMobileDocumentState = () => {
+  for (const element of document.querySelectorAll(SCROLL_SELECTOR)) {
+    element.scrollTo(0, 0);
+  }
+  window.scrollTo(0, 0);
+  const autofocus = document.querySelector("[autofocus]");
+  if (autofocus && focusElement(autofocus))
+    return;
+  const target = ["[data-absolute-navigation-focus]", "main h1", "h1", "main"].map((selector) => document.querySelector(selector)).find((element) => element !== null);
+  focusElement(target ?? undefined);
+};
+
 // src/mobile/shellBootstrap.ts
 var MANIFEST_PATH = "./absolute-mobile-manifest.json";
 var STATUS_ID = "absolute-mobile-status";
+var NAVIGATION_ERROR_ID = "absolute-mobile-navigation-error";
 var initialNavigationPath = (entry) => {
   const expoPath = new URLSearchParams(location.search).get("absolutePath");
   if (expoPath?.startsWith("/") && !expoPath.startsWith("//"))
@@ -1157,33 +1420,19 @@ var currentNavigationPath = () => {
   const expoPath = new URLSearchParams(location.search).get("absolutePath");
   return expoPath?.startsWith("/") && !expoPath.startsWith("//") ? expoPath : `${location.pathname}${location.search}${location.hash}`;
 };
-var pushNavigationHistory = (path) => {
+var historyUrl = (path) => {
   if (!Reflect.get(globalThis, "__absoluteExpoBridge")) {
-    history.pushState({ absoluteMobile: true }, "", path);
-    return;
+    return path;
   }
   const url = new URL(location.href);
   url.search = "";
   url.hash = "";
   url.searchParams.set("absolutePath", path);
-  history.pushState({ absoluteMobile: true }, "", url.href);
-  const bridge = Reflect.get(globalThis, "__absoluteExpoBridge");
-  if (typeof bridge === "object" && bridge !== null && typeof Reflect.get(bridge, "setPath") === "function") {
-    Reflect.get(bridge, "setPath").call(bridge, path);
-  }
+  return url.href;
 };
-var replaceNavigationHistory = (path) => {
-  const state = { absoluteMobile: true };
-  if (!Reflect.get(globalThis, "__absoluteExpoBridge")) {
-    history.replaceState(state, "", path);
-    return;
-  }
-  const url = new URL(location.href);
-  url.search = "";
-  url.hash = "";
-  url.searchParams.set("absolutePath", path);
-  history.replaceState(state, "", url.href);
-  notifyExpoNavigationPath(path);
+var writeNavigationHistory = (entry, mode) => {
+  history[mode === "push" ? "pushState" : "replaceState"](entry, "", historyUrl(entry.path));
+  notifyExpoNavigationPath(entry.path);
 };
 var notifyExpoNavigationPath = (path) => {
   const bridge = Reflect.get(globalThis, "__absoluteExpoBridge");
@@ -1222,6 +1471,34 @@ var renderStatus = (message, kind = "loading") => {
     status.textContent = message;
   adaptiveShell?.refreshDocument();
 };
+var clearNavigationFailure = () => {
+  document.getElementById(NAVIGATION_ERROR_ID)?.remove();
+};
+var renderNavigationFailure = (message, retry) => {
+  clearNavigationFailure();
+  const error = document.createElement("aside");
+  error.id = NAVIGATION_ERROR_ID;
+  error.dataset.absoluteMobileNavigationError = "";
+  error.setAttribute("role", "alert");
+  error.style.cssText = "position:fixed;z-index:2147483646;inset:auto max(1rem,var(--absolute-safe-area-inset-right,0px)) max(1rem,var(--absolute-safe-area-inset-bottom,0px)) max(1rem,var(--absolute-safe-area-inset-left,0px));display:flex;align-items:center;justify-content:space-between;gap:1rem;box-sizing:border-box;padding:.75rem 1rem;border:1px solid color-mix(in srgb,CanvasText 24%,transparent);border-radius:.75rem;background:Canvas;color:CanvasText;box-shadow:0 .5rem 2rem color-mix(in srgb,CanvasText 20%,transparent)";
+  const text = document.createElement("span");
+  text.textContent = message;
+  const button = document.createElement("button");
+  button.type = "button";
+  button.textContent = "Retry";
+  button.addEventListener("click", retry, { once: true });
+  error.append(text, button);
+  document.body.append(error);
+};
+var markNavigationPending = (pending) => {
+  if (pending) {
+    document.body.dataset.absoluteMobileNavigationPending = "";
+    document.body.setAttribute("aria-busy", "true");
+  } else {
+    delete document.body.dataset.absoluteMobileNavigationPending;
+    document.body.removeAttribute("aria-busy");
+  }
+};
 var renderPageTarget = () => {
   document.title = "AbsoluteJS";
   document.head.innerHTML = '<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">';
@@ -1247,13 +1524,16 @@ var installLocalPageStyle = (manifest, pageId, contract) => {
   link.dataset.absoluteMobilePageStyle = page.bundleHash;
   document.head.appendChild(link);
 };
-var navigate = async (manifest, path, historyMode, fetchImpl) => {
-  const hadActivePage = document.body.dataset.absoluteMobilePageActive !== undefined;
+var waitForDocumentPaint = () => new Promise((resolve) => {
+  if (typeof requestAnimationFrame !== "function") {
+    setTimeout(resolve, 0);
+    return;
+  }
+  requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
+});
+var commitNavigation = async (manifest, envelope, hadActivePage) => {
   if (!hadActivePage)
     renderStatus("Loading…");
-  const envelope = await fetchAbsoluteMobilePage(manifest, path, {
-    ...fetchImpl ? { fetch: fetchImpl } : {}
-  });
   let activation;
   const commit = async () => {
     await disposeAbsoluteMobilePage();
@@ -1285,14 +1565,12 @@ var navigate = async (manifest, path, historyMode, fetchImpl) => {
     throw new TypeError("The mobile page did not produce an activation.");
   if (activation.kind === "upgrade-required") {
     renderStatus("This app version must be updated to continue.", "update");
-    return;
+    return false;
   }
+  await waitForDocumentPaint();
   document.body.dataset.absoluteMobilePageActive = "";
   adaptiveShell?.refreshDocument();
-  if (historyMode === "push")
-    pushNavigationHistory(path);
-  else if (historyMode === "replace")
-    replaceNavigationHistory(path);
+  return true;
 };
 var openExternalLink = (anchor, event) => {
   if (Reflect.get(globalThis, "__absoluteExpoBridge"))
@@ -1305,7 +1583,7 @@ var openExternalLink = (anchor, event) => {
     Browser.open({ url: url.href }).catch(() => location.assign(url.href));
   } catch {}
 };
-var installAnchorNavigation = (manifest, onNavigate) => {
+var installAnchorNavigation = (manifest, onNavigate, onBack) => {
   const handleClick = (event) => {
     if (!(event.target instanceof Element))
       return;
@@ -1315,7 +1593,7 @@ var installAnchorNavigation = (manifest, onNavigate) => {
     const intent = readAbsoluteMobileLinkIntent(anchor);
     if (intent.kind === "back") {
       event.preventDefault();
-      if (!uiPrimitives?.requestBack())
+      if (!uiPrimitives?.requestBack() && !onBack())
         history.back();
       return;
     }
@@ -1355,21 +1633,6 @@ var installDeepLinks = async (manifest, onNavigate, authRedirectUri) => {
   } catch {}
   return listener;
 };
-var navigateWithFailureState = async (manifest, path, historyMode, direction, from, reinstallBrowserNavigation, fetchImpl) => {
-  let completed = false;
-  try {
-    document.documentElement.dataset.absoluteNavigationDirection = direction;
-    await navigate(manifest, path, historyMode, fetchImpl);
-    completed = true;
-  } catch (error) {
-    console.error("[Absolute Mobile] Navigation failed:", error);
-    renderStatus(document.documentElement.dataset.absoluteNetwork === "offline" ? "You are offline. Reconnect to load this page." : "Unable to load this page. Check your connection and retry.", "error");
-  } finally {
-    reinstallBrowserNavigation();
-  }
-  if (completed)
-    uiPrimitives?.navigate({ direction, from, to: path });
-};
 var startAbsoluteMobileShell = async (options = {}) => {
   notifyCapacitorSystemBarsDomReady();
   await adaptiveShell?.dispose();
@@ -1378,6 +1641,11 @@ var startAbsoluteMobileShell = async (options = {}) => {
   uiPrimitives = installAbsoluteMobileUiPrimitives();
   const manifest = await readManifest();
   let activePath = initialNavigationPath(manifest.entry);
+  let activeEntry = readAbsoluteMobileHistoryEntry(history.state) ?? createAbsoluteMobileHistoryEntry(activePath, 0);
+  if (activeEntry.path !== activePath) {
+    activeEntry = createAbsoluteMobileHistoryEntry(activePath, 0);
+  }
+  writeNavigationHistory(activeEntry, "replace");
   const auth = manifest.auth && options.createAuth ? await options.createAuth(manifest.auth, {
     beforeSignOut: options.beforeSignOut
   }) : undefined;
@@ -1387,15 +1655,104 @@ var startAbsoluteMobileShell = async (options = {}) => {
     options.connectPush?.(auth);
   if (auth && manifest.sync?.socketTickets)
     options.installSync?.(auth, manifest.sync);
+  const snapshots = new Map;
+  const targetEntries = new WeakMap;
+  let suppressNextPop = false;
+  let hasActivePage = false;
   let removeAnchorNavigation = () => {
     return;
   };
-  const handlePopState = () => {
+  const coordinator = createAbsoluteMobileNavigationCoordinator({
+    commit: async (envelope, request) => {
+      if (hasActivePage) {
+        snapshots.set(activeEntry.entryId, captureAbsoluteMobileDocumentState());
+      }
+      document.documentElement.dataset.absoluteNavigationDirection = request.direction;
+      try {
+        const previouslyActive = hasActivePage;
+        hasActivePage = false;
+        hasActivePage = await commitNavigation(manifest, envelope, previouslyActive);
+      } finally {
+        reinstallBrowserNavigation();
+      }
+    },
+    load: (request, signal) => fetchAbsoluteMobilePage(manifest, request.path, {
+      fetch: applicationFetch,
+      signal
+    }),
+    onFailure: (error, phase, request) => {
+      console.error("[Absolute Mobile] Navigation failed:", error);
+      markNavigationPending(false);
+      const targetEntry = targetEntries.get(request);
+      if (targetEntry && targetEntry.index !== activeEntry.index) {
+        suppressNextPop = true;
+        history.go(activeEntry.index - targetEntry.index);
+      }
+      const message = document.documentElement.dataset.absoluteNetwork === "offline" ? "You are offline. Reconnect to load this page." : "Unable to load this page. Check your connection and retry.";
+      if (phase === "load" && hasActivePage) {
+        renderNavigationFailure(message, () => {
+          if (targetEntry) {
+            history.go(targetEntry.index - activeEntry.index);
+          } else
+            coordinator.navigate(request);
+        });
+      } else
+        renderStatus(message, "error");
+    },
+    onStart: () => {
+      clearNavigationFailure();
+      markNavigationPending(true);
+    },
+    onSuccess: (request) => {
+      let nextEntry = targetEntries.get(request);
+      if (request.historyMode === "push") {
+        nextEntry = createAbsoluteMobileHistoryEntry(request.path, activeEntry.index + 1);
+        writeNavigationHistory(nextEntry, "push");
+      } else if (request.historyMode === "replace") {
+        nextEntry = createAbsoluteMobileHistoryEntry(request.path, activeEntry.index);
+        writeNavigationHistory(nextEntry, "replace");
+      }
+      nextEntry ??= activeEntry;
+      activeEntry = nextEntry;
+      activePath = request.path;
+      markNavigationPending(false);
+      clearNavigationFailure();
+      const snapshot = snapshots.get(activeEntry.entryId);
+      if (snapshot)
+        restoreAbsoluteMobileDocumentState(snapshot);
+      else if (request.historyMode !== "none")
+        resetAbsoluteMobileDocumentState();
+      uiPrimitives?.navigate({
+        direction: request.direction,
+        from: request.from,
+        to: request.path
+      });
+    }
+  });
+  const cancelPendingNavigation = () => {
+    if (!coordinator.cancelPending())
+      return false;
+    markNavigationPending(false);
+    clearNavigationFailure();
+    return true;
+  };
+  const handlePopState = (event) => {
     const path = currentNavigationPath();
-    const from = activePath;
-    activePath = path;
+    if (suppressNextPop) {
+      suppressNextPop = false;
+      notifyExpoNavigationPath(activePath);
+      return;
+    }
+    const targetEntry = readAbsoluteMobileHistoryEntry(event.state) ?? createAbsoluteMobileHistoryEntry(path, activeEntry.index - 1);
     notifyExpoNavigationPath(path);
-    navigateWithFailureState(manifest, path, "none", "back", from, reinstallBrowserNavigation, applicationFetch);
+    const request = {
+      direction: targetEntry.index > activeEntry.index ? "forward" : "back",
+      from: activePath,
+      historyMode: "none",
+      path
+    };
+    targetEntries.set(request, targetEntry);
+    coordinator.navigate(request);
   };
   const reinstallBrowserNavigation = () => {
     removeAnchorNavigation();
@@ -1403,20 +1760,33 @@ var startAbsoluteMobileShell = async (options = {}) => {
     uiPrimitives?.dispose();
     uiPrimitives = installAbsoluteMobileUiPrimitives();
     uiPrimitives.refreshDocument(activePath);
-    removeAnchorNavigation = installAnchorNavigation(manifest, onNavigate);
+    removeAnchorNavigation = installAnchorNavigation(manifest, onNavigate, cancelPendingNavigation);
     addEventListener("popstate", handlePopState);
   };
   const onNavigate = (path, direction = "forward", replace = false) => {
-    const from = activePath;
-    activePath = path;
-    navigateWithFailureState(manifest, path, replace ? "replace" : "push", direction, from, reinstallBrowserNavigation, applicationFetch);
+    if (path === activePath && !replace && hasActivePage)
+      return;
+    coordinator.navigate({
+      direction,
+      from: activePath,
+      historyMode: replace ? "replace" : "push",
+      path
+    });
   };
-  await navigateWithFailureState(manifest, activePath, "none", "replace", activePath, reinstallBrowserNavigation, applicationFetch);
+  reinstallBrowserNavigation();
+  await coordinator.navigate({
+    direction: "replace",
+    from: activePath,
+    historyMode: "none",
+    path: activePath
+  });
   await installDeepLinks(manifest, onNavigate, auth?.redirectUri);
   try {
     await App.addListener("backButton", ({ canGoBack }) => {
       if (uiPrimitives?.requestBack())
         return;
+      if (cancelPendingNavigation())
+        return;
       if (canGoBack)
         history.back();
       else

package/dist/mobile/shellSync.js

@@ -107,17 +107,28 @@ var installAbsoluteMobileShellSync = (auth, config, options = {}) => {
   const reportSchemaState = options.reportSchemaState ?? reportShellSchemaState;
   const configureBackground = options.configureBackground ?? configureCapacitorBackgroundSync;
   const clearBackground = options.clearBackground ?? (() => AbsoluteBackgroundSync.clear());
+  let schemaReady = Promise.resolve(true);
   if (store?.getSchemaStatus) {
     reportSchemaState({ state: "preparing" });
-    store.getSchemaStatus().then(reportSchemaState).catch((error) => reportSchemaState(schemaFailureState(error)));
+    schemaReady = store.getSchemaStatus().then((state) => {
+      reportSchemaState(state);
+      return true;
+    }).catch((error) => {
+      reportSchemaState(schemaFailureState(error));
+      return false;
+    });
   }
   if (namespace && config) {
-    configureBackground({
-      clientId: auth.clientId,
-      endpoint: config.background.endpoint,
-      intervalMinutes: config.background.intervalMinutes,
-      issuer: auth.issuer,
-      namespace
+    schemaReady.then((ready) => {
+      if (!ready)
+        return;
+      return configureBackground({
+        clientId: auth.clientId,
+        endpoint: config.background.endpoint,
+        intervalMinutes: config.background.intervalMinutes,
+        issuer: auth.issuer,
+        namespace
+      });
     }).catch((error) => console.error("[Absolute Mobile] Background Sync configuration failed:", error));
   } else {
     clearBackground().catch(() => {

package/dist/src/mobile/navigationLifecycle.d.ts

@@ -0,0 +1,36 @@
+export type AbsoluteMobileNavigationHistoryMode = 'none' | 'push' | 'replace';
+export type AbsoluteMobileNavigationRequest = {
+    direction: 'back' | 'forward' | 'replace';
+    from: string;
+    historyMode: AbsoluteMobileNavigationHistoryMode;
+    path: string;
+};
+export type AbsoluteMobileNavigationFailurePhase = 'commit' | 'load';
+export type AbsoluteMobileNavigationResult = {
+    kind: 'cancelled';
+} | {
+    kind: 'committed';
+} | {
+    kind: 'failed';
+    error: unknown;
+    phase: AbsoluteMobileNavigationFailurePhase;
+};
+export type AbsoluteMobileNavigationCoordinatorOptions<Payload> = {
+    commit: (payload: Payload, request: AbsoluteMobileNavigationRequest) => Promise<void>;
+    load: (request: AbsoluteMobileNavigationRequest, signal: AbortSignal) => Promise<Payload>;
+    onCommit?: (request: AbsoluteMobileNavigationRequest) => void;
+    onFailure?: (error: unknown, phase: AbsoluteMobileNavigationFailurePhase, request: AbsoluteMobileNavigationRequest) => void;
+    onStart?: (request: AbsoluteMobileNavigationRequest) => void;
+    onSuccess?: (request: AbsoluteMobileNavigationRequest) => void;
+};
+export type AbsoluteMobileNavigationCoordinator = {
+    cancelPending(): boolean;
+    dispose(): void;
+    navigate(request: AbsoluteMobileNavigationRequest): Promise<AbsoluteMobileNavigationResult>;
+    phase(): 'committing' | 'idle' | 'loading' | 'queued';
+};
+/**
+ * Coordinates native-shell route loads. Loads may overlap, but only the latest
+ * completed load may enter the serialized document commit boundary.
+ */
+export declare const createAbsoluteMobileNavigationCoordinator: <Payload>(options: AbsoluteMobileNavigationCoordinatorOptions<Payload>) => AbsoluteMobileNavigationCoordinator;