feat: add html payment pages for browser 402 responses

.github/workflows/verify.yml

@@ -36,8 +36,11 @@ jobs:
       - name: Lint & format
         run: pnpm check:ci
 
+      - name: Generate HTML
+        run: pnpm gen:html
+
       - name: Check types
-        run: pnpm dev && pnpm check:types && pnpm check:types:examples
+        run: pnpm check:types && pnpm check:types:html && pnpm check:types:examples
 
   test:
     name: Test Runtime
@@ -102,3 +105,10 @@ jobs:
           pnpm run test --bail=1
         env:
           CI: true
+
+      - name: Run HTML e2e tests
+        run: pnpm test:html
+        env:
+          VITE_STRIPE_PUBLIC_KEY: ${{ secrets.VITE_STRIPE_PUBLIC_KEY }}
+          VITE_STRIPE_SECRET_KEY: ${{ secrets.VITE_STRIPE_SECRET_KEY }}
+          VITE_TEMPO_TAG: sha-20aecec

.gitignore

@@ -3,7 +3,9 @@ dist
 node_modules
 coverage
 *.tsbuildinfo
+*.gen.ts
 .DS_Store
 .env
 .env.*
 !.env.example
+test-results/

AGENTS.md

@@ -145,12 +145,42 @@ id = base64url(HMAC-SHA256(server_secret, input))
 ## Commands
 
 ```bash
-pnpm build          # Build with zile
-pnpm check          # Lint with oxlint + format with oxfmt
-pnpm check:types    # TypeScript type checking
-pnpm test           # Run tests with vitest
+pnpm build            # Build with zile
+pnpm check            # Lint with oxlint + format with oxfmt
+pnpm check:types      # TypeScript type checking
+pnpm check:types:html # TypeScript type checking for HTML payment pages (browser tsconfig)
+pnpm test             # Run tests with vitest
+pnpm test:html        # Run HTML e2e tests (Stripe + Tempo) with Playwright
+pnpm check:types:examples # TypeScript type checking for examples/
 ```
 
