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 generate: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
@@ -74,3 +77,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

.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

@@ -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,13 @@ 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,
+      html: true,
       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.
@@ -17,80 +21,8 @@ const mppx = Mppx.create({
   ],
 })
 
-// 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)
-
-  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,29 @@
 {
   "scripts": {
-    "build": "zile",
-    "changeset:publish": "zile publish:prepare && changeset publish && zile publish:post",
+    "build": "pnpm generate:html && zile",
+    "build:html": "vp build src/html/page && vp build src/html/tempo && vp build src/html/stripe",
+    "changeset:publish": "pnpm generate: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: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": "pnpm generate:html && zile dev",
+    "dev:example": "pnpm generate: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",
+    "generate:html": "pnpm build:html",
     "mppx": "node --import tsx src/bin.ts",
-    "test": "vp test"
+    "test": "pnpm generate:html && vp test",
+    "test:html": "pnpm generate: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": "playwright test -c src/html/test/playwright.config.ts",
+    "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": {