feat: add html payment pages for browser 402 responses

.github/workflows/verify.yml

@@ -37,7 +37,7 @@
         run: pnpm check:ci
 
       - name: Check types
-        run: pnpm dev && pnpm check:types && pnpm check:types:examples
+        run: pnpm dev && pnpm check:types && pnpm check:types:html && pnpm check:types:examples
 
   test:
     name: Test Runtime
@@ -74,3 +74,10 @@
           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

.github/workflows/zizmor.yml

@@ -0,0 +1,25 @@
+name: Zizmor
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: ['**']
+
+permissions: {}
+
+jobs:
+  zizmor:
+    name: Zizmor
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      contents: read
+      actions: read
+    steps:
+      - name: Clone repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Run zizmor
+        uses: zizmorcore/zizmor-action@71321a20a9ded102f6e9ce5718a2fcec2c4f70d8 # v0.5.2

.gitignore

@@ -7,3 +7,4 @@ coverage
 .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-wagmi/server.ts

@@ -1,4 +1,4 @@
-import { Mppx, tempo } from 'mppx/server'
+import { Html, Mppx, tempo } from 'mppx/server'
 import { createClient, http } from 'viem'
 import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts'
 import { tempoModerato } from 'viem/chains'
@@ -20,6 +20,11 @@ const mppx = Mppx.create({
 export async function handler(request: Request): Promise<Response | null> {
   const url = new URL(request.url)
 
+  if (url.pathname === Html.serviceWorkerPathname)
+    return new Response(Html.serviceWorkerScript, {
+      headers: { 'Content-Type': 'application/javascript' },
+    })
+
   // Free
   if (url.pathname === '/api/health') return Response.json({ status: 'ok' })
 

examples/charge/src/server.ts

@@ -1,16 +1,15 @@
-import { Mppx, tempo } from 'mppx/server'
+import { Html, Mppx, tempo } from 'mppx/server'
 import { createClient, http } from 'viem'
 import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts'
 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,
+      currency: '0x20c0000000000000000000000000000000000000',
       feePayer: true,
       recipient: account.address,
       testnet: true,
@@ -21,6 +20,11 @@ const mppx = Mppx.create({
 export async function handler(request: Request): Promise<Response | null> {
   const url = new URL(request.url)
 
+  if (url.pathname === Html.serviceWorker.pathname)
+    return new Response(Html.serviceWorker.script, {
+      headers: { 'Content-Type': 'application/javascript' },
+    })
+
   // Free
   if (url.pathname === '/api/health') return Response.json({ status: 'ok' })
 

examples/stripe/src/server.ts

@@ -13,84 +13,19 @@ const mppx = Mppx.create({
       networkId: 'internal',
       // Ensure only card is supported.
       paymentMethodTypes: ['card'],
+      // Publishable key for browser HTML payment form.
+      publishableKey: process.env.VITE_STRIPE_PUBLIC_KEY,
+      // Secret key for HTML payment page SPT creation.
+      secretKey,
     }),
   ],
 })
 
-// Handles creating an SPT and charging a customer.
-// In production examples, this would be a DIFFERENT server than
-// the one that handles the HTTP 402 flow.
 export async function handler(request: Request): Promise<Response | null> {
-  const url = new URL(request.url)
+  const htmlResponse = await mppx.html(request)
+  if (htmlResponse) return htmlResponse
 
-  if (url.pathname === '/api/create-spt') {
-    const { paymentMethod, amount, currency, expiresAt, networkId, metadata } =
-      (await request.json()) as {
-        paymentMethod: string
-        amount: string
-        currency: string
-        expiresAt: number
-        networkId?: string
-        metadata?: Record<string, string>
-      }
-
-    if (metadata?.externalId) {
-      return Response.json(
-        { error: 'metadata.externalId is reserved; use credential externalId instead' },
-        { status: 400 },
-      )
-    }
-
-    const body = new URLSearchParams({
-      payment_method: paymentMethod,
-      'usage_limits[currency]': currency,
-      'usage_limits[max_amount]': amount,
-      'usage_limits[expires_at]': expiresAt.toString(),
-    })
-    if (networkId) body.set('seller_details[network_id]', networkId)
-    if (metadata) {
-      for (const [key, value] of Object.entries(metadata)) {
-        body.set(`metadata[${key}]`, value)
-      }
-    }
-
-    // Test-only endpoint; production SPT flow uses the agent-side issued_tokens API.
-    const createSpt = async (bodyParams: URLSearchParams) =>
-      fetch('https://api.stripe.com/v1/test_helpers/shared_payment/granted_tokens', {
-        method: 'POST',
-        headers: {
-          Authorization: `Basic ${btoa(`${secretKey}:`)}`,
-          'Content-Type': 'application/x-www-form-urlencoded',
-        },
-        body: bodyParams,
-      })
-
-    let response = await createSpt(body)
-    if (!response.ok) {
-      const error = (await response.json()) as { error: { message: string } }
-      if ((metadata || networkId) && error.error.message.includes('Received unknown parameter')) {
-        const fallbackBody = new URLSearchParams({
-          payment_method: paymentMethod,
-          'usage_limits[currency]': currency,
-          'usage_limits[max_amount]': amount,
-          'usage_limits[expires_at]': expiresAt.toString(),
-        })
-        response = await createSpt(fallbackBody)
-      } else {
-        return Response.json({ error: error.error.message }, { status: 500 })
-      }
-    }
-
-    if (!response.ok) {
-      const error = (await response.json()) as { error: { message: string } }
-      return Response.json({ error: error.error.message }, { status: 500 })
-    }
-
-    const { id: spt } = (await response.json()) as { id: string }
-    return Response.json({ spt })
-  }
-
-  if (url.pathname === '/api/fortune') {
+  if (new URL(request.url).pathname === '/api/fortune') {
     const result = await mppx.charge({
       amount: '1',
       currency: 'usd',

package.json

@@ -1,18 +1,27 @@
 {
   "scripts": {
     "build": "zile",
+    "build:html": "vite build src/html/page && vite build src/html/tempo && vite build src/html/stripe",
     "changeset:publish": "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:html": "tsgo -p src/html/tsconfig.browser.json",
     "check:types:examples": "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: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",
     "mppx": "node --import tsx src/bin.ts",
-    "test": "vp test"
+    "test": "vp test",
+    "test:html": "pnpm test:html:compose && pnpm test:html:stripe && pnpm test:html:tempo",
+    "test:html:compose": "pnpm --filter @mppx/html-page test:compose",
+    "test:html:stripe": "pnpm --filter @mppx/html-stripe test",
+    "test:html:tempo": "pnpm --filter @mppx/html-tempo test"
   },
   "browserslist": [
     "defaults",
@@ -39,8 +48,10 @@
     "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",

pnpm-workspace.yaml

@@ -2,6 +2,9 @@ packages:
   - .
   - examples/*
   - examples/session/*
+  - src/html/page
+  - src/html/tempo
+  - src/html/stripe
 
 overrides:
   mppx: 'workspace:*'