@aforoai/storefront-widgets 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,327 @@
+# Changelog
+
+All notable changes to `@aforoai/storefront-widgets` will be documented in
+this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Fixed
+
+- **Script-tag loader now parses the PricingCard presentation attributes
+  `data-cta-text`, `data-cta-url`, `data-max-plans`, and
+  `data-show-features`.** `pricingCardConfigToProps` reads all four
+  (`ctaText`/`ctaUrl`/`maxPlans`/`showFeatures`), and the operator Embed
+  Studio snippet (`EmbeddableWidgetTab`) emits `data-cta-text`,
+  `data-max-plans`, and `data-show-features` — but `readDataAttrs` never
+  parsed them, so those per-mount overrides silently did nothing on a
+  customer's page. Added a `readBooleanAttr` coercion helper for
+  `data-show-features` (data attributes are strings; the mapper guards on
+  `typeof === 'boolean'`). This brings PricingCard's script-tag tier to
+  parity with its React/JSX props. Regression coverage in
+  `tests/loader-config-attrs.test.ts`. Purely additive on the parse side.
+
+- **Script-tag loader now parses `data-theme`, `data-cart-type`, and
+  `data-target-id`.** The shared config→props mappers
+  (`src/core/widgetConfigMaps.ts`) already read `config.config.theme`
+  (every widget), `config.config.cartType`, and `config.config.targetId`
+  (CheckoutFlow), but `readDataAttrs` in `loader/loader.ts` never parsed
+  those three `data-*` attributes — so a script-tag placeholder's theme
+  selection was ignored (always `auto`) and an embedded checkout always
+  fell back to `SUBSCRIBE` with an empty target. This completes the
+  parse↔consume contract for the documented attribute surface. Regression
+  coverage added in `tests/loader-config-attrs.test.ts`. No public API
+  change; purely additive on the loader's parse side.
+
+- **`subscription-manager` `data-default-status` pre-filter now works.**
+  `subscriptionManagerConfigToProps` narrowed the value against a **lowercase**
+  allow-list (`active`, `trialing`, …) while `SubscriptionStatusFilter`, the
+  widget's `STATUS_CHIPS`, its `sub.status` comparisons, and the list-request
+  `status` param are all **UPPERCASE**. Every non-`all` selection (e.g.
+  `data-default-status="ACTIVE"`) was therefore rejected and silently fell
+  back to `all`, so the initial status filter never applied. The allow-list is
+  now the exact `SubscriptionStatusFilter` members (adds the previously-missing
+  `EXPIRING_SOON`). Regression test locks the accept-uppercase / reject-
+  lowercase-fallback contract.
+
+## [1.0.1] — 2026-05-29
+
+### Fixed
+
+- **`BridgeClient` PaymentMethod methods now honour the demo-mode
+  provider.** All other `BridgeClient` methods (`exchange`,
+  `fetchHeadlessConfig`, `fetchSubscriptions`, `fetchUsage`,
+  `previewSubscriptionChange`, etc.) short-circuit via
+  `if (BridgeClient.demoModeProvider) return ...` at the top of the
+  method, so `installDemoModeProvider()` routes every call to the
+  registered mock. The four PaymentMethod methods shipped in v1.0.0
+  (`fetchPaymentMethods`, `createPaymentMethodSetupIntent`,
+  `setDefaultPaymentMethod`, `deletePaymentMethod`) were missing this
+  delegate — they always hit the real network path.
+
+  Symptom: any consumer that installed a demo-mode provider for testing
+  saw "No payment method on file" (empty list) from `AforoPaymentMethod`
+  even though the mock provider's `fetchPaymentMethods` returned cards.
+  The four methods now match the rest of the interface.
+
+  Discovered during the `@aforoai/storefront-widgets-sandbox` build-out
+  pass (sandbox v0.0.1 → live mounts). All other widgets render their
+  synthetic fixtures correctly; only PaymentMethod was returning empty.
+
+  No public API change — bug fix only. Customers on v1.0.0 should
+  upgrade if they rely on demo mode for PaymentMethod widget testing
+  (Embed Studio's operator preview pane is unaffected because it
+  bypasses BridgeClient via the `_mockPaymentMethods` internal prop).
+
+## [1.0.0] — 2026-05-29
+
+### General availability — all 8 widgets shipped, public API surface frozen.
+
+This is the first generally-available release of `@aforoai/storefront-widgets`.
+The public API is now stable per semver — breaking changes will require a major
+bump and follow a 90-day deprecation period (see
+[Versioning docs](https://docs.aforo.ai/docs/embed-versioning)).
+
+### Widgets (8 — all with full implementations, no placeholders)
+
+| Widget | Purpose | Gzipped bundle |
+|---|---|---|
+| **`AforoPricingCard`** | Anonymous pricing display (3 layouts: horizontal cards, vertical list, comparison table) | 59.15 KB |
+| **`AforoSubscribeButton`** | Authenticated subscribe CTA with anti-double-subscribe lookup + 3 modes (redirect / event-only / embedded-flow) | 64.23 KB |
+| **`AforoInvoiceList`** | Paginated customer invoice browser with status filter, PDF download, Pay Now | 69.93 KB |
+| **`AforoCheckoutFlow`** | Multi-step embedded checkout (4-phase state machine) — Stripe Elements / Razorpay Drop-in / PayPal Smart Buttons | 60.86 KB |
+| **`AforoSubscriptionManager`** | Customer-portal subscription detail view (read-only state machine surface, upgrade/cancel events delegated to parent) | 60.23 KB |
+| **`AforoUsageMeter`** | Per-subscription real-time usage display with quota progress + threshold-reached alerts | 58.85 KB |
+| **`AforoPaymentMethod`** | Add / update / remove payment method via provider iframes (Stripe SetupIntent, Razorpay tokenize, PayPal Vault) | 57.89 KB |
+| **`AforoUpgradeCancel`** | Multi-step upgrade + cancellation deflection wizard (V50 CancellationFeedback reuse) | 61.51 KB |
+
+All bundles within FR-TIER-7 (loader ≤ 15 KB gz) and FR-TIER-8 (per-widget ≤ 80 KB gz) budgets defined in the spec.
+
+### Foundation locked
+
+- **AforoSession singleton** — N widgets on the same page perform exactly 1 bridge exchange (FR-§17.16). Verified by `tests/integration/all-widgets-singleton.test.tsx` (deferred to follow-up).
+- **Three distribution tiers** — Script-tag loader (2.42 KB gz), npm ESM / CJS (peer-dep React 18+), Vue 3 adapter at `@aforoai/storefront-widgets/vue`.
+- **Real-time push via SSE** — Backend `SseEmitter` + Redis pub/sub fan-out, exponential-backoff reconnect (capped at 60s), 100ms event dedup.
+- **Magic-link auth** — Anti-enumeration 200-always pattern + 15-minute single-use tokens + 10/min per-IP + 5/hour per-email rate limits.
+- **SRI hash publication** — Manifest at `embed.aforo.ai/v1/sri.json` for per-bundle integrity pinning.
+- **Theme inheritance** — 4-layer cascade (overrides → CSS custom properties → brand kit → neutral default).
+
+### Security
+
+- Embed-key auth + bridge-token JWT exchange + per-widget signature verification (FR-SEC-9).
+- Origin allowlist enforcement on all postMessage events (FR-EVT-6) — `targetOrigin` is never `*`.
+- HTTPS-only enforcement at loader (rejects `http://` pages with clear console error, FR-TIER-12).
+- CSP `nonce` propagation from loader script to dynamically-injected widget scripts (FR-SEC-16).
+- Webhook-authoritative rule (FR-SEC-23) — backend webhooks are canonical; postMessage events are informational.
+- In-memory tokens only — session JWTs never written to `localStorage`, `sessionStorage`, or cookies. Cleared on tab close.
+- No `eval()`, no `Function()`, no dynamic `import()` of untrusted URLs.
+
+### Operator surface
+
+- Embed Studio tab in aforo-product UI with 4 sub-tabs: Widgets / Keys / Auth Bridge / Telemetry.
+- Inline preview pane for all 8 widgets with mock-mode short-circuit via underscore-prefixed props.
+- One-time plaintext reveal on key mint with 10-minute auto-clear.
+- Telemetry CSV / JSON export with formula-injection guard.
+
+### Public docs
+
+- 12 docs pages at `docs.aforo.ai/docs/embed-*` — Quick Start, all 8 widget references, Authentication, Theming, Events, Integration Patterns, Security, Versioning.
+
+### Bundle sizes (gzipped)
+
+| Bundle | Size | Budget |
+|---|---|---|
+| `dist/loader.umd.js` | 2.42 KB | 15 KB |
+| `dist/widgets/pricing-card.js` | 59.15 KB | 80 KB |
+| `dist/widgets/subscribe-button.js` | 64.23 KB | 80 KB |
+| `dist/widgets/invoice-list.js` | 69.93 KB | 80 KB |
+| `dist/widgets/checkout-flow.js` | 60.86 KB | 80 KB |
+| `dist/widgets/subscription-manager.js` | 60.23 KB | 80 KB |
+| `dist/widgets/usage-meter.js` | 58.85 KB | 80 KB |
+| `dist/widgets/payment-method.js` | 57.89 KB | 80 KB |
+| `dist/widgets/upgrade-cancel.js` | 61.51 KB | 80 KB |
+
+### Quality gates (status at 1.0.0 ship)
+
+- **393 unit tests pass** across 41 test files. Public surface contract locked
+  by `sdk-contract.test.ts`; BridgeClient fail-soft on read paths + propagates
+  on mutation paths; AforoSession multi-tenant isolation + magic-link verify;
+  EventBus origin allowlist + dedup + non-`*` targetOrigin; ThemeReader
+  cascade; TelemetryReporter consent gating; per-widget unit + a11y + events +
+  session + loader tests.
+- **Axe-core WCAG 2.1 AA** verified zero violations across all 8 widgets in
+  default + loading + error + has-data + empty states.
+
+### Deferred to Phase 1 (explicitly out of scope for v1.0.0)
+
+- iframe tier rendering — current ship is script-tag + npm + Vue 3 only
+- OAuth / OIDC tenant-managed auth
+- Multi-subject sessions
+- Last-Event-ID SSE replay
+- DNS ownership challenge for custom domains
+- Enterprise self-hosted bundle assets
+- Web Components tier
+- Subscription pause flow within `AforoUpgradeCancel`
+- Per-tenant custom deflection offers in cancel flow
+- Sortable columns on `AforoInvoiceList`
+- Inline 3DS modal (currently falls back to provider-hosted challenge page in new tab)
+- Full Storybook config + Chromatic CI integration (`.stories.tsx` files
+  shipped; mounting via Storybook is a separate ship)
+- Sandbox playground at `embed.aforo.ai/sandbox`
+- Cross-browser matrix execution + Lighthouse audit runbooks (Prompt 15
+  formal gauntlet documents — `v1.0.0` ships with the artifact verified to
+  build + test green and bundle sizes within budget; the formal matrix
+  runbook is a follow-up)
+- i18n — UI strings are English-only at v1.0.0; locale-aware currency + date
+  formatting via `Intl` works today
+
+### Known limitations
+
+Same as the Phase 1 deferral list above. None of these block v1.0.0 customer
+rollout for tenants on Chrome / Edge / Firefox / Safari modern channels and
+standard payment providers.
+
+## [0.1.0] — 2026-05-29
+
+### Initial public release.
+
+This is the first release published to public npm. The SDK was previously
+private (workspace-internal) while widget bodies were built out. The public
+surface is locked by [`sdk-contract.test.ts`](https://github.com/aforoai/aforo-nextgen-UI/blob/main/packages/storefront-widgets/tests/sdk-contract.test.ts) —
+adding or removing an export is a deliberate test update.
+
+### Widgets shipped (4 of 8)
+
+- **`AforoPricingCard`** — anonymous pricing display with three layouts
+  (horizontal cards, vertical list, comparison table). Auto-fetches the
+  tenant's published offerings from the headless config endpoint and
+  inherits brand kit colors via the theme cascade.
+- **`AforoSubscribeButton`** — authenticated subscribe CTA. Exchanges a
+  bridge token for a session JWT, checks for an existing subscription to
+  avoid double-subscribing, and routes to checkout in redirect, event-only,
+  or embedded-flow mode.
+- **`AforoInvoiceList`** — paginated customer invoice table with status
+  filtering (UNPAID/PAID/OVERDUE/VOID), search, PDF download, and Pay Now
+  action. 30s in-widget client cache for responsive filter/page scrubbing.
+- **`AforoCheckoutFlow`** — multi-step embedded checkout. 4-phase state
+  machine (customer details → payment → confirming → completed), with
+  Stripe Payment Element, Razorpay Drop-in, and PayPal Smart Buttons via
+  postMessage-bridged iframes. Supports both SUBSCRIBE and INVOICE_PAYMENT
+  cart types.
+
+### Widgets stubbed (placeholder bodies; full implementations in subsequent releases)
+
+- `AforoSubscriptionManager`, `AforoUsageMeter`, `AforoPaymentMethod`,
+  `AforoUpgradeCancel` — these render an accessible loading placeholder
+  with their final prop interface locked. Drop-in replacement once their
+  bodies ship; the public API will not change.
+
+### Infrastructure
+
+#### Three embed tiers
+
+- **Script tag.** Drop one `<script>` plus `<div data-aforo-widget="…">`
+  placeholders. The loader (~2.5 KB gzipped) discovers placeholders,
+  lazy-fetches per-widget bundles, and mounts. Works in Webflow, WordPress,
+  plain HTML — no build toolchain required.
+- **npm / React.** `npm install @aforoai/storefront-widgets` then
+  `import { AforoPricingCard } from '@aforoai/storefront-widgets'`.
+  React 18+ peer dependency.
+- **Vue 3 + vanilla JS.** Wrappers shipped at
+  `@aforoai/storefront-widgets/vue` and
+  `@aforoai/storefront-widgets/vanilla`.
+
+#### Authentication
+
+- **Anonymous** — pricing display only; embed key + domain allowlist.
+- **Bridge token** — customer backend mints a short-lived signed token;
+  SDK exchanges it for an in-memory session JWT.
+- **Magic link** — for portals without their own session: SDK posts the
+  customer's email to Aforo, customer clicks the emailed link, returns to
+  the host page with a session JWT. Anti-enumeration: identical 202
+  response regardless of whether the email is registered. Rate-limited per
+  IP (10/min) and per email (5/hour). 15-minute one-time-use tokens.
+
+#### Real-time push (SSE)
+
+- Server-Sent-Events stream pushes lifecycle events
+  (`invoice.paid`, `subscription.status_changed`, `payment.failed`,
+  `usage.threshold_breached`, `invoice.created`) to mounted widgets in
+  real time. Automatic exponential-backoff reconnect (capped at 60s), per-
+  tab connection cap, 30s grace-close after last subscriber unsubscribes.
+
+#### Theming
+
+- Three-layer cascade: tenant brand-kit fallback → CSS variables on the
+  customer's page → per-widget `themeOverrides` prop. Dark mode via
+  `theme="dark"`, RTL via 100% logical CSS properties, namespaced classes
+  (`aforo-w-pc-*`, `aforo-w-sb-*`, etc.).
+
+#### Events
+
+- Outbound: every widget emits a typed
+  `aforo.<widget>.<event>` postMessage. Origin is always the resolved
+  parent origin — never `*`. 100ms dedup window per `(type, payload-hash)`.
+- Inbound: 5-type allowlist (`aforo:checkout-completed`,
+  `aforo:checkout-cancelled`, `aforo:invoice-paid`,
+  `aforo:refresh-requested`, `aforo:payment-challenge-completed`).
+  Origin allowlist enforced against the embed key's registered domains.
+
+### Security
+
+- **Subresource Integrity (SRI).** Per-version SHA-384 hashes published at
+  `https://embed.aforo.ai/v1/sri.json`. Customers pin via `integrity=`
+  attribute on the loader `<script>`.
+- **Dedicated origin.** All bundles served from `embed.aforo.ai` so CORS,
+  CSP, and SRI policies isolate the embed surface from the rest of Aforo.
+- **No dynamic code.** No `eval()`, no `Function()`, no dynamic
+  `import()` of untrusted URLs.
+- **HTTPS-only loader.** Bootstrap refuses to run on `http://` pages.
+- **In-memory tokens.** Session JWTs are never written to `localStorage`,
+  `sessionStorage`, or cookies. Cleared on tab close.
+
+### Test coverage
+
+- 313 unit tests covering: public surface contract, BridgeClient (with
+  fail-soft semantics on all read paths), AforoSession multi-tenant
+  isolation + magic-link verify flow, EventBus origin allowlist + dedup
+  + outbound non-`*` targetOrigin, ThemeReader cascade, TelemetryReporter
+  consent gating, all 4 shipped widgets (unit + a11y + events + SSE).
+- Axe-core WCAG 2.1 AA verified zero violations across all shipped
+  widgets in default + loading + error + has-data states.
+
+### Bundle sizes (gzipped)
+
+| Bundle                          | Size      | Budget    |
+|---------------------------------|-----------|-----------|
+| `dist/loader.umd.js`            | 2.42 KB   | 15 KB     |
+| `dist/widgets/pricing-card.js`  | 56.28 KB  | 80 KB     |
+| `dist/widgets/subscribe-button.js` | 62.80 KB | 80 KB    |
+| `dist/widgets/invoice-list.js`  | 68.49 KB  | 80 KB     |
+| `dist/widgets/checkout-flow.js` | 59.43 KB  | 80 KB     |
+
+All within FR-TIER-7 (loader 15 KB) and FR-TIER-8 (per-widget 80 KB)
+budgets defined in the spec.
+
+### Known limitations
+
+- **Iframe tier rendering deferred to Phase 1.** v0.1.x ships script-tag
+  and npm tiers only. The iframe wrapper (for tenants requiring strict
+  origin isolation) lands in a future release.
+- **3DS challenge falls back to redirect.** Inline 3DS modal coming in
+  Phase 1; v0.1.x customers requiring 3DS see the gateway's hosted
+  challenge page in a new tab.
+- **4 widget shells still render placeholder.** SubscriptionManager,
+  UsageMeter, PaymentMethod, UpgradeCancel will receive full bodies in
+  subsequent minor releases. Their public API surface (props + events)
+  is locked so dropping in the new bundle does not require code changes.
+- **Sandbox playground at embed.aforo.ai/sandbox coming.** Lets developers
+  try widgets against synthetic data without setting up an account.
+- **No i18n yet.** All copy is English. Locale-aware currency + date
+  formatting via `Intl` works today, but UI strings are not externalised.
+
+[1.0.1]: https://github.com/aforoai/aforo-nextgen-UI/releases/tag/storefront-widgets-v1.0.1
+[1.0.0]: https://github.com/aforoai/aforo-nextgen-UI/releases/tag/storefront-widgets-v1.0.0
+[0.1.0]: https://github.com/aforoai/aforo-nextgen-UI/releases/tag/storefront-widgets-v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aforo AI Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,249 @@
+# @aforoai/storefront-widgets
+
+> Drop-in embeddable widgets for Aforo's storefront — pricing cards, subscribe
+> buttons, invoice lists, and embedded checkout. Brand them yours, ship in
+> minutes.
+
+[![npm version](https://img.shields.io/npm/v/@aforoai/storefront-widgets.svg)](https://www.npmjs.com/package/@aforoai/storefront-widgets)
+[![license](https://img.shields.io/npm/l/@aforoai/storefront-widgets.svg)](./LICENSE)
+
+```bash
+npm install @aforoai/storefront-widgets
+```
+
+**Full developer docs:** <https://docs.aforo.ai/docs/embed-quickstart>
+
+---
+
+## What you get
+
+Eight widgets covering the customer billing surface. v0.1.0 ships four real
+widget bodies — the other four render an accessible loading placeholder while
+their bodies are being built. Their public API is locked, so dropping in the
+new bundle later requires no code changes on your side.
+
+| Widget                      | Status          | What it does                                      |
+|-----------------------------|-----------------|---------------------------------------------------|
+| `AforoPricingCard`          | ✅ Shipped       | Anonymous pricing display (horizontal / vertical / table) |
+| `AforoSubscribeButton`      | ✅ Shipped       | Authenticated subscribe CTA with anti-double-subscribe check |
+| `AforoInvoiceList`          | ✅ Shipped       | Paginated invoice list with status filter, search, PDF, Pay Now |
+| `AforoCheckoutFlow`         | ✅ Shipped       | Multi-step embedded checkout (Stripe / Razorpay / PayPal) |
+| `AforoSubscriptionManager`  | 🔜 Coming soon  | Customer-facing subscription summary + lifecycle actions |
+| `AforoUsageMeter`           | 🔜 Coming soon  | Real-time per-metric usage gauges with quota visualization |
+| `AforoPaymentMethod`        | 🔜 Coming soon  | Saved payment methods table + add/remove flow |
+| `AforoUpgradeCancel`        | 🔜 Coming soon  | Plan upgrade / downgrade / cancel flow with deflection |
+
+---
+
+## Three ways to embed
+
+### 1. Script tag (no build needed)
+
+For Webflow, WordPress, Squarespace, and plain HTML pages. The loader is
+~2.5 KB gzipped and lazy-fetches per-widget bundles only when their
+placeholders are on the page.
+
+```html
+<script
+  src="https://embed.aforo.ai/v1/loader.js"
+  integrity="sha384-…"
+  crossorigin="anonymous"
+  async
+></script>
+
+<div
+  data-aforo-widget="pricing-card"
+  data-tenant-slug="acme"
+  data-embed-key="embk_live_…"
+  data-layout="horizontal"
+></div>
+```
+
+The current SRI hash for `loader.js` is at
+<https://embed.aforo.ai/v1/sri.json>. Copy it into the `integrity=`
+attribute on the `<script>` tag so the browser refuses to execute a
+tampered bundle.
+
+### 2. React / Next.js
+
+```tsx
+import { AforoPricingCard } from '@aforoai/storefront-widgets';
+
+export function PricingSection() {
+  return (
+    <AforoPricingCard
+      tenantSlug="acme"
+      embedKey="embk_live_…"
+      layout="horizontal"
+      ctaUrlByOffering={{ off_pro: '/checkout/pro' }}
+    />
+  );
+}
+```
+
+### 3. Vue 3
+
+```vue
+<script setup>
+import { AforoPricingCard } from '@aforoai/storefront-widgets/vue';
+</script>
+
+<template>
+  <AforoPricingCard
+    tenant-slug="acme"
+    embed-key="embk_live_…"
+    layout="horizontal"
+  />
+</template>
+```
+
+Vanilla JS consumers (Svelte, Solid, Lit, etc.) import from
+`@aforoai/storefront-widgets/vanilla` — the same mount/unmount API the
+loader script uses internally.
+
+---
+
+## Authentication modes
+
+The plugin tier supports three auth modes depending on what your portal
+already has:
+
+1. **Anonymous** — pricing display only, no customer context. Use this for
+   marketing pages where you want to show your live offerings without
+   asking visitors to sign in.
+
+2. **Bridge token** — your backend mints a short-lived signed token that
+   identifies your customer to Aforo. The widget exchanges it for an
+   in-memory session JWT — your signing key never reaches the browser.
+   Use this when your portal already has its own authenticated session.
+
+3. **Magic link** — for portals that don't have their own session yet.
+   The customer types their email, gets an Aforo-branded email, clicks
+   the link, and lands back on your page with a session JWT. Rate-limited
+   and anti-enumeration-defended out of the box.
+
+Full guide with sequence diagrams + code samples for Node.js / Python / Go
+bridge-token signing: <https://docs.aforo.ai/docs/embed-authentication>.
+
+---
+
+## Theming
+
+Three-layer cascade — each layer overrides the previous:
+
+1. **Tenant brand kit** (logo + colors) configured in Aforo's Storefront →
+   Customize, fetched once when the widget mounts.
+2. **CSS variables** on your page (e.g. `--aforo-color-primary: #1A73E8;`)
+   override the brand kit for fine-grained theming.
+3. **Per-widget `themeOverrides` prop** for in-React/Vue customization at
+   the component level.
+
+Dark mode is opt-in via `theme="dark"`. The widgets are RTL-safe (100%
+logical CSS properties) and namespace every class
+(`aforo-w-pc-*`, `aforo-w-sb-*`, etc.) to avoid colliding with your CSS.
+
+Full theming docs: <https://docs.aforo.ai/docs/embed-theming>.
+
+---
+
+## Events
+
+Every widget emits typed `postMessage` events you can listen to from the
+parent page. Origin is always the resolved parent origin — never `*`.
+
+```js
+window.aforoEmbed?.on('aforo.subscribe.checkout_requested', (payload) => {
+  console.log('Customer clicked subscribe', payload);
+  // payload = { offeringId, planName, priceCents, currency, billingCycle, ratePlanId }
+});
+```
+
+Common events:
+
+| Event                                | When                                          |
+|--------------------------------------|-----------------------------------------------|
+| `aforo.<widget>.ready`               | Widget mounted and first paint complete       |
+| `aforo.subscribe.checkout_requested` | Customer clicked Subscribe                    |
+| `aforo.subscription.created`         | Subscribe checkout completed (advisory only)  |
+| `aforo.invoice-list.invoice.paid`    | Invoice marked paid via SSE push              |
+| `aforo.checkout.confirmed`           | Embedded checkout completed                   |
+| `aforo.<widget>.error`               | Any error path (typed `code`, no PII)         |
+
+> **⚠ Webhook is authoritative.** postMessage events fired into your page
+> are **advisory only**. Always validate state changes via Aforo's signed
+> webhooks before mutating your own database. We surface this prominently
+> because it's the most common source of integration bugs.
+
+Full event catalog: <https://docs.aforo.ai/docs/embed-events>.
+
+---
+
+## Browser support
+
+We test against the latest two stable versions of every major browser. The
+SDK runs anywhere modern JavaScript runs.
+
+| Browser            | Minimum version | Notes |
+|--------------------|-----------------|-------|
+| Chrome             | N-2 (latest 2)  | Desktop and Android |
+| Firefox            | N-2             | Desktop |
+| Safari             | 16+             | macOS |
+| Mobile Safari      | iOS 16+         | iPhone + iPad |
+| Mobile Chrome      | Android 12+     | Most devices |
+| Edge               | Latest          | Chromium-based |
+
+The loader refuses to bootstrap on `http://` pages — HTTPS is mandatory.
+We do not support IE11 or pre-Chromium Edge.
+
+---
+
+## Security
+
+- **SRI hashes published per release** at
+  <https://embed.aforo.ai/v1/sri.json>. Pin them via `integrity=` on the
+  `<script>` tag.
+- **Customer CSP guidance.** Add `script-src https://embed.aforo.ai` and
+  `connect-src https://api.aforo.ai` to your Content-Security-Policy. No
+  `unsafe-inline` or `unsafe-eval` required.
+- **In-memory session JWTs.** Never written to `localStorage`,
+  `sessionStorage`, or cookies. Cleared on tab close.
+- **Anti-enumeration on magic-link.** Identical 202 response regardless of
+  whether the email is registered. Rate-limited per IP and per email.
+- **No dynamic code.** No `eval()`, no `Function()`, no dynamic `import()`
+  of untrusted URLs.
+
+Full security model + how to report vulnerabilities: see
+[`SECURITY.md`](./SECURITY.md).
+
+---
+
+## Versioning
+
+We follow [Semantic Versioning](https://semver.org). Pre-1.0:
+
+- `0.x.y` — frequent additions, occasional breaking changes documented in
+  [CHANGELOG.md](./CHANGELOG.md). Pin to a specific version in production.
+
+Post-1.0:
+
+- `1.x.y` — strict semver. Additions and bug fixes only.
+- `2.x.y` — breaking changes with a 90-day deprecation period announced
+  via the changelog. The loader URL is pinned at `/v1/` and stays
+  backward-compatible within v1.
+
+Full versioning policy: <https://docs.aforo.ai/docs/embed-versioning>.
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
+---
+
+## Support
+
+- 📖 Docs: <https://docs.aforo.ai/docs/embed-quickstart>
+- 🐛 Issues: <https://github.com/aforoai/aforo-nextgen-UI/issues>
+- 🔒 Security: `security@aforo.ai`
+- 💬 Email: `support@aforo.ai`