diff --git a/common/components/ShopifyLogin.vue b/common/components/ShopifyLogin.vue
index b1989c0..e1e7ccc 100644
--- a/common/components/ShopifyLogin.vue
+++ b/common/components/ShopifyLogin.vue
@@ -21,10 +21,11 @@
 <script setup lang="ts">
 import { IonContent, IonIcon, IonItem, IonPage, onIonViewDidEnter, onIonViewDidLeave } from "@ionic/vue";
 import { ref } from "vue";
-import { emitter, translate, useShopify, useEmbeddedAppStore } from "../index";
+import { commonUtil, emitter, translate, useShopify, useEmbeddedAppStore } from "../index";
 import Logo from "./Logo.vue";
 import { accxuiConfig } from "../core/configRegistry";
 import { warningOutline } from "ionicons/icons";
+import { useAuth } from "../composables/useAuth"
 
 const { appBridgeLogin } = useShopify();
 const embeddedAppStore = useEmbeddedAppStore();
@@ -41,6 +42,17 @@ onIonViewDidEnter(async () => {
 
     let { shop, host } = route.query;
 
+    console.log('router.', shop, host, import.meta.env.VITE_SHOPIFY_SHOP_CONFIG)
+
+    // Resolve the pinned app version BEFORE touching App Bridge. Shopify's App URL can't carry a version,
+    // so an embedded session always starts unversioned and may need one redirect — doing it first means we
+    // don't throw away a completed bridge handshake and session-token exchange, and App Bridge is created
+    // exactly once, on the page that will actually run. This needs no token (`appVersions` is an anonymous
+    // endpoint) and no login round trip: the shop's Maarg instance comes from the build-time shop config.
+    const shopConfig = commonUtil.jsonParse(import.meta.env.VITE_SHOPIFY_SHOP_CONFIG)?.[shop as string];
+    // A redirect is a pending page load — stop here rather than starting work that gets torn down.
+    if (await useAuth().fetchAppVersion(commonUtil.getMaargURL(shopConfig?.maarg))) return;
+
     const success = await appBridgeLogin(shop as string, host as string);
 
     if (success) {
diff --git a/common/composables/appVersionRedirect.spec.ts b/common/composables/appVersionRedirect.spec.ts
new file mode 100644
index 0000000..d262698
--- /dev/null
+++ b/common/composables/appVersionRedirect.spec.ts
@@ -0,0 +1,114 @@
+// @vitest-environment jsdom
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createPinia, setActivePinia } from "pinia";
+
+// Each scenario needs a fresh module instance: the in-flight flag and the "reconciled once" flag are
+// module-scoped, standing in for a page load. resetModules() + dynamic import is how we simulate a reload.
+const loadUseAuth = async () => {
+  vi.resetModules();
+  const [{ useAuth }, { accxuiConfig }] = await Promise.all([
+    import("./useAuth"),
+    import("../core/configRegistry")
+  ]);
+  return { useAuth, accxuiConfig };
+};
+
+const setBuildVersion = (buildVersion: string) =>
+  vi.stubEnv("VITE_APP_VERSION_CONFIG", JSON.stringify({ appId: "BOPIS", environmentTypeId: "AppEnvDev", buildVersion }));
+
+const setUrl = (url: string) => window.history.replaceState({}, "", url);
+
+// Simulate one page load: bundle built as `buildVersion`, served at `pathname`, OMS pinning `pinned`.
+// Returns whether a redirect was issued and where to, plus the composable for follow-up calls.
+const load = async (buildVersion: string, pathname: string, pinned: string) => {
+  setBuildVersion(buildVersion);
+  setUrl(pathname);
+  const { useAuth, accxuiConfig } = await loadUseAuth();
+  accxuiConfig.value.appVersion = pinned;
+
+  const replace = vi.fn();
+  Object.defineProperty(window, "location", {
+    configurable: true,
+    value: { ...window.location, pathname, search: "", hash: "", origin: "https://app.test", replace }
+  });
+
+  const auth = useAuth();
+  const redirected = auth.checkAppVersionRedirect();
+  return { redirected, to: replace.mock.calls[0]?.[0] as string | undefined, auth };
+};
+
+describe("checkAppVersionRedirect", () => {
+  beforeEach(() => {
+    setActivePinia(createPinia());
+    sessionStorage.clear();
+  });
+
+  afterEach(() => vi.unstubAllEnvs());
+
+  it("redirects the root build onto the pinned version", async () => {
+    const { redirected, to } = await load("", "/", "v5.1.0");
+
+    expect(redirected).toBe(true);
+    expect(to).toContain("/v5.1.0/");
+  });
+
+  it("reports the in-flight redirect to later callers in the same page load", async () => {
+    const { auth } = await load("", "/", "v5.1.0");
+
+    // Login.vue resolves the version from more than one path; the router guard fires per navigation.
+    expect(auth.checkAppVersionRedirect()).toBe(true);
+    expect(auth.checkAppVersionRedirect()).toBe(true);
+  });
+
+  it("does nothing once the pinned version is the one being served", async () => {
+    sessionStorage.setItem("appVersionRedirectPending", "v5.1.0");
+    const { redirected, to } = await load("v5.1.0", "/v5.1.0/tabs/orders", "v5.1.0");
+
+    expect(redirected).toBe(false);
+    expect(to).toBeUndefined();
+    // The landed attempt must not be recorded as a failure, or a later rollback here would be refused.
+    expect(sessionStorage.getItem("appVersionRedirectFailed")).toBeNull();
+  });
+
+  it("moves to a newly pinned version when the backend changes", async () => {
+    const { redirected, to } = await load("v5.1.0", "/v5.1.0/tabs/orders", "v5.2.0");
+
+    expect(redirected).toBe(true);
+    expect(to).toContain("/v5.2.0/tabs/orders");
+  });
+
+  it("converges to root — without oscillating — when the pinned version isn't deployed", async () => {
+    // 1. Root build asks for v5.1.0.
+    const first = await load("", "/", "v5.1.0");
+    expect(first.to).toContain("/v5.1.0/");
+
+    // 2. The host's catch-all served the root bundle at the versioned path, so the attempt didn't land.
+    const second = await load("", "/v5.1.0/", "v5.1.0");
+    expect(second.redirected).toBe(true);
+    expect(second.to).toBe("/");
+    expect(sessionStorage.getItem("appVersionRedirectFailed")).toBe("v5.1.0");
+
+    // 3. Back at root: v5.1.0 is known-unreachable, so we stay put instead of bouncing back to it.
+    const third = await load("", "/", "v5.1.0");
+    expect(third.redirected).toBe(false);
+    expect(third.to).toBeUndefined();
+  });
+
+  it("still honours a different version after one proved unreachable", async () => {
+    sessionStorage.setItem("appVersionRedirectFailed", "v5.1.0");
+    const { redirected, to } = await load("", "/", "v5.2.0");
+
+    expect(redirected).toBe(true);
+    expect(to).toContain("/v5.2.0/");
+  });
+
+  it("no-ops while the version is still unresolved", async () => {
+    setBuildVersion("");
+    setUrl("/");
+    const { useAuth, accxuiConfig } = await loadUseAuth();
+    accxuiConfig.value.appVersion = undefined;
+
+    expect(useAuth().checkAppVersionRedirect()).toBe(false);
+  });
+});
diff --git a/common/composables/useAuth.ts b/common/composables/useAuth.ts
index 038e4e0..6fc4c01 100644
--- a/common/composables/useAuth.ts
+++ b/common/composables/useAuth.ts
@@ -19,6 +19,78 @@ const isMoquiOmsRef = ref(commonUtil.isMoqui())
 const token = ref(cookieHelper().get("token") || "")
 const expirationTime = ref(cookieHelper().get("expirationTime") || "")
 
+// Loop protection for version redirects, scoped to the tab: sessionStorage survives the reload a redirect
+// causes, which is exactly the span we need to reason across, and a new tab starts clean. Access is
+// guarded because embedded webviews can restrict storage — losing loop protection must never block the
+// redirect itself.
+const PENDING_VERSION_KEY = "appVersionRedirectPending"
+const FAILED_VERSIONS_KEY = "appVersionRedirectFailed"
+
+const readSession = (key: string) => {
+  try {
+    return sessionStorage.getItem(key)
+  } catch (e) {
+    return null
+  }
+}
+
+const writeSession = (key: string, value: string) => {
+  try {
+    sessionStorage.setItem(key, value)
+  } catch (e) {
+    // Storage unavailable — proceed without loop protection rather than stranding the user.
+  }
+}
+
+const clearSession = (key: string) => {
+  try {
+    sessionStorage.removeItem(key)
+  } catch (e) {
+    // As above.
+  }
+}
+
+const getFailedVersions = () => (readSession(FAILED_VERSIONS_KEY) || "").split(",").filter(Boolean)
+
+// A redirect issued during THIS page load. window.location.replace() doesn't stop the current task, and
+// several callers can run before the navigation happens (Login.vue resolves the version from more than
+// one path; the router guard fires on every navigation). They must be told a redirect is already in
+// flight, not treated as a fresh attempt.
+let versionRedirectIssued = false
+
+// Settle the previous page load's attempt, once per load. If the version we redirected to isn't the
+// version actually being served, the host isn't serving what the OMS named: record it so we stop
+// targeting it, otherwise root and that version bounce off each other forever. A redirect that landed
+// records nothing, so a later backend change — including a rollback to a version we already ran — still
+// redirects normally.
+let versionAttemptReconciled = false
+
+const reconcileVersionAttempt = () => {
+  if (versionAttemptReconciled) return
+  versionAttemptReconciled = true
+
+  const pending = readSession(PENDING_VERSION_KEY)
+  if (pending === null) return
+  clearSession(PENDING_VERSION_KEY)
+
+  // Redirecting to root is the fallback and always lands, so only a named version can fail.
+  if (!pending || pending === commonUtil.getBuildVersion()) return
+
+  const failed = getFailedVersions()
+  if (!failed.includes(pending)) writeSession(FAILED_VERSIONS_KEY, [...failed, pending].join(","))
+  logger.error(`App version "${pending}" is not served by this host; falling back to the root build for this session.`)
+}
+
+// Pinia isn't active at module-import time (and never in a bare unit context), so resolve the store
+// defensively — mirrors commonUtil's own guarded accessor.
+const getEmbeddedAppStoreSafe = () => {
+  try {
+    return useEmbeddedAppStore()
+  } catch (e) {
+    return undefined
+  }
+}
+
 export function useAuth() {
   const getDuration = (expirationTime?: any) => {
     const expiry = (expirationTime !== undefined && expirationTime !== null) ? expirationTime : commonUtil.getTokenExpiration();
@@ -58,9 +130,19 @@ export function useAuth() {
     let isOmsVerified = false;
     let isUserVerified = false;
 
-    if (!token.value || !expirationTime.value) return false;
+    // An embedded (Shopify) session keeps its credentials in the embedded-app store, not in cookies:
+    // document.cookie is unreliable inside Shopify's cross-origin iframe, since SameSite=Lax cookies
+    // aren't sent in a third-party context. So read the store first and fall back to the cookie-backed
+    // refs for standalone sessions — those stay reactive because updateToken() writes them. Reading the
+    // store's getters here (rather than commonUtil.getToken(), which resolves the cookie non-reactively)
+    // is what keeps this computed invalidating on both paths.
+    const embeddedAppStore = getEmbeddedAppStoreSafe();
+    const currentToken = embeddedAppStore?.getToken || token.value;
+    const currentExpiration = embeddedAppStore?.getTokenExpiration || expirationTime.value;
+
+    if (!currentToken || !currentExpiration) return false;
 
-    const expiry = Number(expirationTime.value);
+    const expiry = Number(currentExpiration);
     if(expiry) {
       const currTime = DateTime.now().toMillis();
       isTokenExpired = expiry < currTime;
@@ -201,9 +283,10 @@ export function useAuth() {
     localStorage.removeItem("requestedPagePath")
 
     if (commonUtil.isAppEmbedded()) {
-      const embeddedAppStore = useEmbeddedAppStore();
-      redirectionUrl = window.location.origin + '/shopify-login?shop=' + embeddedAppStore.shop + '&host=' + embeddedAppStore.host + '&embedded=1';
-      embeddedAppStore.$reset();
+      // Build the entry URL before the reset, while shop/host are still in the store, and let the helper
+      // keep the version segment of the path we're on.
+      redirectionUrl = commonUtil.getEmbeddedAppEntryUrl();
+      useEmbeddedAppStore().$reset();
     }
 
     if(redirectionUrl) {
@@ -277,17 +360,49 @@ export function useAuth() {
   // (not resolved yet — acting would risk a premature/looping redirect) or already canonical. Shared by
   // the router guard (every navigation) and fetchAppVersion (right after it resolves the version).
   const checkAppVersionRedirect = () => {
+    // A redirect is already in flight for this page load: report it as such so callers bail, rather than
+    // letting a second caller treat it as a fresh attempt (and, by returning false, let an in-app
+    // navigation proceed and supersede the pending page load).
+    if(versionRedirectIssued) return true;
+
     const configuredVersion = accxuiConfig.value.appVersion;
     if(configuredVersion === undefined) return false;
 
-    const canonicalPath = getCanonicalPath(configuredVersion, window.location.pathname);
+    reconcileVersionAttempt();
+
+    // Hosting's catch-all rewrite serves the root bootstrap for any version it doesn't have, so the URL
+    // can claim a version this bundle isn't. Getting back onto a path this deployment can actually serve
+    // takes priority over honouring the OMS's answer — otherwise the versioned path matches no route and
+    // renders a blank outlet. The loop guard below then stops us being sent straight back.
+    const undeployedVersion = commonUtil.getUndeployedVersion();
+    // A version already proven unreachable this session is never targeted again — otherwise root and that
+    // version bounce off each other forever, and there is no address bar to escape from in Shopify POS.
+    const wantedVersion = getFailedVersions().includes(configuredVersion) ? "" : configuredVersion;
+    const targetVersion = undeployedVersion ? "" : wantedVersion;
+
+    const canonicalPath = getCanonicalPath(targetVersion, window.location.pathname);
     if(canonicalPath === null) return false;
 
+    // Remember what we're about to try so the next load can tell whether it landed.
+    writeSession(PENDING_VERSION_KEY, targetVersion);
+    versionRedirectIssued = true;
+
+    // A version switch is always a full page load, which destroys the live App Bridge instance. An
+    // embedded session can only rebuild it by going through /shopify-login, so send it there (carrying
+    // shop/host) instead of to the canonical path — landing anywhere else leaves it with no bridge.
+    if(commonUtil.isAppEmbedded()) {
+      window.location.replace(commonUtil.getEmbeddedAppEntryUrl(targetVersion));
+      return true;
+    }
+
     window.location.replace(`${canonicalPath}${window.location.search}${window.location.hash}`);
     return true;
   };
 
-  const fetchAppVersion = async () => {
+  // `baseURL` lets the caller name the backend to ask before the session knows its own — the embedded
+  // flow resolves the version from the shop's Maarg instance ahead of login. Returns true when a redirect
+  // was issued, so callers can stop instead of continuing into a page that is being torn down.
+  const fetchAppVersion = async (baseURL?: string) => {
     try {
       // appId (endpoint path) and environmentTypeId come from the single multi-version config object
       // (VITE_APP_VERSION_CONFIG), so they match this deployment's app rather than being hardcoded.
@@ -298,7 +413,8 @@ export function useAuth() {
         params: {
           appId,
           environmentTypeId
-        }
+        },
+        ...(baseURL ? { baseURL } : {})
       });
 
       const appVersions = Array.isArray(resp.data) ? resp.data : resp.data?.docs;
@@ -306,13 +422,15 @@ export function useAuth() {
 
       // Persist the OMS's answer, then move the Login page onto that version's canonical URL.
       accxuiConfig.value.appVersion = configuredVersion || "";
-      checkAppVersionRedirect();
+      return checkAppVersionRedirect();
     } catch (error) {
-      // The call failed outright (endpoint unreachable/absent, or the config JSON was unparseable).
-      // Resolve to "" so the app runs unversioned at root instead of staying unresolved.
-      accxuiConfig.value.appVersion = "";
-      checkAppVersionRedirect();
+      // The call failed outright (endpoint unreachable/absent, or the config JSON was unparseable). Don't
+      // demote a session already running a version this deployment serves — a transient OMS outage must
+      // not move every merchant onto the root build. Otherwise resolve to "" and run unversioned at root.
+      const runningVersion = commonUtil.getBuildVersion();
+      accxuiConfig.value.appVersion = runningVersion && !commonUtil.getUndeployedVersion() ? runningVersion : "";
       logger.error(error);
+      return checkAppVersionRedirect();
     }
   };
 
diff --git a/common/composables/useShopify.ts b/common/composables/useShopify.ts
index 81b0272..8274480 100644
--- a/common/composables/useShopify.ts
+++ b/common/composables/useShopify.ts
@@ -1,5 +1,6 @@
 import { Scanner, Features, Group, Redirect } from '@shopify/app-bridge/actions';
 import { useEmbeddedAppStore } from "../store/embeddedApp";
+import { commonUtil } from "../utils/commonUtil";
 import { createApp } from "@shopify/app-bridge";
 import { getSessionToken } from "@shopify/app-bridge-utils";
 import api from '../core/remoteApi';
@@ -136,7 +137,9 @@ const openPosScanner = (): Promise<any> => {
         url: `app-bridge/login`,
         method: 'post',
         data: loginPayload,
-        baseURL: `${maargUrl}/rest/s1/`
+        // Route through getMaargURL so a shop config holding a bare instance name ("demo") resolves the
+        // same way as a full URL — string-concatenating /rest/s1/ onto it produced an invalid base.
+        baseURL: commonUtil.getMaargURL(maargUrl)
       });
 
       if (!loginResp.data.token || !loginResp.data.omsInstanceUrl) {
diff --git a/common/store/embeddedApp.ts b/common/store/embeddedApp.ts
index d007936..c8078e3 100644
--- a/common/store/embeddedApp.ts
+++ b/common/store/embeddedApp.ts
@@ -61,5 +61,8 @@ export const useEmbeddedAppStore = defineStore('embeddedApp', {
       this.token.expiration = expiration;
     }
   },
-  persist: true
+  // `shopifyAppBridge` must never be persisted: it is a live App Bridge client whose methods are
+  // dropped by JSON serialization, so rehydrating it yields a truthy but non-functional object that
+  // outlives the embedded session it belonged to. It is recreated by appBridgeLogin on every load.
+  persist: { omit: ["shopifyAppBridge"] }
 });
\ No newline at end of file
diff --git a/common/utils/commonUtil.embeddedApp.spec.ts b/common/utils/commonUtil.embeddedApp.spec.ts
new file mode 100644
index 0000000..d5d9b98
--- /dev/null
+++ b/common/utils/commonUtil.embeddedApp.spec.ts
@@ -0,0 +1,141 @@
+// @vitest-environment jsdom
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createPinia, setActivePinia } from "pinia";
+import { commonUtil } from "./commonUtil";
+import { useEmbeddedAppStore } from "../store/embeddedApp";
+
+// jsdom is always top-level; embedded detection is gated on being framed, so tests opt in explicitly.
+const setFramed = (framed: boolean) => {
+  Object.defineProperty(window, "top", {
+    configurable: true,
+    get: () => (framed ? ({} as Window) : window)
+  });
+};
+
+const setUrl = (url: string) => window.history.replaceState({}, "", url);
+
+describe("commonUtil.isAppEmbedded", () => {
+  beforeEach(() => {
+    setActivePinia(createPinia());
+    setUrl("/");
+  });
+
+  afterEach(() => {
+    setFramed(false);
+    vi.unstubAllEnvs();
+  });
+
+  it("is false at top level even when a previous embedded session left shop/host persisted", () => {
+    setFramed(false);
+    const store = useEmbeddedAppStore();
+    store.shop = "demo.myshopify.com";
+    store.host = "aG9zdA==";
+
+    expect(commonUtil.isAppEmbedded()).toBe(false);
+  });
+
+  it("is true when framed with Shopify launch params in the URL, before any login", () => {
+    setFramed(true);
+    setUrl("/shopify-login?shop=demo.myshopify.com&host=aG9zdA==&embedded=1");
+
+    expect(commonUtil.isAppEmbedded()).toBe(true);
+  });
+
+  it("stays true after client-side navigation has dropped the launch params", () => {
+    setFramed(true);
+    const store = useEmbeddedAppStore();
+    store.shop = "demo.myshopify.com";
+    store.host = "aG9zdA==";
+    setUrl("/tabs/orders");
+
+    expect(commonUtil.isAppEmbedded()).toBe(true);
+  });
+
+  it("is false when framed by something that is not Shopify", () => {
+    setFramed(true);
+    setUrl("/tabs/orders");
+
+    expect(commonUtil.isAppEmbedded()).toBe(false);
+  });
+
+  it("does not depend on the App Bridge instance, which no longer survives a reload", () => {
+    setFramed(true);
+    setUrl("/shopify-login?shop=demo.myshopify.com&host=aG9zdA==");
+    const store = useEmbeddedAppStore();
+    store.shopifyAppBridge = null;
+
+    expect(commonUtil.isAppEmbedded()).toBe(true);
+  });
+});
+
+describe("commonUtil.getUndeployedVersion", () => {
+  const stubBuildVersion = (buildVersion: string) =>
+    vi.stubEnv("VITE_APP_VERSION_CONFIG", JSON.stringify({ appId: "BOPIS", environmentTypeId: "AppEnvDev", buildVersion }));
+
+  afterEach(() => vi.unstubAllEnvs());
+
+  it("detects the catch-all fall-through: URL names a version the loaded bundle isn't", () => {
+    stubBuildVersion("");
+    setUrl("/v5.1.0/shopify-login?shop=demo.myshopify.com");
+
+    expect(commonUtil.getUndeployedVersion()).toBe("v5.1.0");
+  });
+
+  it("is null when the served bundle matches the version in the URL", () => {
+    stubBuildVersion("v5.1.0");
+    setUrl("/v5.1.0/shopify-login");
+
+    expect(commonUtil.getUndeployedVersion()).toBeNull();
+  });
+
+  it("is null on an unversioned path", () => {
+    stubBuildVersion("");
+    setUrl("/shopify-login");
+
+    expect(commonUtil.getUndeployedVersion()).toBeNull();
+  });
+
+  it("is null when the version config is missing or unparseable", () => {
+    vi.stubEnv("VITE_APP_VERSION_CONFIG", "not-json");
+    setUrl("/shopify-login");
+
+    expect(commonUtil.getUndeployedVersion()).toBeNull();
+  });
+});
+
+describe("commonUtil.getEmbeddedAppEntryUrl", () => {
+  beforeEach(() => {
+    setActivePinia(createPinia());
+  });
+
+  it("uses the launch params when they are still on the URL (pre-login)", () => {
+    setUrl("/shopify-login?shop=demo.myshopify.com&host=aG9zdA==&embedded=1");
+
+    const url = new URL(commonUtil.getEmbeddedAppEntryUrl("v5.1.0"));
+    expect(url.pathname).toBe("/v5.1.0/shopify-login");
+    expect(url.searchParams.get("shop")).toBe("demo.myshopify.com");
+    expect(url.searchParams.get("host")).toBe("aG9zdA==");
+    expect(url.searchParams.get("embedded")).toBe("1");
+  });
+
+  it("falls back to the store mid-session, once the params are gone", () => {
+    const store = useEmbeddedAppStore();
+    store.shop = "demo.myshopify.com";
+    store.host = "aG9zdA==";
+    setUrl("/tabs/orders");
+
+    const url = new URL(commonUtil.getEmbeddedAppEntryUrl(""));
+    expect(url.pathname).toBe("/shopify-login");
+    expect(url.searchParams.get("shop")).toBe("demo.myshopify.com");
+  });
+
+  it("keeps the version segment currently being served when none is passed", () => {
+    const store = useEmbeddedAppStore();
+    store.shop = "demo.myshopify.com";
+    store.host = "aG9zdA==";
+    setUrl("/v5.1.0/tabs/orders");
+
+    expect(new URL(commonUtil.getEmbeddedAppEntryUrl()).pathname).toBe("/v5.1.0/shopify-login");
+  });
+});
diff --git a/common/utils/commonUtil.ts b/common/utils/commonUtil.ts
index bd192c1..6fb2bb9 100644
--- a/common/utils/commonUtil.ts
+++ b/common/utils/commonUtil.ts
@@ -9,6 +9,7 @@ import Encoding from 'encoding-japanese';
 import { CronExpressionParser as cronParser } from "cron-parser";
 import cronstrue from "cronstrue"
 import { useEmbeddedAppStore } from "../store/embeddedApp";
+import { getVersionedPathInfo } from "./appVersionUtil";
 
 export interface JsonToCsvOption {
   parse?: object | null;
@@ -365,8 +366,11 @@ const telecomCode = {
   "ZW": "+263"
 } as any;
 
-const getMaargURL = () => {
-  const maarg = getEmbeddedAppStoreSafe().maarg || cookieHelper().get("maarg")
+// `maargInstance` lets a caller resolve a URL for an instance that isn't (yet) the session's own —
+// the embedded flow needs this to reach a shop's Maarg from VITE_SHOPIFY_SHOP_CONFIG before login
+// has populated the store.
+const getMaargURL = (maargInstance?: string) => {
+  const maarg = maargInstance || getEmbeddedAppStoreSafe().maarg || cookieHelper().get("maarg")
   let maargURL = ""
   if (maarg) {
     maargURL = maarg.startsWith('http') ? maarg.includes('/rest/s1') ? maarg : `${maarg}/rest/s1/` : `https://${maarg}.hotwax.io/rest/s1/`;
@@ -379,6 +383,7 @@ const getMaargBaseURL = () => {
 }
 
 const getOmsURL = (isMoquiOnly = isMoqui()) => {
+  console.log('getEmbeddedAppStoreSafe().oms', getEmbeddedAppStoreSafe().oms)
   const oms = getEmbeddedAppStoreSafe().oms || cookieHelper().get("oms")
   // VITE_OMS_TYPE=MOQUI → use Moqui REST paths (/rest/s1/)
   // VITE_OMS_TYPE unset  → use OFBiz paths (/api/)  [default, backward-compatible]
@@ -410,8 +415,60 @@ const getTokenExpiration = () => {
   return getEmbeddedAppStoreSafe().getTokenExpiration || cookieHelper().get("expirationTime")
 }
 
+// "Is this page running inside Shopify right now?"
+//
+// Deliberately NOT derived from the App Bridge instance: that object is rebuilt on every page load,
+// and a persisted copy is both method-less and outlives the real session — which used to leave every
+// later standalone visit on the same origin permanently reporting as embedded.
+//
+// Being in a frame is the one signal that cannot survive a reload, so it gates everything. Shopify's
+// launch params identify the entry page; once client-side navigation has dropped them, the shop/host
+// captured in the store carries the rest of the session.
 const isAppEmbedded = () => {
-  return !!getEmbeddedAppStoreSafe().shopifyAppBridge
+  if (typeof window === "undefined" || window.top === window.self) return false
+  const store = getEmbeddedAppStoreSafe()
+  if (store.shop && store.host) return true
+  const params = new URLSearchParams(window.location.search)
+  return !!(params.get("host") || params.get("embedded"))
+}
+
+// The version segment this bundle was BUILT as ("" for the unversioned root bootstrap).
+const getBuildVersion = () => {
+  try {
+    return (JSON.parse(import.meta.env.VITE_APP_VERSION_CONFIG || "{}").buildVersion || "") as string
+  } catch (e) {
+    return ""
+  }
+}
+
+// Returns the version named in the URL when the host did not actually serve it, else null.
+//
+// Hosting's catch-all rewrite falls back to the root bootstrap for any path it can't resolve, so a URL
+// carrying an undeployed version silently loads the unversioned bundle instead. That bundle's router
+// base is "/", so the versioned path matches no route and renders a blank outlet — with no address bar
+// to recover from inside Shopify POS. Comparing the URL's version against the version this bundle was
+// built as detects exactly that fall-through.
+const getUndeployedVersion = () => {
+  if (typeof window === "undefined") return null
+  console.log('getVersionedPathInfo', getVersionedPathInfo(window.location.pathname))
+  const { version } = getVersionedPathInfo(window.location.pathname)
+  if (!version || version === getBuildVersion()) return null
+  return version
+}
+
+// Embedded sessions must always re-enter through /shopify-login: it is the only route that rebuilds
+// App Bridge, and every other landing spot leaves the session with a bridge that no longer exists.
+// `version` defaults to the version segment currently being served so a versioned deployment isn't
+// silently dropped to root; pass one explicitly to move to a different version.
+const getEmbeddedAppEntryUrl = (version?: string) => {
+  const store = getEmbeddedAppStoreSafe()
+  const params = new URLSearchParams(window.location.search)
+  // Pre-login the launch params are all we have; mid-session they're gone and the store holds them.
+  const shop = params.get("shop") || store.shop || ""
+  const host = params.get("host") || store.host || ""
+  const segment = version !== undefined ? version : (getVersionedPathInfo(window.location.pathname).version || "")
+  const query = new URLSearchParams({ shop, host, embedded: "1" })
+  return `${window.location.origin}${segment ? `/${segment}` : ""}/shopify-login?${query.toString()}`
 }
 
 const statusColor = {
@@ -984,11 +1041,14 @@ export const commonUtil = {
   getDateTimeWithOrdinalSuffix,
   getDateWithOrdinalSuffix,
   getFacilityChipLabel,
+  getBuildVersion,
+  getEmbeddedAppEntryUrl,
   getFeature,
   getFeatures,
   getIdentificationId,
   getMaargBaseURL,
   getMaargURL,
+  getUndeployedVersion,
   getNextExecutionTime,
   getOMSInstanceName,
   getOmsURL,
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 722b076..3fa3ead 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -13848,4 +13848,4 @@ snapshots:
 
   zod@3.25.76: {}
 
-  zod@4.3.6: {}
+  zod@4.3.6: {}
\ No newline at end of file