mnfst 0.5.162 → 0.5.164

package/lib/manifest.payments.js

@@ -1,18 +1,10 @@
-/*  Manifest Payments
+/*  Manifest Payments — config
 /*  By Andrew Matlock under MIT license
 /*  https://manifestx.dev
-/*
-/*  Provider-agnostic payments surface (x-pay / $pay).
-/*  The client only ever talks to YOUR function endpoint — never a provider's
-/*  secret API directly. Session creation, fulfilment webhooks and any mutation
-/*  live server-side. See manifest.payments.core.js for the contract.
 */
 
-/* Payments config */
-
-// Refuse strings still containing an unresolved ${VAR}. The loader interpolates
-// against window.env before caching the manifest, so a literal ${VAR} here means
-// an undefined env var — fail loud rather than POST it to the function verbatim.
+// Refuse strings still containing an unresolved ${VAR} — fail loud rather than
+// POST an undefined env var to the function verbatim.
 function resolvedOrNull(value, fieldName) {
     if (typeof value !== 'string') return value;
     if (/\$\{[^}]+\}/.test(value)) {
@@ -35,13 +27,6 @@ async function ensureManifest() {
 }
 
 // Normalize manifest.payments into a stable config object.
-//   provider   default adapter key (e.g. "revolut", "stripe", "paddle")
-//   endpoint   YOUR function base — mints checkout/portal sessions, verifies webhooks
-//   mode       default modality hint: "redirect" | "overlay" (server may override)
-//   publicKey  publishable key for overlay SDK init (safe to expose; NOT a secret key)
-//   managed    true = Manifest-hosted server moment (endpoint inferred)
-//   state      optional reactive-state source for $pay.state: { url } (GET) — for
-//              managed mode. Appwrite-backed projects read state via $x instead.
 let _cache = null;
 async function getPaymentsConfig() {
     if (_cache) return _cache;
@@ -71,33 +56,10 @@ async function getPaymentsConfig() {
 window.ManifestPaymentsConfig = { getPaymentsConfig, ensureManifest };
 
 
-/* Payments adapters */
-//
-// An adapter is the ONLY provider-specific client code. It knows how to open a
-// provider's overlay/embedded checkout. Link-through (redirect) needs no adapter
-// and is the universal floor — ANY provider with a hosted page works without one.
-//
-// Capability tiers:
-//   overlay  (supportsOverlay: true)  — provider exposes a programmatic modal
-//                                        with a success/cancel callback. Shipped
-//                                        for: revolut, paddle, lemonsqueezy,
-//                                        polar, razorpay.
-//   redirect (supportsOverlay: false) — no no-mount modal; works via the redirect
-//                                        floor (server returns {mode:'redirect',
-//                                        url}). Embedded/popup variants (Stripe
-//                                        Elements, Square Web Payments, PayPal
-//                                        Buttons, …) can be added per-provider via
-//                                        $pay.register(name, customAdapter).
-//
-// Adapter shape:
-//   { supportsOverlay: bool,
-//     async open({ url, params, config }) -> { status: 'complete'|'cancelled'|… } }
-//
-// The server (your function) decides modality per response, so adapters never see
-// secret keys — only a hosted url, publishable params, or a public token.
+/* Manifest Payments — provider adapters (overlay/embedded checkout) */
 
-// Load a CDN script once; resolve when ready. Adapters call this on first use so
-// heavy provider SDKs are never bundled and never appear in prerendered output.
+// Load a CDN script once; resolve when ready. Keeps heavy provider SDKs out of
+// the bundle and prerendered output.
 const _loaded = {};
 function loadScript(src, attrs) {
     if (_loaded[src]) return _loaded[src];
@@ -127,8 +89,7 @@ function list() { return Object.keys(_registry).map(n => ({ name: n, overlay: !!
 
 /* ---- Overlay adapters (programmatic modal + success callback) ------------- */
 
-// Revolut Merchant — popup over an order token. Function returns
-// { provider:'revolut', params:{ token } }  (token = the order's public id).
+// Revolut Merchant — popup over an order token.
 register('revolut', {
     supportsOverlay: true,
     async open({ params = {}, config }) {
@@ -148,8 +109,7 @@ register('revolut', {
     }
 });
 
-// Paddle (MoR) — overlay via Paddle.js. Function returns
-// { provider:'paddle', params:{ token, items, customer, … } }  (token = publishable).
+// Paddle (MoR) — overlay via Paddle.js.
 register('paddle', {
     supportsOverlay: true,
     async open({ params = {}, config }) {
@@ -169,8 +129,7 @@ register('paddle', {
     }
 });
 
-// Lemon Squeezy (MoR) — URL-in-a-modal via lemon.js. Function returns
-// { provider:'lemonsqueezy', url }  (a hosted checkout URL).
+// Lemon Squeezy (MoR) — URL-in-a-modal via lemon.js.
 register('lemonsqueezy', {
     supportsOverlay: true,
     async open({ url }) {
@@ -189,8 +148,7 @@ register('lemonsqueezy', {
     }
 });
 
-// Polar (MoR) — URL-in-a-modal via the embed SDK. Function returns
-// { provider:'polar', url }  (a checkout-link/session url).
+// Polar (MoR) — URL-in-a-modal via the embed SDK.
 register('polar', {
     supportsOverlay: true,
     async open({ url }) {
@@ -206,8 +164,7 @@ register('polar', {
     }
 });
 
-// Razorpay — true modal checkout. Function returns
-// { provider:'razorpay', params:{ key, order_id, amount, … } }.
+// Razorpay — true modal checkout.
 register('razorpay', {
     supportsOverlay: true,
     async open({ params = {} }) {
@@ -225,34 +182,15 @@ register('razorpay', {
 });
 
 /* ---- Redirect-floor providers --------------------------------------------- */
-// Well-known hosted-page providers with no clean no-mount modal. They work today
-// via the redirect floor — the function returns { mode:'redirect', url } (a hosted
-// checkout / payment link / order approve url). Registered for discoverability and
-// so a mistaken mode:'overlay' degrades cleanly. Add an embedded/popup variant any
-// time with $pay.register(name, { supportsOverlay:true, open }).
-//
-//   stripe     Checkout session url (Elements/embedded = custom adapter)
-//   square     Payment Link / Checkout API url (Web Payments SDK = custom)
-//   paypal     Orders API approve url (Smart Buttons popup = custom)
-//   braintree  hosted / Drop-in (Drop-in needs a mount node = custom)
-//   adyen      Pay-by-Link / hosted (Drop-in/Components = custom)
-//   mollie     hosted checkout (redirect-first by design)
-//
-// NOTE: any provider NOT listed here still works with zero config via the same
-// redirect floor (absolute-URL ref, or the function returning {mode:'redirect'}).
-// Hosted destinations like Patreon / Buy Me a Coffee / Ko-fi / donation pages are
-// just link-through: <a x-pay="'https://patreon.com/you'">…</a>. No adapter needed.
+// Registered for discoverability; no overlay, so they degrade to the redirect
+// floor. Unlisted providers work the same way with zero config.
 ['stripe', 'square', 'paypal', 'braintree', 'adyen', 'mollie']
     .forEach((name) => register(name, { supportsOverlay: false, redirectOnly: true }));
 
 window.ManifestPaymentsAdapters = { register, get, list, loadScript };
 
 
-/* Payments store */
-//
-// Reactive in-flight + server-defined state for $pay. Commerce semantics are NOT
-// modelled here — `state` is whatever your function returns (schema-less). The
-// core engine (plain JS) mutates these fields via Alpine.store('pay').
+/* Manifest Payments — reactive store for $pay */
 
 function initializePaymentsStore() {
     if (typeof Alpine === 'undefined') return;
@@ -274,7 +212,7 @@ document.addEventListener('alpine:init', () => {
 window.ManifestPaymentsStore = { initialize: initializePaymentsStore };
 
 
-/* Payments core */
+/* Manifest Payments — core engine (client ↔ function contract) */
 //
 // CONTRACT (client → your function):
 //   POST {endpoint}  { ref, payload, context }
@@ -283,24 +221,19 @@ window.ManifestPaymentsStore = { initialize: initializePaymentsStore };
 //     → { mode:'overlay',  provider, url }         URL-in-a-modal overlay
 //   GET  {state.url}?workspace=…&user=…            → arbitrary entitlement record
 //
-// `ref` is OPAQUE — a string only your function understands (price id, plan code,
-// cart token, "portal", …). Manifest never interprets it. All commerce semantics,
-// secret keys and webhook fulfilment live behind the function. Fulfilment is the
-// webhook — never trust this redirect/callback; always reconcile against state.
+// `ref` is opaque — Manifest never interprets it. Fulfilment is the webhook, not
+// this redirect/callback; always reconcile against state.
 
 const RETURN_PARAM = 'checkout';
 
 function store() { return window.Alpine?.store('pay') || null; }
 function setStore(patch) { const s = store(); if (s) Object.assign(s, patch); }
 
-// Navigation indirection. Defaults to a full-page redirect; override via
-// setNavigate() to intercept (SPA router integration, or test harnesses that
-// must not actually leave the page).
+// Navigation indirection; override via setNavigate() for SPA routers or tests.
 let _navigate = (url) => window.location.assign(url);
 function setNavigate(fn) { if (typeof fn === 'function') _navigate = fn; }
 
-// Identity context, auto-injected so the function knows who/which workspace pays.
-// Read from the auth store if the auth plugin is present; absent otherwise.
+// Identity context, auto-injected from the auth store when present.
 function getContext() {
     const ctx = {};
     try {
@@ -323,9 +256,7 @@ async function postSession(config, ref, payload, preferMode) {
         body: JSON.stringify({ ref, payload: payload || null, context })
     });
     if (!res.ok) {
-        // Surface the function's own human message (it returns { error } /
-        // { message } strings meant for the shopper) rather than a bare status
-        // code. Fall back to a friendly generic if the body isn't readable JSON.
+        // Surface the function's own { error }/{ message } over a bare status code.
         let message = '';
         try {
             const body = await res.json();
@@ -336,8 +267,8 @@ async function postSession(config, ref, payload, preferMode) {
     return res.json();
 }
 
-// Drive a server response into the right modality. Overlay degrades to redirect
-// when no adapter supports it — the universal floor, so no author hits a wall.
+// Drive a server response into the right modality; overlay degrades to redirect
+// when no adapter supports it.
 async function dispatch(response, config) {
     const mode = response?.mode || 'redirect';
     if (mode === 'overlay') {
@@ -357,10 +288,8 @@ async function dispatch(response, config) {
     return { status: 'redirected' };
 }
 
-// Public: initiate a payment flow for an opaque ref.
-//   ref      string the function understands, OR an absolute URL for a plain
-//            link-through with no server (the "embed a checkout link today" case).
-//   payload  optional opaque data forwarded to the function (+ optional .context).
+// Public: initiate a payment flow for an opaque ref (or an absolute URL for a
+// zero-server link-through).
 async function initiate(ref, payload = {}) {
     setStore({ loading: true, error: null });
     try {
@@ -386,12 +315,10 @@ async function initiate(ref, payload = {}) {
     }
 }
 
-// Convenience: open the billing/customer portal. Just another ref ("portal" by
-// default) the function maps to a server-minted portal session.
+// Convenience: open the billing/customer portal (just another ref).
 function portal(ref = 'portal', payload = {}) { return initiate(ref, payload); }
 
-// Read server-defined entitlement state into $pay.state (managed mode). Appwrite
-// projects should read state reactively via $x instead of configuring state.url.
+// Read server-defined entitlement state into $pay.state (managed mode).
 async function refreshState() {
     const config = await window.ManifestPaymentsConfig.getPaymentsConfig();
     if (!config?.state?.url) return null;
@@ -411,15 +338,9 @@ async function refreshState() {
     }
 }
 
-// On return from a redirect checkout, settle: the webhook is the source of truth,
-// so we re-pull state rather than trusting the success redirect. Strips our marker
-// from the URL afterward. Success pages should carry ?checkout=1 (set as the
-// function's success_url) so we know to reconcile.
-//
-// The provider's webhook can land seconds AFTER the buyer does, so a single
-// refresh can read pre-payment state. Re-poll on a short backoff to absorb the
-// lag — each refresh overwrites $pay.state, so the page settles on the granted
-// record without author code.
+// On return from a redirect checkout (success_url carries ?checkout=…), re-pull
+// state and strip the marker. The webhook can land seconds after the buyer, so
+// re-poll on a backoff to absorb the lag; each refresh overwrites $pay.state.
 const RETURN_POLL_MS = [2000, 5000, 10000];
 function handleReturn() {
     try {
@@ -439,19 +360,13 @@ function handleReturn() {
 window.ManifestPayments = { initiate, portal, refreshState, handleReturn, getContext, setNavigate };
 
 
-/* Payments magic ($pay) */
+/* Manifest Payments — $pay magic (callable + reactive props) */
 //
-// $pay is a callable magic with reactive properties:
-//   $pay('pro-monthly')            initiate a flow for an opaque ref → Promise
-//   $pay('https://buy.…')          absolute URL → plain link-through, no server
+//   $pay(ref|url)                  initiate a flow → Promise
 //   $pay.portal()                  open the billing/customer portal
 //   $pay.refresh()                 re-pull server state into $pay.state
-//   $pay.register(name, adapter)   add/override an overlay adapter (escape hatch)
-//   $pay.state                     server-defined entitlement record (schema-less)
-//   $pay.loading / $pay.error / $pay.last
-//
-// Reads of .state/.loading/etc. go through the reactive 'pay' store, so Alpine
-// tracks them in x-show / x-text. State for Appwrite projects is read via $x.
+//   $pay.register(name, adapter)   add/override an overlay adapter
+//   $pay.state / .loading / .error / .last   reactive (tracked in x-show/x-text)
 
 function initializePaymentsMagic() {
     if (typeof Alpine === 'undefined') return;
@@ -481,19 +396,11 @@ document.addEventListener('alpine:init', () => {
 window.ManifestPaymentsMagic = { initialize: initializePaymentsMagic };
 
 
-/* Payments directive (x-pay) */
-//
-// Sugar for "on click, initiate this ref". Markup is provider- AND modality-
-// agnostic — switching either is a config/server change, never an HTML change.
-//   <button x-pay="'pro-monthly'">Subscribe</button>
-//   <button x-pay="'credits-1000'">Buy credits</button>
-//   <button x-pay.portal>Manage billing</button>
-//   <button x-pay.overlay="'pro-monthly'">Subscribe</button>   modality hint
-//   <a x-pay="cart.token">Checkout</a>
+/* Manifest Payments — x-pay directive (click → initiate a ref) */
 //
 // Modifiers:
-//   .portal           treat as a portal flow (ref defaults to "portal")
-//   .overlay/.redirect  hint preferred modality to the function (server decides)
+//   .portal             portal flow (ref defaults to "portal")
+//   .overlay/.redirect  hint preferred modality (server decides)
 
 function initializePaymentsDirective() {
     if (typeof Alpine === 'undefined') return;
@@ -508,11 +415,9 @@ function initializePaymentsDirective() {
         const hasExpr = expression && expression.trim().length > 0;
         const getRef = hasExpr ? evaluateLater(expression) : null;
 
-        // Busy guard: ignore clicks while a flow is in flight and disable the
-        // element, so double-clicks can't mint duplicate checkout sessions.
-        // On failure, surface feedback automatically via the toasts plugin
-        // when it's loaded ($toast resolved through this element's Alpine
-        // scope); programmatic $pay() callers handle their own rejections.
+        // Busy guard: ignore clicks and disable the element while in flight, so
+        // double-clicks can't mint duplicate sessions. On failure, surface a
+        // toast if the toasts plugin is loaded.
         const run = async (ref) => {
             if (el.getAttribute('aria-busy') === 'true') return;
             const payload = modeHint ? { mode: modeHint } : {};
@@ -556,11 +461,7 @@ document.addEventListener('alpine:init', () => {
 window.ManifestPaymentsDirective = { initialize: initializePaymentsDirective };
 
 
-/* Payments main */
-//
-// Orchestration: settle redirect-returns and pull initial state once Alpine and
-// (optionally) auth are ready. Registration of store/magic/directive happens in
-// their own subscripts on alpine:init.
+/* Manifest Payments — boot (settle redirect-returns, pull initial state) */
 
 function bootPayments() {
     if (window.__manifestPaymentsBooted) return;

package/lib/manifest.router.js

@@ -124,12 +124,11 @@ let currentRoute = '/';
 let isInternalNavigation = false;
 
 function isPrerenderedStaticBuild() {
-    // When prerendered HTML is served as static pages, prefer normal browser navigation (MPA)
-    // so each URL loads its own prerendered HTML rather than SPA toggling.
+    // Prerendered static pages navigate MPA-style (each URL loads its own HTML).
     const prerendered = document.querySelector('meta[name="manifest:prerendered"]');
     const val = (prerendered?.getAttribute('content') || '').trim().toLowerCase();
     if (prerendered && val !== '0' && val !== 'false') return true;
-    // Backstop: prerender writes this per-page depth marker.
+    // Backstop: per-page depth marker written by prerender.
     return !!document.querySelector('meta[name="manifest:router-base-depth"]');
 }
 
@@ -326,17 +325,12 @@ async function handleRouteChange() {
     const prevRoute = currentRoute;
     currentRoute = newRoute;
 
-    // Handle scrolling based on whether this is an anchor link or route change
+    // Route change scrolls to top; anchor links let the browser scroll naturally.
     if (!window.location.hash) {
-        // This is a route change - scroll to top
-        // Use a small delay to ensure content has loaded
         setTimeout(() => {
-            // Scroll main page to top
             window.scrollTo({ top: 0, behavior: 'smooth' });
 
-            // Find and scroll scrollable containers to top
-            // Use a generic approach that works with any CSS framework
-            // Only check elements that are likely to be scrollable containers
+            // Also reset any scrollable containers.
             const potentialContainers = document.querySelectorAll('div, main, section, article, aside, nav, header, footer, .prose');
             potentialContainers.forEach(element => {
                 const computedStyle = window.getComputedStyle(element);
@@ -353,11 +347,8 @@ async function handleRouteChange() {
             });
         }, 50);
     } else {
-        // This is an anchor link - let the browser handle the scroll naturally
-        // Use a small delay to ensure content has loaded, then let browser scroll to anchor
         setTimeout(() => {
-            // The browser will automatically scroll to the anchor
-            // We just need to ensure the content is loaded first
+            // Let the browser scroll to the anchor once content has loaded.
         }, 50);
     }
 
@@ -370,18 +361,9 @@ async function handleRouteChange() {
         }
     });
 
-    // SPA route changes use the View Transitions API when available so the
-    // visibility-toggle that listeners perform inside this dispatch is
-    // animated. Cross-document MPA navigations are already handled by
-    // `@view-transition { navigation: auto }` in the framework's reset CSS;
-    // the same `::view-transition-group(*)` rule (driven by
-    // `--view-transition-duration` / `--view-transition-easing`) covers both.
-    //
-    // The callback is synchronous: visibility/head/anchor listeners mutate
-    // the DOM inside `dispatchEvent` and return. Returning anything async
-    // here would freeze the rendered frame until the promise resolves,
-    // adding the entirety of Alpine's pending-update queue to the perceived
-    // navigation time (1–2s on busy pages).
+    // Wrap the SPA dispatch in a View Transition when available (MPA is handled
+    // by @view-transition in reset CSS). Callback must stay synchronous:
+    // returning a promise freezes the frame until Alpine's update queue drains.
     if (shouldUseViewTransition()) {
         document.startViewTransition(() => {
             window.dispatchEvent(event);
@@ -391,30 +373,12 @@ async function handleRouteChange() {
     }
 }
 
-// Decide whether SPA route changes should run inside a View Transition.
-// Three modes, in priority order:
-//
-//   1. `<html data-no-view-transitions>`  → force OFF
-//   2. `<html data-view-transitions>`     → force ON
-//   3. (neither)                          → auto: ON when the current page is
-//                                            under VT_AUTO_THRESHOLD elements,
-//                                            OFF otherwise
-//
-// The auto threshold exists because the View Transitions API rasterizes the
-// full viewport for the "before" and "after" snapshots; cost scales linearly
-// with DOM size and gets noticeable above a few thousand elements (a 10k-
-// element page measured ~500ms per snapshot in dev). Light pages keep the
-// crossfade; heavy pages stay fast.
-//
-// Cross-document (MPA) navigations are unaffected — those use the browser's
-// native cross-document path (`@view-transition { navigation: auto }`),
-// which rasterizes in parallel with page load and doesn't expose the cost.
-//
-// Per-element opt-out (`data-no-view-transition`, singular) on individual
-// elements is handled by the existing reset CSS rule that sets
-// `view-transition-name: none` on them. `prefers-reduced-motion` is
-// respected automatically — the browser falls back to a snap with no
-// animation when the user has it set.
+// Whether SPA route changes run inside a View Transition. Priority:
+// data-no-view-transitions → off, data-view-transitions → on, else auto
+// (on under VT_AUTO_THRESHOLD elements). Auto threshold: VT rasterizes the
+// full viewport per snapshot, so cost scales with DOM size (~500ms/snapshot
+// on a 10k-element page). Per-element opt-out and prefers-reduced-motion are
+// handled in reset CSS / by the browser.
 const VT_AUTO_THRESHOLD = 3000;
 
 function shouldUseViewTransition() {
@@ -431,14 +395,9 @@ function shouldUseViewTransition() {
     }
 }
 
-// Headless automation (Puppeteer / Playwright / Selenium / WebDriver-driven
-// Chromium) frequently captures screenshots mid-transition, producing blank
-// frames. Real browsers report `navigator.webdriver === false` — including
-// when DevTools is open, when launched via `open <url>`, or on mobile — so
-// this check exclusively affects automation tooling and leaves end-user
-// behavior identical. Authors who want transitions in their automation tests
-// can force them on with `<html data-view-transitions>`, which takes priority
-// over this attribute via `shouldUseViewTransition()` above.
+// Disable transitions under WebDriver automation, which captures screenshots
+// mid-transition and gets blank frames. Only affects automation
+// (navigator.webdriver); data-view-transitions overrides.
 if (typeof navigator !== 'undefined' && navigator.webdriver === true) {
     const html = document.documentElement;
     if (html && !html.hasAttribute('data-view-transitions')) {
@@ -514,9 +473,8 @@ function installMpaStickyLocaleLinks() {
         event.preventDefault();
         event.stopPropagation();
         event.stopImmediatePropagation();
-        // For prerendered MPA builds, directory paths must have a trailing slash so that the
-        // static file host (e.g. Appwrite) resolves them to the correct index.html rather than
-        // falling back to the root index.html.
+        // MPA directory paths need a trailing slash so the static host resolves
+        // them to the right index.html, not the root one.
         const hasFileExt = /\.[a-zA-Z0-9]+$/.test(adjusted);
         url.pathname = (adjusted !== '/' && !hasFileExt && !adjusted.endsWith('/'))
             ? adjusted + '/'
@@ -547,18 +505,11 @@ function interceptLinkClicks() {
         // Handle pure anchor links normally - don't intercept them
         if (href.startsWith('#')) return;
 
-        // Don't intercept blob: or data: URLs. The export plugin creates a
-        // throwaway <a href="blob:…" download="…"> and programmatically
-        // clicks it to trigger a file save; if the router treats it as a
-        // SPA link, `new URL("blob:http://localhost/UUID", origin).pathname`
-        // resolves to "http://localhost/UUID" which then pushState pushes
-        // as a same-origin path, producing /http://localhost/UUID and
-        // landing the user on a 404 instead of downloading.
+        // Don't intercept blob:/data: (e.g. export plugin's download links) —
+        // pushState would turn them into a bogus same-origin path and 404.
         if (href.startsWith('blob:') || href.startsWith('data:')) return;
 
-        // Honor `download` — the link is opting out of SPA navigation in
-        // favor of letting the browser save its target. Same intent as
-        // blob:/data:, just expressed via the standard HTML attribute.
+        // Honor `download` — same opt-out intent, via the standard attribute.
         if (link.hasAttribute('download')) return;
 
         // Check if it's an external link FIRST (before any other processing)
@@ -651,8 +602,8 @@ function initializeNavigation() {
     handleRouteChange();
 }
 
-// Match the browser URL as soon as this module loads. Later chunks in the same bundle (e.g. router magic)
-// may initialize before DOMContentLoaded; getCurrentRoute() must not stay at '/' or $route breaks article pages.
+// Match the browser URL at module load: later chunks (e.g. router magic) may
+// read getCurrentRoute() before DOMContentLoaded; stale '/' breaks $route.
 currentRoute = pathnameToLogical(window.location.pathname);
 
 // Run immediately if DOM is ready, otherwise wait