@maytes/checkout-button 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,37 +1,91 @@
 # Changelog
 
+## 1.1.0
+
+### Minor Changes
+
+- [#11](https://github.com/kttipay/maytes-checkout-button/pull/11) [`def33e0`](https://github.com/kttipay/maytes-checkout-button/commit/def33e010bf23b11bc94871e236d35a65deb825e) Thanks [@kos-maytes](https://github.com/kos-maytes)! - `renderButton`'s default `mode` is now `'popup'` instead of `'redirect'`. Pass `mode: 'redirect'` explicitly to keep the previous same-window navigation behavior. Popup mode already falls back to same-window redirect on mobile viewports and when the popup is blocked, so this only changes the desktop no-`mode`-specified path.
+
+- [#8](https://github.com/kttipay/maytes-checkout-button/pull/8) [`a6d85e2`](https://github.com/kttipay/maytes-checkout-button/commit/a6d85e23653e340b7a850ad61e882ec2f6cef5d2) Thanks [@kttipaydiogocavaiar](https://github.com/kttipaydiogocavaiar)! - The button never loads the hosted checkout inside an iframe any more. When the button is rendered inside a frame (for example a booking widget embedded on the merchant's page), a phone or a narrow frame used to take the same-window fallback and navigate the frame itself, so the checkout ran as a cross-site iframe where its session cookie is rejected and sign-in ended on "Your session expired". The button now measures the top-level window (or the screen when the top window is cross-origin) and navigates the top-level window; if the browser refuses, it opens the checkout in a new tab; if both are refused, it dispatches `maytes:checkout-failed` with `reason: 'navigation-blocked'` and leaves the button usable. `maytes:checkout-redirected` now carries `detail.target` (`'self' | 'top' | 'tab'`). `redirectToCheckout()` follows the same rule and throws `MaytesError` when it cannot leave the frame. Merchants who deliberately relied on in-frame navigation will see the top-level page change instead; render the button in the top-level page if that is not wanted.
+
+<!-- @hash-sri-start -->
+
+**SRI hashes** (use these in `<script integrity="..." crossorigin="anonymous">`):
+
+```
+checkout-button.js   sha384-+hQ9khxZbVEUhR685659hqmPyN/3RYfbNEI7itac3SkcyYor/94/0mIwVnVwMa8M
+checkout-button.mjs  sha384-1areqNcTs9sephTl6S1+sOgACv1/NqIqXBG0Ej11/4OfSDcN92GvQvhhu4K76R5i
+checkout-button.cjs  sha384-4c1JuweT47cnpvGlQfv+qQw/3CS+7o2/Dg4qQnLiWM1GDChhHQo0dT+z8705Hy50
+```
+
+**SemVer CDN links** (readable production pins; use with the SRI hashes above):
+
+- [checkout-button.js](https://js.maytes.co/v1.1.0/checkout-button.js)
+- [checkout-button.mjs](https://js.maytes.co/v1.1.0/checkout-button.mjs)
+- [checkout-button.cjs](https://js.maytes.co/v1.1.0/checkout-button.cjs)
+
+**Hashed CDN links** (byte-level production pins; use with the SRI hashes above):
+
+- [checkout-button.811263f9.js](https://js.maytes.co/checkout-button.811263f9.js)
+- [checkout-button.f96c49ee.mjs](https://js.maytes.co/checkout-button.f96c49ee.mjs)
+- [checkout-button.178d8394.cjs](https://js.maytes.co/checkout-button.178d8394.cjs)
+
+<!-- @hash-sri-end -->
+## 1.0.1
+
+### Patch Changes
+
+- [#2](https://github.com/kttipay/maytes-checkout-button/pull/2) [`e5b8e63`](https://github.com/kttipay/maytes-checkout-button/commit/e5b8e6399dd33e0b3b24131d9f808ebd8eae44ef) Thanks [@kos-maytes](https://github.com/kos-maytes)! - `destroy()` no longer force-closes a popup that has already navigated to the checkout URL. Previously it would close any open popup unconditionally, which could kill an in-progress checkout if the host page called `destroy()` while the popup was still completing (e.g. reacting to its own payment-status polling). A popup is now only auto-closed while it's still on the blank loading screen, before checkout has started.
+
+<!-- @hash-sri-start -->
+
+**SRI hashes** (use these in `<script integrity="..." crossorigin="anonymous">`):
+
+```
+checkout-button.js   sha384-scp0qo7rcOJGuuI+gpadCOUQMn7g7hx3lqY9p7Xr2fd7/9Sb/L79DaHKStTTX7Ko
+checkout-button.mjs  sha384-5+TplHKGAk10ajWGdKwpG3pKutLD+v3cOYqtPEvRNLWudyOELPUKuU6sqlAhuy1h
+checkout-button.cjs  sha384-+O2S6KfO4Pc0VEvL+kTsFzxU14W4EILV6+U5mAdW8X43Xm8Qk1aV0y/KbM3Fnp9M
+```
+
+**SemVer CDN links** (readable production pins; use with the SRI hashes above):
+
+- [checkout-button.js](https://js.maytes.co/v1.0.1/checkout-button.js)
+- [checkout-button.mjs](https://js.maytes.co/v1.0.1/checkout-button.mjs)
+- [checkout-button.cjs](https://js.maytes.co/v1.0.1/checkout-button.cjs)
+
+**Hashed CDN links** (byte-level production pins; use with the SRI hashes above):
+
+- [checkout-button.8c71493e.js](https://js.maytes.co/checkout-button.8c71493e.js)
+- [checkout-button.81ea2037.mjs](https://js.maytes.co/checkout-button.81ea2037.mjs)
+- [checkout-button.6d259930.cjs](https://js.maytes.co/checkout-button.6d259930.cjs)
+
+<!-- @hash-sri-end -->
+
 ## 1.0.0
 
-### Major Changes
+First public release on npm.
 
-- [`c17857f`](https://github.com/kttipay/checkout-button/commit/c17857fcb38bf045ae89fde207a1859ae12214e3) Thanks [@Merkost](https://github.com/Merkost)! - First public release on npm.
+### Major Changes
 
-  The button is now installable as `@maytes/checkout-button` alongside the existing
-  CDN `<script>` distribution — same package, same API, both fed from this source.
+- **`@maytes/checkout-button` is now installable via npm**, alongside the existing CDN `<script>` distribution — same package, same API, both built from this repo.
 
-  Framework apps (React, Angular, Vue, Svelte, plain bundled JS) should import the
-  factory directly:
+  Framework apps (React, Angular, Vue, Svelte, plain bundled JS) should import the factory directly:
 
   ```ts
   import { Maytes } from "@maytes/checkout-button";
   ```
 
-  That removes the script-injection dance those apps previously needed: no
-  `window.Maytes` global to feature-detect, no polling for the CDN script to
-  finish loading before mounting, and no hand-written `declare global` typings —
-  the package ships its own `.d.ts`.
+  That removes the script-injection dance those apps previously needed: no `window.Maytes` global to feature-detect, no polling for the CDN script to finish loading before mounting, and no hand-written `declare global` typings — the package ships its own `.d.ts`.
 
-  The `<script>` tag remains the right integration for no-build sites and jQuery,
-  and is unchanged: pin a SemVer or content-hash URL with SRI in every environment,
-  development included.
+  The `<script>` tag remains the right integration for no-build sites and jQuery, and is unchanged: pin a SemVer or content-hash URL with SRI in every environment, development included.
 
 ### Minor Changes
 
-- [`c17857f`](https://github.com/kttipay/checkout-button/commit/c17857fcb38bf045ae89fde207a1859ae12214e3) Thanks [@Merkost](https://github.com/Merkost)! - Brand the checkout button with the Maytes wordmark logo and maroon brand color, and make its size auto-scale from a single `--maytes-button-font-size` custom property (default 14px).
+- Branded the checkout button with the Maytes wordmark logo and maroon brand colour, and made its size auto-scale from a single `--maytes-button-font-size` custom property (default 14px).
 
-- [`c17857f`](https://github.com/kttipay/checkout-button/commit/c17857fcb38bf045ae89fde207a1859ae12214e3) Thanks [@Merkost](https://github.com/Merkost)! - Add a launch `mode` to `renderButton` and a branded popup loading screen.
+- Added a launch `mode` to `renderButton` and a branded popup loading screen.
 
-  - `renderButton(container, { mode })` accepts `'redirect'` (new default) or `'popup'`. Invalid values throw `MaytesError(CONFIG)`.
+  - `renderButton(container, { mode })` accepts `'redirect'` (default) or `'popup'`. Invalid values throw `MaytesError(CONFIG)`.
   - `mode: 'popup'` opens a blank popup synchronously on click (preserving the user gesture so browsers do not block it), paints a branded Maytes loading screen into it (logo, spinner, `role="status"`/`aria-live`, a slow-network message that appears after ~8s, and a `prefers-reduced-motion` guard), then `popup.location.replace(url)`s once `createCheckout` resolves.
   - On mobile viewports `mode: 'popup'` behaves as a same-window redirect.
   - The misleading `maytes:checkout-failed` (`reason: 'popup-blocked'`) is replaced by a new `maytes:checkout-redirected` event (`detail.url`). A same-window redirect is a normal outcome, not a failure. The `failed` event now only carries `'create-checkout-rejected'` | `'invalid-shape'`.
@@ -40,21 +94,21 @@
 
 ### Patch Changes
 
-- [`c17857f`](https://github.com/kttipay/checkout-button/commit/c17857fcb38bf045ae89fde207a1859ae12214e3) Thanks [@Merkost](https://github.com/Merkost)! - Harden the checkout button popup lifecycle:
-
-  - Open the hosted checkout URL exactly once (it was navigated twice — `window.open(url)` plus a redundant `location.href` write).
-  - Give each SDK instance a unique popup window name so concurrent merchant tabs no longer share or steal one popup; this also removes the cross-origin `SecurityError` that could hang the overlay.
-  - `destroy()` now detaches every button's click listener and is ignored by an in-flight `createCheckout` that resolves after teardown (no late popup).
-  - Remove the cloned overlay `<style>` from the top document on teardown (same-origin iframe embeds).
-  - Scope the injected style marker and ref-count by SDK version so two SDK versions on one page don't clash.
-  - Clear the overlay immediately when the shopper presses Escape (was delayed up to one poll interval).
-  - Validate that a merchant-supplied `checkoutUrl` is an `http(s)` URL before opening it — matching the protocol guard already applied to the constructed URL, so a buggy backend can't turn the button into a `javascript:`/`data:` popup.
+**Popup lifecycle**
 
-- [`c17857f`](https://github.com/kttipay/checkout-button/commit/c17857fcb38bf045ae89fde207a1859ae12214e3) Thanks [@Merkost](https://github.com/Merkost)! - Take the Maytes brand colours from the design foundation (`kttipay/designsystem` v0.3.0, vendored by `npm run sync:foundation` and pinned in `foundation.lock.json`) instead of hand-written hexes. The only rendered change: the button's hover shade is now the foundation's burgundy/700 `#3B021D` (was `#3A021C`).
+- Open the hosted checkout URL exactly once (it was navigated twice — `window.open(url)` plus a redundant `location.href` write).
+- Give each SDK instance a unique popup window name so concurrent merchant tabs no longer share or steal one popup; this also removes the cross-origin `SecurityError` that could hang the overlay.
+- `destroy()` now detaches every button's click listener and is ignored by an in-flight `createCheckout` that resolves after teardown (no late popup).
+- Remove the cloned overlay `<style>` from the top document on teardown (same-origin iframe embeds).
+- Scope the injected style marker and ref-count by SDK version so two SDK versions on one page don't clash.
+- Clear the overlay immediately when the shopper presses Escape (was delayed up to one poll interval).
+- Validate that a merchant-supplied `checkoutUrl` is an `http(s)` URL before opening it — matching the protocol guard already applied to the constructed URL, so a buggy backend can't turn the button into a `javascript:`/`data:` popup.
+- Fixed a race in `mode: 'popup'`: if the shopper closed the popup while `createCheckout` was still in flight, the SDK would try to navigate (or, on rejection, report a failure for) a window that was already gone once the promise settled — on top of the `maytes:checkout-closed` event the close-poll had already fired. Both the success and rejection paths now check whether the popup is still open before acting, so closing the popup early produces exactly one `checkout-closed` event and nothing else.
 
-- [`c17857f`](https://github.com/kttipay/checkout-button/commit/c17857fcb38bf045ae89fde207a1859ae12214e3) Thanks [@Merkost](https://github.com/Merkost)! - Serve the CDN (IIFE) bundle minified, with a sourcemap. The ESM/CJS npm bundles stay unminified so the consumer's bundler can tree-shake them.
+**Design & build**
 
-- [`c17857f`](https://github.com/kttipay/checkout-button/commit/c17857fcb38bf045ae89fde207a1859ae12214e3) Thanks [@Merkost](https://github.com/Merkost)! - Fix a race in `mode: 'popup'`: if the shopper closed the popup while `createCheckout` was still in flight, the SDK would try to navigate (or, on rejection, report a failure for) a window that was already gone once the promise settled — on top of the `maytes:checkout-closed` event the close-poll had already fired. Both the success and rejection paths now check whether the popup is still open before acting, so closing the popup early produces exactly one `checkout-closed` event and nothing else.
+- Brand colours now come from the design foundation (`kttipay/designsystem` v0.3.0, vendored by `npm run sync:foundation` and pinned in `foundation.lock.json`) instead of hand-written hexes. The only rendered change: the button's hover shade is now the foundation's burgundy/700 `#3B021D` (was `#3A021C`).
+- The CDN (IIFE) bundle now ships minified, with a sourcemap. The ESM/CJS npm bundles stay unminified so the consumer's bundler can tree-shake them.
 
 This project follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 

package/README.md

@@ -1,28 +1,85 @@
-# @maytes/checkout-button
+<p align="center">
+  <img src=".github/logo.svg" height="32" alt="Maytes">
+</p>
 
-Drop-in **Split with Maytes** button. Renders a button and launches the Maytes-hosted checkout. Default mode is same-window redirect; `mode: 'popup'` opts desktop browsers into a centered popup with a branded loader and redirect fallback on mobile or when blocked.
+<h1 align="center">@maytes/checkout-button</h1>
+
+<p align="center">
+  Drop-in <strong>Split with Maytes</strong> button — one script or import, and shoppers can split any checkout with friends.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@maytes/checkout-button"><img alt="npm version" src="https://img.shields.io/npm/v/@maytes/checkout-button?color=4A0324&label=npm"></a>
+  <a href="https://bundlephobia.com/package/@maytes/checkout-button"><img alt="bundle size" src="https://img.shields.io/bundlephobia/minzip/@maytes/checkout-button?color=FE572A&label=gzip"></a>
+  <a href="./CHANGELOG.md"><img alt="provenance" src="https://img.shields.io/badge/npm-provenance-4A0324"></a>
+  <a href="./LICENSE"><img alt="license" src="https://img.shields.io/badge/license-MIT-4A0324"></a>
+  <a href="https://developers.maytes.co/checkout-button"><img alt="docs" src="https://img.shields.io/badge/docs-developers.maytes.co-FE572A"></a>
+</p>
+
+---
+
+Renders a button and launches the Maytes-hosted checkout in the top-level window. Default mode opens a centered popup on wide viewports, with a branded loader and automatic redirect fallback on phones or when the popup is blocked; `mode: 'redirect'` opts into a redirect always. Inside an iframe every redirect targets the top-level window.
+
+**📖 Full integration guide:** [developers.maytes.co/checkout-button](https://developers.maytes.co/checkout-button)
+
+- **Framework-agnostic** — same factory whether it's a `<script>` tag or `import { Maytes }`; no React/Vue/Angular binding to keep in sync.
+- **Zero runtime dependencies** — a small, dependency-free bundle; ESM/CJS ship unminified so your bundler can tree-shake it.
+- **CSP-safe by construction** — no `eval`, `Function`, or string-form timers; every release is scanned for it before shipping.
+- **Evergreen CDN by default** — the recommended `<script>` tag always serves the newest release; pin a SemVer or content-hash URL instead if you'd rather freeze on a tested build.
+- **Signed provenance** — every npm release carries a [SLSA](https://slsa.dev) provenance attestation back to this repo's build.
+
+## Contents
+
+- [Install](#install)
+- [Usage](#usage)
+- [API](#api)
+- [Mobile app](#mobile-app)
+- [Development](#development)
 
 ## Install
 
 ### Script tag (CDN)
 
-For production, pin an exact release. The readable SemVer URL and the content-hash URL are two names for the **same release bytes** and share the **same SRI value** — pick either:
+|  | Evergreen (recommended) | Pinned |
+|---|---|---|
+| **Use when** | Default — always get the newest `1.x` release | You'd rather freeze on a tested build |
+| **Guarantee** | Always current; a bad release reaches you immediately | The bytes you tested are the bytes shipped, forever |
+| **SRI** | Not possible | Yes |
+
+### Evergreen (recommended)
 
 ```html
-<script src="https://js.maytes.co/v1.0.0/checkout-button.js"
-        integrity="sha384-…"
+<script src="https://js.maytes.co/v1/checkout-button.js"
         crossorigin="anonymous"></script>
 ```
 
+No `integrity` attribute is possible here — the bytes change without notice as new `1.x` releases ship. Trust the origin via CSP instead:
+
+```
+Content-Security-Policy: script-src 'self' https://js.maytes.co;
+```
+
+`/v1/` tracks the newest `1.x` release only; it won't jump to a future `2.x` (move to `/v2/checkout-button.js` explicitly once that ships). Poll `https://js.maytes.co/integrity.json` if you want to detect changes yourself.
+
+### Pinned (SemVer or content hash)
+
+For a guarantee instead of convenience — freeze on a tested build, update on your own schedule:
+
+<!-- @cdn-example-start -->
 ```html
-<script src="https://js.maytes.co/checkout-button.795d508b.js"
+<script src="https://js.maytes.co/v1.1.0/checkout-button.js"
         integrity="sha384-…"
         crossorigin="anonymous"></script>
 ```
 
-`v1.0.0` / `795d508b` are examples. The real version, hash, and SRI for each release live in [`CHANGELOG.md`](./CHANGELOG.md), the matching [release](https://github.com/kttipay/checkout-button/releases), and `https://js.maytes.co/integrity.json`.
+```html
+<script src="https://js.maytes.co/checkout-button.811263f9.js"
+        integrity="sha384-…"
+        crossorigin="anonymous"></script>
+```
+<!-- @cdn-example-end -->
 
-Use a pinned URL in every environment, development included — pinning is what makes the bytes you tested the bytes your shoppers get.
+Both URLs are the same release bytes with the same SRI value — pick either. Full version/hash/SRI history: [`CHANGELOG.md`](./CHANGELOG.md), [releases](https://github.com/kttipay/maytes-checkout-button/releases), `https://js.maytes.co/integrity.json`. Pinned URLs never change once published.
 
 ### npm
 
@@ -47,8 +104,8 @@ const maytes = Maytes({
 
 const cleanup = maytes.renderButton(document.getElementById('slot'), { block: true });
 
-// Optional popup mode:
-maytes.renderButton(document.getElementById('popup-slot'), { block: true, mode: 'popup' });
+// Opt into same-window redirect instead of the default popup:
+maytes.renderButton(document.getElementById('redirect-slot'), { block: true, mode: 'redirect' });
 
 // Imperative alternatives:
 maytes.redirectToCheckout({ checkoutId });
@@ -66,10 +123,14 @@ Via the script tag, the same factory is available as the global `window.Maytes(.
 | Method | Purpose |
 |---|---|
 | `Maytes(options)` | Create an SDK instance. `options.createCheckout` mints a checkout server-side; `options.environment` selects the Maytes environment. |
-| `renderButton(container, options?)` | Render the button into `container`; returns a cleanup function. Options include `label`, `block`, and `mode: 'redirect' \| 'popup'`. |
+| `renderButton(container, options?)` | Render the button into `container`; returns a cleanup function. Options include `label`, `block`, and `mode: 'redirect' \| 'popup'` (default `'popup'`). |
 | `redirectToCheckout(options)` | Launch checkout directly (no button). |
 | `checkoutUrl(options)` | Build the hosted checkout URL. |
-| `destroy()` | Tear down the instance and its listeners. |
+| `destroy()` | Tear down the instance and its listeners — call this on unmount or when the instance's config/environment changes, not as a reaction to detecting payment success from your own polling (that can tear down a checkout that's still in progress). To remove a single button, use the cleanup function returned by `renderButton()` or hide/disable the button element instead. |
+
+### Inside an iframe?
+
+The hosted checkout must run in the top-level window (its session cookie is refused inside a cross-site frame). If you render the button inside an iframe, the SDK navigates the top-level window; if the browser refuses, it opens a new tab; if both are refused it dispatches `maytes:checkout-failed` with `reason: 'navigation-blocked'`. When the checkout opens in a new tab, no popup poll starts and no `maytes:checkout-opened` / `maytes:checkout-closed` pair fires — you'll only see `maytes:checkout-redirected` with `target: 'tab'`. A sandboxed iframe needs `allow-scripts allow-same-origin allow-top-navigation` (plus `allow-popups allow-popups-to-escape-sandbox` for the tab fallback). Listen to `maytes:checkout-redirected` and read `event.detail.target` (`'self'`, `'top'` or `'tab'`) if your page needs to know where the checkout went. Rendering the button in the top-level page avoids all of this.
 
 ## Mobile app
 
@@ -85,22 +146,8 @@ npm run test:run
 npm run build        # bundles + SRI hashes + CSP scan
 ```
 
-Versioning and changelog are managed with [Changesets](./.changeset/README.md). Run `npm run changeset` with your PR.
-
-## Brand colours come from the design foundation
-
-The Maytes brand colours the button paints (`brand.primary` burgundy, `brand.secondary` orange, the burgundy/700 hover shade, and the inverse text white) are **not hand-written** in this package. They are vendored from the design foundation — `kttipay/designsystem` `web/tokens.ts` — into `src/foundation/brand.generated.ts`, pinned to a release tag recorded in `foundation.lock.json`:
-
-```json
-{ "repo": "kttipay/designsystem", "tag": "v0.3.0", "source": "web/tokens.ts" }
-```
-
-- `src/branding.ts`, `src/styles.ts` and `src/button.ts` read every brand colour from that generated module. Never type a Maytes hex into `src/`.
-- To move to a newer foundation release: `npm run sync:foundation -- --tag vX.Y.Z` (fetches the file at that tag with `gh api`, so you need a logged-in `gh`; `--from ../path/to/designsystem/web/tokens.ts` works offline). The script rewrites the generated module and the lock file. Commit both together.
-- A vitest test fails if the generated header's tag drifts from `foundation.lock.json`, so the file can only change through the script.
-
-The design-system repo does not publish an npm package yet. When it does (`@kttipay/foundation` on GitHub Packages), the upgrade path is to replace the vendored module with that dependency and delete the script and lock file.
+Versioning and changelog are managed with [Changesets](./.changeset/README.md). Run `npm run changeset` with your PR. Brand colours are vendored, not hand-written — see [`RELEASING.md`](./RELEASING.md#brand-colours-come-from-the-design-foundation) for how that works.
 
 ## License
 
-MIT
+[MIT](./LICENSE)

package/dist/{checkout-button.2a6f6a35.cjs → checkout-button.178d8394.cjs}

@@ -86,21 +86,79 @@ var MaytesError = class extends Error {
   }
 };
 
+// src/framing.ts
+function isSecurityError(err) {
+  return typeof err === "object" && err !== null && err.name === "SecurityError";
+}
+function isFramed() {
+  return window.top !== null && window.top !== window;
+}
+function sameOriginTop() {
+  if (!isFramed()) return null;
+  const top = window.top;
+  try {
+    void top.document;
+    return top;
+  } catch (err) {
+    if (!isSecurityError(err)) throw err;
+    return null;
+  }
+}
+function viewportWidth() {
+  if (!isFramed()) return window.innerWidth;
+  const top = sameOriginTop();
+  if (top !== null) return top.innerWidth;
+  const screenWidth = window.screen?.width;
+  return typeof screenWidth === "number" && screenWidth > 0 ? screenWidth : window.innerWidth;
+}
+function navigateWindow(target, url, replace) {
+  if (replace) {
+    target.location.replace(url);
+  } else {
+    target.location.href = url;
+  }
+}
+function severOpener(tab) {
+  try {
+    tab.opener = null;
+  } catch (err) {
+    if (!isSecurityError(err)) throw err;
+  }
+}
+function navigateTopLevel(url, replace) {
+  if (!isFramed()) {
+    navigateWindow(window, url, replace);
+    return { target: "self" };
+  }
+  let refusal;
+  try {
+    navigateWindow(window.top, url, replace);
+    return { target: "top" };
+  } catch (err) {
+    if (!isSecurityError(err)) throw err;
+    refusal = err;
+  }
+  try {
+    const tab = window.open(url, "_blank");
+    if (tab !== null) {
+      severOpener(tab);
+      return { target: "tab" };
+    }
+    return { target: null, cause: refusal };
+  } catch (err) {
+    return { target: null, cause: err };
+  }
+}
+
 // src/overlay.ts
 var TITLE_ID = "maytes-overlay-title";
 var STYLE_MARKER = "data-maytes-checkout-button-overlay-styles";
 var NATIVE_BACKDROP_FALLBACK = "rgba(0, 0, 0, 0.6)";
 function tryReadTopDocument() {
-  if (window.top === null || window.top === window) return null;
-  try {
-    const topDoc = window.top.document;
-    return topDoc.body !== null ? topDoc : null;
-  } catch (err) {
-    if (!(err instanceof DOMException && err.name === "SecurityError")) {
-      console.warn("[maytes/checkout-button] unexpected error resolving overlay host", err);
-    }
-    return null;
-  }
+  const top = sameOriginTop();
+  if (top === null) return null;
+  const topDoc = top.document;
+  return topDoc.body !== null ? topDoc : null;
 }
 function resolveOverlayHost() {
   return tryReadTopDocument() ?? document;
@@ -148,7 +206,7 @@ function buildOverlay(host, state) {
       try {
         state.popupWindow.focus();
       } catch (err) {
-        if (!(err instanceof DOMException && err.name === "SecurityError")) throw err;
+        if (!isSecurityError(err)) throw err;
       }
     }
   });
@@ -258,10 +316,12 @@ function performRedirect(url, replace) {
       "redirectToCheckout requires a browser context (window is undefined)"
     );
   }
-  if (replace) {
-    window.location.replace(url);
-  } else {
-    window.location.href = url;
+  const outcome = navigateTopLevel(url, replace);
+  if (outcome.target === null) {
+    throw new MaytesError(
+      MaytesErrorCode.Config,
+      "redirectToCheckout could not leave the embedding iframe; call it from a user gesture or from the top-level page"
+    );
   }
 }
 function makeRedirect(environment, baseUrlOverride) {
@@ -277,7 +337,7 @@ function makeRedirect(environment, baseUrlOverride) {
 }
 
 // src/version.ts
-var SDK_VERSION = "1.0.0";
+var SDK_VERSION = "1.1.0";
 
 // src/styles.ts
 var STYLE_ATTR = "data-maytes-checkout-button";
@@ -488,9 +548,6 @@ function isValidCheckoutResult(value) {
   }
   return true;
 }
-function isSecurityError(err) {
-  return err instanceof DOMException && err.name === "SecurityError";
-}
 function refocusPopup(popup) {
   try {
     popup.focus();
@@ -531,7 +588,7 @@ function startPopupPoll(state, onClose) {
   }, POPUP_POLL_INTERVAL_MS);
 }
 function isMobileViewport() {
-  return window.innerWidth <= MOBILE_MAX_WIDTH;
+  return viewportWidth() <= MOBILE_MAX_WIDTH;
 }
 function openBlankPopup(state) {
   return window.open("about:blank", state.popupName, popupFeatures());
@@ -592,7 +649,7 @@ function renderButton(state, container, options = {}) {
   ensureStylesInjected(state.config.cspNonce);
   const label = options.label ?? "Split with";
   const block = options.block === true;
-  const mode = options.mode ?? "redirect";
+  const mode = options.mode ?? "popup";
   if (mode !== "redirect" && mode !== "popup") {
     throw new MaytesError(
       MaytesErrorCode.Config,
@@ -633,13 +690,19 @@ function renderButton(state, container, options = {}) {
       detail: cause === void 0 ? { reason } : { reason, cause }
     }));
   };
-  const dispatchRedirected = (url) => {
-    document.dispatchEvent(new CustomEvent("maytes:checkout-redirected", { detail: { url } }));
+  const dispatchRedirected = (url, target) => {
+    const detail = { url, target };
+    document.dispatchEvent(new CustomEvent("maytes:checkout-redirected", { detail }));
   };
-  const redirectSameWindow = (url) => {
+  const navigateAway = (url) => {
+    const outcome = navigateTopLevel(url, false);
     teardownActiveCheckout();
-    dispatchRedirected(url);
-    window.location.href = url;
+    if (outcome.target === null) {
+      console.error("[maytes/checkout-button] could not leave the embedding frame:", outcome.cause);
+      dispatchFailed("navigation-blocked", outcome.cause);
+      return;
+    }
+    dispatchRedirected(url, outcome.target);
   };
   const closeOrphanPopup = (popup) => {
     closePopupWindow(popup);
@@ -654,6 +717,7 @@ function renderButton(state, container, options = {}) {
     const popup = shouldUsePopup ? openBlankPopup(state) : null;
     if (popup !== null) {
       state.popupWindow = popup;
+      state.popupNavigated = false;
       refocusPopup(popup);
       paintPopupLoadingScreen(popup, state.config.cspNonce);
       showOverlay(state);
@@ -682,12 +746,13 @@ function renderButton(state, container, options = {}) {
         result.checkoutId
       );
       if (popup !== null) {
+        state.popupNavigated = true;
         navigatePopup(popup, url);
       } else {
         if (shouldUsePopup) {
-          console.warn("[maytes/checkout-button] popup was blocked; falling back to same-window redirect");
+          console.warn("[maytes/checkout-button] popup was blocked; redirecting instead");
         }
-        redirectSameWindow(url);
+        navigateAway(url);
       }
     } catch (err) {
       if (popup !== null && popup.closed) return;
@@ -737,6 +802,7 @@ function createInstanceState(options, internal) {
     busy: false,
     overlayEl: null,
     popupWindow: null,
+    popupNavigated: false,
     popupName: generatePopupName(),
     popupPollHandle: null,
     destroyed: false,
@@ -789,7 +855,7 @@ var Maytes = (options, internal) => {
       state.destroyed = true;
       stopPopupPoll(state);
       hideOverlay(state);
-      closePopupWindow(state.popupWindow);
+      if (!state.popupNavigated) closePopupWindow(state.popupWindow);
       state.popupWindow = null;
       state.busy = false;
       for (const teardown of [...state.teardowns]) teardown();