+## HTML Payment Pages
+
+Browser-rendered payment pages live in `src/html/`. Each method (Tempo, Stripe) has its own directory with:
+
+- `src/charge.ts` — Entry point, creates DOM and handles payment flow
+- `src/env.d.ts` — Module augmentation for `MppxConfig` and `MppxChallengeRequest`
+- `vite.config.ts` — Dev server and build config
+
+### Build pipeline
+
+`pnpm build` bundles each method's `charge.ts` into `{method}/server/internal/html.gen.ts` (generated, do not edit). The page shell is bundled into `server/internal/html.gen.ts`.
+
+### Global types
+
+- `src/html/env.d.ts` — Base global types (`mppx` var, `MppxConfig`, `MppxChallengeRequest`, `MppxEventMap`)
+- Each method augments `MppxConfig` and `MppxChallengeRequest` via its own `src/env.d.ts`
+- Browser tsconfig: `src/html/tsconfig.browser.json`
+
+### Infrastructure routes (`mppx.html()`)
+
+`Mppx.create()` returns an `html(request)` method that handles infrastructure routes:
+
+- Service worker (`/__mppx_serviceWorker.js`)
+- Method-registered routes (e.g., Stripe's `/__mppx_stripe_create_token`)
+
+Methods register routes via `htmlRoutes` on `Method.toServer()`.
+
 ## Skills Reference
 
 Load these skills for specialized guidance:

examples/charge/src/server.ts

@@ -5,13 +5,14 @@ import { tempoModerato } from 'viem/chains'
 import { Actions } from 'viem/tempo'
 
 const account = privateKeyToAccount(generatePrivateKey())
-const currency = '0x20c0000000000000000000000000000000000000' as const // pathUSD
 
 const mppx = Mppx.create({
   methods: [
     tempo({
-      currency,
+      account,
+      currency: '0x20c0000000000000000000000000000000000000',
       feePayer: true,
+      html: {},
       recipient: account.address,
       testnet: true,
     }),

examples/stripe/src/server.ts

@@ -9,6 +9,10 @@ const mppx = Mppx.create({
   methods: [
     stripe.charge({
       client: stripeClient,
+      html: {
+        // Publishable key for browser HTML payment form.
+        publishableKey: process.env.VITE_STRIPE_PUBLIC_KEY!,
+      },
       // Stripe Business Network profile ID.
       networkId: 'internal',
       // Ensure only card is supported.

package.json

@@ -1,18 +1,29 @@
 {
   "scripts": {
-    "build": "zile",
-    "changeset:publish": "zile publish:prepare && changeset publish && zile publish:post",
+    "build": "pnpm gen:html && zile",
+    "build:html": "vp build src/html/page && vp build src/html/tempo && vp build src/html/stripe",
+    "changeset:publish": "pnpm gen:html && zile publish:prepare && changeset publish && zile publish:post",
     "changeset:version": "changeset version",
     "check": "vp lint --fix && vp fmt --write .",
     "check:ci": "vp lint && vp fmt --check .",
     "check:types": "tsgo -b",
-    "check:types:examples": "pnpm -r --filter './examples/**' run check:types",
+    "check:types:html": "tsgo -p src/html/tsconfig.browser.json",
+    "check:types:examples": "pnpm zile build && pnpm -r --filter './examples/**' run check:types",
     "deps": "pnpx taze -r --no-ignore-other-workspaces --ignore-paths node_modules",
     "deps:ci": "pnpx actions-up",
-    "dev": "zile dev",
-    "dev:example": "node scripts/dev:example.ts",
+    "dev": "pnpm gen:html && zile dev",
+    "dev:example": "pnpm gen:html && node scripts/dev:example.ts",
+    "dev:html:compose": "pnpm --filter @mppx/html-page dev:compose",
+    "dev:html:stripe": "pnpm --filter @mppx/html-stripe dev",
+    "dev:html:tempo": "pnpm --filter @mppx/html-tempo dev",
+    "gen:html": "pnpm build:html",
     "mppx": "node --import tsx src/bin.ts",
-    "test": "vp test"
+    "test": "pnpm gen:html && vp test",
+    "test:html": "pnpm gen:html && pnpm test:html:form && pnpm test:html:compose && pnpm test:html:stripe && pnpm test:html:tempo",
+    "test:html:compose": "pnpm --filter @mppx/html-page test:compose",
+    "test:html:form": "pnpm --filter @mppx/html-page test:form",
+    "test:html:stripe": "pnpm --filter @mppx/html-stripe test",
+    "test:html:tempo": "pnpm --filter @mppx/html-tempo test"
   },
   "browserslist": [
     "defaults",
@@ -39,13 +50,16 @@
     "fast-check": "^4.6.0",
     "file-type": "^21.3.2",
     "hono": "^4.11.9",
+    "@playwright/test": "^1.58.2",
     "playwright": "^1.58.2",
     "prool": "^0.2.4",
+    "vite": "^8.0.0",
     "tempo.ts": "^0.14.2",
     "testcontainers": "^11.11.0",
     "tsx": "^4.21.0",
     "typescript": "~5.9.3",
     "viem": "^2.47.6",
+    "vite-plus": "~0.1.14",
     "vp": "npm:vite-plus@~0.1.14",
     "zile": "^0.0.19"
   },
@@ -146,6 +160,20 @@
       "types": "./dist/middlewares/elysia.d.ts",
       "src": "./src/middlewares/elysia.ts",
       "default": "./dist/middlewares/elysia.js"
+    },
+    "./html": {
+      "types": "./dist/html/index.d.ts",
+      "src": "./src/html/index.ts",
+      "default": "./dist/html/index.js"
+    },
+    "./html/vite": {
+      "types": "./dist/html/vite.d.ts",
+      "src": "./src/html/vite.ts",
+      "default": "./dist/html/vite.js"
+    },
+    "./html/env": {
+      "types": "./dist/html/env.d.ts",
+      "src": "./src/html/env.d.ts"
     }
   },
   "peerDependencies": {

pnpm-workspace.yaml

@@ -2,12 +2,15 @@ packages:
   - .
   - examples/*
   - examples/session/*
+  - src/html/page
+  - src/html/tempo
+  - src/html/stripe
 
 overrides:
   mppx: 'workspace:*'
-  vite: 'npm:@voidzero-dev/vite-plus-core@~0.1.14'
+  mppx>vite: 'npm:@voidzero-dev/vite-plus-core@~0.1.14'
   vitest: 'npm:@voidzero-dev/vite-plus-test@~0.1.14'
-  ox: '^0.14.1'
+  ox: '0.14.1'
   viem: '^2.47.5'
   tar@<=7.5.10: '7.5.11'
   '@modelcontextprotocol/sdk@>=1.10.0 <=1.25.3': '1.26.0'
@@ -20,6 +23,7 @@ overrides:
   '@hono/node-server@<1.19.10': '1.19.10'
   elysia@<1.4.26: '1.4.26'
   file-type: '21.3.2'
+  path-to-regexp: '^8.4.0'
   flatted@<=3.4.1: '>=3.4.2'
   undici@>=7.0.0 <7.24.0: '7.24.0'
   socket.io-parser@>=4.0.0 <4.2.6: '>=4.2.6'

src/Challenge.test.ts

@@ -269,6 +269,7 @@ describe('fromMethod', () => {
         "request": {
           "amount": "1000000",
           "currency": "0x20c0000000000000000000000000000000000001",
+          "decimals": 6,
           "recipient": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00",
         },
       }
@@ -300,6 +301,7 @@ describe('fromMethod', () => {
         "request": {
           "amount": "1000000",
           "currency": "0x20c0000000000000000000000000000000000001",
+          "decimals": 6,
           "methodDetails": {
             "chainId": 42431,
             "feePayer": true,