@mobiloud/ml-back-button

Version 2: a browser-only, dependency-free Back button engine for websites and native WebViews. Initialize explicitly; importing the engine alone does not display a button. Test on your actual iOS/Android app before deploying to customers. The npm latest tag points to version 2.0.0.

Install

npm install @mobiloud/[email protected]

For app injection, load script.js from your own hosting or a version-pinned npm CDN URL, then initialize in the same page:

window.createBackButton({
  navigationScope: 'customer-tab',
  iconOnly: true,
  hideOnStartPage: true,
  suppressInitialSameURLBack: true,
  size: 48,
  rules: [{match: {target: 'url', type: 'contains', value: 'checkout'}, override: {visible: false}}]
});

Inject on every full-document navigation. Keep separate native WebViews' session storage independent. This is a browser script exposing window.createBackButton, not a Node.js/SSR module. It does not automatically detect native apps; control injection in your app or gate initialization yourself. Disable any older separate Back button injection.

Configuration

Supports text, icon, iconOnly, size, borderRadius, zIndex, showSpinner, minLoadingTime, colors (background, backgroundHover, text, icon, spinner), and position (vertical, horizontal, offsetTop, offsetBottom, offsetLeft, offsetRight).

scrollBehavior can be off (default), hide, or fade; scrollOpacity controls fading. URL rules support contains, exact, and wildcard matching against path or url, default case-insensitive. Later matching rules override earlier presentation settings. onBack, onShow, and onHide callbacks run in the page. debugMode logs locally; it is off by default. The diagnostic overlay is not shipped in this package.

hideOnStartPage hides Back whenever the starting origin/path is revisited without clearing browser history. suppressInitialSameURLBack suppresses duplicate initial entries. Unknown history entries are handled conservatively. Cross-origin tracking is limited by browser storage boundaries; a floating fallback does not guarantee history restoration on another domain.

Optional Backcountry adapter

After loading script.js, load adapters/backcountry.js and call:

window.createBackcountryHeaderButton({navigationScope: 'backcountry', reserveSpace: false});

Only initialize this adapter on Backcountry. It requires the existing customer app CSS and search-row markup. It inserts a black 36px circle with a 44px hit area and white chevron/spinner. It hides on the starting page and URLs containing checkout. Missing/ambiguous header anchors hide the adapter; the generic engine can be used for floating placement. This adapter does not include the old cross-domain test bundle's automatic profile switching.

Security and privacy

Custom SVG is restricted to geometric elements and an attribute allowlist. Scripts, event handlers, foreign content, external resources, and URL-based paint are omitted. Unsupported SVG features may not render; plain-text icons also work. Configuration must still come from a trusted administrator.

Navigation metadata uses sessionStorage scoped by navigationScope. Persisted URLs contain origin/path only, without query strings, fragments or userinfo. Paths can still contain personal identifiers. Opaque random group IDs preserve same-document query navigation distinctions without saving query values. History tracking retains at most 200 entries; navigation into discarded entries is conservative. Browser history itself is not erased. Data stays in the page; there is no telemetry or cookie access in the engine.

Version 2 changes navigation tracking and custom-SVG handling from version 1. Browser history methods are wrapped for SPA tracking. A document-lifetime tracker remains after a button is destroyed, allowing a replacement button to reuse it. Do not treat this release as an independently audited security guarantee.

Development and publishing

npm ci --ignore-scripts
npm test
npm pack --dry-run

Only script.js, adapters/backcountry.js, package metadata, README and LICENSE are published. The test-only DOM dependency is not a runtime dependency.

GitHub CI checks tests and packaging. .github/workflows/publish.yml is a manually dispatched publishing workflow restricted to main, using the npm environment and npm OIDC trusted publishing. Configure the npm trusted publisher for organization 50pixels, repository ml-back-button, workflow publish.yml, environment npm. It publishes stable versions to latest and prereleases to next. The private GitHub repository remains private; package source is public under MIT. No provenance claim is made for private-repository publishing.