@meddleware/token-deployer-ui 0.0.1

package/README.md

@@ -0,0 +1,234 @@
+# @meddleware/token-deployer-ui
+
+A browser front-end that lets anyone deploy their own Sui coin — a client-side
+equivalent of `blockchain/sui/sui-token-template`. **Everything runs in the
+browser**: the user's wallet signs and pays gas, and nothing is compiled or
+signed on a server. The user also gets the full, verifiable Move source package,
+and can optionally push it to a new GitHub repo in their own account.
+
+## How it works
+
+1. Ships one pre-compiled `sui_token_template` Move module whose metadata fields
+   are DISTINCT named constants, so they can be patched
+   ([src/move-template/](src/move-template/)).
+2. In the browser, [`@mysten/move-bytecode-template`](https://www.npmjs.com/package/@mysten/move-bytecode-template)
+   deserialises the module; the identifiers + constant pool are patched to the
+   user's values ([src/lib/template.ts](src/lib/template.ts)) and it is re-serialised.
+3. A publish PTB ([src/lib/buildPublishTx.ts](src/lib/buildPublishTx.ts)) publishes
+   the module, applies the UpgradeCap policy, and splits a trivial fee to the
+   operator treasury. A follow-up finalize PTB mints the initial supply and applies
+   the supply/metadata policies when they differ from the defaults.
+4. The same inputs generate a full, downloadable source package
+   ([src/lib/generatePackage.ts](src/lib/generatePackage.ts)) that is **byte-identical**
+   to the CLI generator's output, so the on-chain package is source-verifiable.
+5. Licenses are fetched live from SPDX ([src/lib/licenses.ts](src/lib/licenses.ts)); an
+   optional icon upload goes to Walrus ([src/lib/walrus.ts](src/lib/walrus.ts)); and an
+   optional GitHub push uses the user's own token ([src/lib/github.ts](src/lib/github.ts)).
+
+## Security & trust model
+
+- **No backend, no key custody.** The only network calls are to the Sui RPC, the
+  user's wallet, SPDX (`raw.githubusercontent.com`), the Walrus relay/aggregator
+  (only if the icon uploader is used), and GitHub (only if the push is used).
+- **No endorsement.** The tool is neutral; it does not vet or endorse created
+  tokens or their creators. This is stated in the review, result, and footer UI.
+- **Defence in depth.** User input is validated at the form
+  ([src/lib/validation.ts](src/lib/validation.ts)) *and* re-asserted before it is
+  substituted into Move source / shell scripts
+  ([src/lib/generatePackage.ts](src/lib/generatePackage.ts)) and before it is
+  patched into the bytecode ([src/lib/template.ts](src/lib/template.ts)), so no
+  quote/backslash/control character or reserved Move keyword can ever produce an
+  injectable package.
+- **Fee integrity.** The fee is split from the user's own gas coin to the operator
+  treasury inside the publish PTB and cannot be redirected at runtime. A production
+  build **fails** if the treasury is unset (see below), so revenue can't silently
+  burn to `0x0`.
+- **GitHub token hygiene.** The optional PAT is `type=password`, `autocomplete=off`,
+  sent only to `api.github.com` over HTTPS, never stored or logged, and cleared as
+  soon as the push finishes.
+
+## Develop
+
+```bash
+npm install
+npm run dev          # Vite dev server
+npm run test         # Vitest unit tests (61 tests)
+npm run type-check   # vue-tsc
+npm run build        # production bundle -> dist/ (runs the treasury guard)
+npm run docs         # TypeDoc API reference -> docs/api/
+```
+
+## Operator configuration
+
+Committed defaults live in [.env.production](.env.production) (build) and
+[.env.development](.env.development) (dev server). Override per environment in the
+host dashboard. See [.env.example](.env.example) for the full list.
+
+| Variable | Purpose | Default |
+| --- | --- | --- |
+| `VITE_FEE_TREASURY_TESTNET` / `_MAINNET` | Operator treasury that receives the fee. **A production build fails if either is the zero address** (bypass with `VITE_ALLOW_UNSET_TREASURY=1`). | committed operator address |
+| `VITE_FEE_MIST` | Flat fee split from the user's gas coin. | `1000000000` (1 SUI) |
+| `VITE_RPC_TESTNET` / `_MAINNET` | JSON-RPC endpoint (set a paid RPC for production). | public endpoints |
+| `VITE_PUBLISH_GAS_BUDGET` | Publish gas budget (MIST). | `500000000` |
+| `VITE_PUBLIC_URL` | Site origin for canonical/OG/JSON-LD URLs. | `https://tokens.meddleware.co.uk` |
+| `VITE_WALRUS_RELAY_TESTNET` / `_MAINNET` | Your own upload relay (to collect the tip). Unset → public Mysten relay (earns nothing). | public relay |
+| `VITE_WALRUS_MAX_TIP_MIST` | Client-side max relay tip. **Must exceed your relay's tip** or uploads fail. | `50000000` (0.05 SUI) |
+| `VITE_ICON_MAX_BYTES` / `VITE_ICON_ALLOWED_TYPES` | Client icon size/type gate (UX only). | `102400` / PNG,JPEG,WebP,SVG |
+
+## Walrus icon upload relay (optional — for per-upload revenue)
+
+Icon uploads go through a Walrus **upload relay**. Using the public Mysten relay
+works out of the box but earns you nothing. To charge users per upload, run your
+own relay and configure `VITE_WALRUS_RELAY_*` — the tip is paid **on-chain by the
+user's wallet to your address**, no custom backend.
+
+**How the tip is safe (walrus SDK 1.1.7 + `crates/walrus-upload-relay`):** the tip
+is baked into the same tx the user signs and bound to the blob by
+`blobDigest ‖ SHA256(nonce) ‖ size`. The relay verifies the on-chain payment —
+amount checked against the *actual received body length* — **before** the expensive
+fan-out. A user cannot strip the tip or underpay for a large blob; either way the
+relay rejects and you incur no fan-out cost. The relay performs **no on-chain tx**,
+so you never pay gas; storage (WAL) is paid by the user at registration.
+
+**Host it (not a Cloudflare Worker).** The relay RS2-encodes blobs and opens
+hundreds of concurrent connections to storage nodes — beyond the Workers model. Run
+the stock `mysten/walrus-upload-relay` Docker image on a container host (Fly.io with
+scale-to-zero bounds idle cost; or a small VPS + Caddy). Your frontend stays static
+(GitHub Pages / Cloudflare Pages); the relay is a separate backend.
+
+```bash
+docker run -p 3000:3000 \
+  -v $HOME/.config/walrus/walrus_upload_relay_config.yaml:/opt/walrus/walrus_upload_relay_config.yaml \
+  -v $HOME/.config/walrus/client_config.yaml:/opt/walrus/client_config.yaml \
+  mysten/walrus-upload-relay --context testnet \
+    --walrus-config /opt/walrus/client_config.yaml \
+    --server-address 0.0.0.0:3000 \
+    --relay-config /opt/walrus/walrus_upload_relay_config.yaml
+```
+
+**Set a `linear` tip with margin** in `walrus_upload_relay_config.yaml`: `base` ≥
+per-request overhead (RPC + connection) and `encoded_size_mul_per_kib` above your
+egress cost/KiB, plus a fat margin (it also absorbs SUI/fiat drift and storage-node
+retry amplification). Tip `address` = your wallet. Keep `VITE_WALRUS_MAX_TIP_MIST`
+comfortably above this tip (the SDK hard-fails uploads if the tip exceeds it). The
+relay reads its tip only at **startup**, so changing it means rewrite-YAML + restart.
+
+**Protect it at the edge (the authoritative controls).** Put the relay behind
+Cloudflare (proxied DNS) with:
+
+- a **hard request-body cap ~256 KB** — icons are <100 KB, but the relay otherwise
+  buffers up to a hardcoded **1 GiB** body into RAM *before* the tip check (the one
+  real abuse vector: ingress/RAM/RPC on rejected uploads; no egress/gas);
+- a **per-IP** WAF rate-limit on `/v1/blob-upload-relay` (per-*wallet* limiting isn't
+  worth it — see [CLAUDE.md](CLAUDE.md) "Walrus relay economics & deferred decisions");
+- **origin locked to Cloudflare** (Authenticated Origin Pulls or a Cloudflare Tunnel)
+  so the origin IP can't be hit directly.
+
+Open CORS means anyone can use your relay, but every served upload paid a size-scaled
+tip, so third-party use is *profitable* as long as the tip keeps margin.
+
+## Deploy (Cloudflare Pages)
+
+- Build command: `npm run build` · Output directory: `dist`
+- [public/_headers](public/_headers) sets security headers + asset caching;
+  [public/_redirects](public/_redirects) provides the SPA fallback.
+- SEO: [index.html](index.html) has env-aware canonical/OG/Twitter/JSON-LD, a real
+  `public/og-image.png` (regenerate with `npm run gen:og-image`), and a crawlable
+  static fallback; `public/robots.txt` + `public/sitemap.xml` are included.
+- Before going live, confirm the treasury vars are set (the build enforces this)
+  and point the subdomain at the deployment.
+
+## Keeping the template in sync (single source of truth)
+
+The shipped bytecode and the downloadable source both derive from
+`@meddleware/sui-token-template` (`optionalDependencies`). After changing that template, re-run:
+
+```bash
+npm run regen:template   # recompiles + refreshes src/move-template/*
+npm run sync:template    # refreshes src/template-src/files.json
+npm run verify:template  # bytecode round-trip + provenance/parity tests
+```
+
+Two tests enforce this invariant in CI so it can never silently drift:
+
+- [tests/templateParity.test.ts](tests/templateParity.test.ts) — `files.json`
+  matches the canonical template sources verbatim.
+- [tests/templateArtifact.test.ts](tests/templateArtifact.test.ts) — the shipped
+  `.mv` still contains the identifiers/constants the patcher expects.
+
+## Verification scripts
+
+- `scripts/publish-localnet.mjs` — patch → publish → finalize against a local Sui node
+  (node, no browser).
+- `scripts/e2e-deploy.mjs` — the **network-parametrized real-chain deploy e2e** (headless
+  browser + injected wallet): drives the full UI, does a REAL publish, waits for real
+  confirmation, checks the result panel, downloads the source zip, and verifies coin type +
+  operator fee on-chain. Covers exactly what the mocked Cypress suite cannot. `scripts/e2e-browser.mjs`
+  is a thin localnet wrapper over it.
+- `scripts/e2e-walrus-browser.mjs` — the Walrus icon uploader end-to-end on testnet
+  with an injected wallet.
+
+## Real-chain e2e / launch runbook
+
+The Playwright mocked suite (`npm run test:e2e`) mocks all RPC via `VITE_E2E=1`, so it can prove
+the form/wallet/publish UI but **not** on-chain confirmation, the result panel, or the source
+download. The real-chain harness fills that gap. It is **manual** — never wired into automatic CI — because testnet/mainnet runs
+publish a real token and spend real SUI.
+
+```bash
+npm run e2e:localnet   # fresh keypair, localnet faucet — no real funds; run this freely
+npm run e2e:testnet    # real testnet publish — needs a funded key (see below)
+npm run e2e:mainnet     # real mainnet publish — additionally needs E2E_MAINNET_CONFIRM=1
+```
+
+Each script builds the app (production build, so the treasury guard runs) and serves `dist` before
+driving it. `E2E_NETWORK` selects the chain; the runner derives the app network (localnet borrows
+testnet mode with the RPC pointed at the local node).
+
+**Prerequisites for a real (testnet/mainnet) run:**
+
+| Env | Purpose |
+| --- | --- |
+| `SUI_PRIV` | bech32 `suiprivkey1…` for a **funded** deployer key. Export the CLI key: `sui keytool export --key-identity <addr>`. Never faucet-funded on a real network. |
+| `VITE_FEE_TREASURY_TESTNET` / `_MAINNET` | Operator treasury baked into the build (already set in `.env.production`). The build fails if it is the zero address. |
+| `E2E_FEE_ADDR` | The treasury to watch for the fee-delta assertion — set it equal to the built treasury. If unset, the fee check is skipped (the app still charges the fee). |
+| `VITE_RPC_TESTNET` / `_MAINNET` and `E2E_RPC` | JSON-RPC endpoint for the build (browser) and the node-side verifier. Use a JSON-RPC-capable endpoint — the official testnet fullnode is gRPC-only. |
+| `E2E_MAINNET_CONFIRM=1` | **Mainnet only.** Without it the mainnet runner aborts cleanly (fail-safe default) so it can never publish by accident. |
+
+A full fee-charging run needs the key to hold **≥ gas + fee** (~0.5 SUI gas + 1 SUI fee = ~1.5 SUI).
+For a first dry run you can lower `VITE_FEE_MIST` or leave the treasury unset (`VITE_ALLOW_UNSET_TREASURY=1`)
+so only ~0.5 SUI of gas is needed.
+
+Example (testnet):
+
+```bash
+export SUI_PRIV="$(sui keytool export --key-identity 0xYOURADDR --json | jq -r .exportedPrivateKey)"
+VITE_RPC_TESTNET=https://sui-testnet-rpc.publicnode.com \
+E2E_RPC=https://sui-testnet-rpc.publicnode.com \
+VITE_FEE_TREASURY_TESTNET=0xYOURTREASURY \
+E2E_FEE_ADDR=0xYOURTREASURY \
+npm run e2e:testnet
+```
+
+> **Do not run `e2e:testnet` until all other launch work is complete** — a premature published token
+> can attract traders before you are ready.
+
+### MVP manual verification checklist
+
+The human backstop for anything the harness does not assert (run once against testnet before launch):
+
+- [ ] Connect a real wallet (testnet), confirm the network selector shows testnet.
+- [ ] Fill the form; the coin-type preview updates as the module name changes.
+- [ ] Review → Confirm & deploy; wallet prompts to sign and pay gas.
+- [ ] "Confirming on-chain" reaches **done** (no timeout).
+- [ ] Result panel shows the correct coin type, package id, and cap ids.
+- [ ] The SuiScan package link opens the deployed package.
+- [ ] "Download source package (.zip)" produces a buildable Move package.
+- [ ] "Deploy another" resets the form.
+- [ ] (If used) the icon upload returns a Walrus aggregator URL that renders the image.
+- [ ] The operator treasury received the fee.
+
+## API reference
+
+`npm run docs` generates a TypeDoc site under `docs/api/` covering the deployment
+library (`src/lib`), composables, and config. See [typedoc.json](typedoc.json).

package/env.d.ts

@@ -0,0 +1,13 @@
+/// <reference types="vite/client" />
+
+declare module '*.vue' {
+  import type { DefineComponent } from 'vue'
+  const component: DefineComponent<Record<string, unknown>, Record<string, unknown>, unknown>
+  export default component
+}
+
+// Raw ?url imports (Vite) for the move-bytecode-template wasm asset.
+declare module '*?url' {
+  const src: string
+  export default src
+}

package/index.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8">
+    <link rel="icon" href="/favicon.ico">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Vite App</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@meddleware/token-deployer-ui",
+  "version": "0.0.1",
+  "type": "module",
+  "exports": {
+    ".": { "default": "./src/index.ts" }
+  },
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "dev": "vite",
+    "build": "vue-tsc --noEmit && vite build",
+    "preview": "vite preview",
+    "type-check": "vue-tsc --noEmit",
+    "test:unit": "vitest",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "build:e2e": "VITE_E2E=1 vite build",
+    "test:e2e": "playwright test",
+    "test:e2e:ui": "playwright test --ui",
+    "e2e:install": "playwright install --with-deps chromium firefox",
+    "e2e:localnet": "VITE_RPC_TESTNET=${VITE_RPC_TESTNET:-http://127.0.0.1:9000} VITE_FEE_TREASURY_TESTNET=${VITE_FEE_TREASURY_TESTNET:-0xfee0000000000000000000000000000000000000000000000000000000000000} vite build && start-server-and-test preview http://localhost:4173 'E2E_NETWORK=localnet node scripts/e2e-deploy.mjs'",
+    "e2e:testnet": "vite build && start-server-and-test preview http://localhost:4173 'E2E_NETWORK=testnet node scripts/e2e-deploy.mjs'",
+    "e2e:mainnet": "vite build && start-server-and-test preview http://localhost:4173 'E2E_NETWORK=mainnet node scripts/e2e-deploy.mjs'",
+    "lint": "oxlint . --fix",
+    "format": "oxfmt src/",
+    "docs": "typedoc",
+    "regen:template": "bash scripts/regen-template.sh",
+    "sync:template": "bash scripts/sync-template-src.sh",
+    "gen:og-image": "node scripts/gen-og-image.mjs",
+    "verify:template": "node scripts/verify-bytecode.mjs && vitest run tests/templateArtifact.test.ts tests/templateParity.test.ts"
+  },
+  "dependencies": {
+    "@meddleware/wallet-adapter": "^0.0.7",
+    "@meddleware/walrus-relay": "^0.1.0",
+    "@mysten/bcs": "~2.1.0",
+    "@mysten/move-bytecode-template": "~0.4.0",
+    "@mysten/sui": "^2.31.0",
+    "@mysten/walrus": "~1.2.0",
+    "fflate": "^0.8.3",
+    "vue": "^3.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "~24.12.2",
+    "@vitejs/plugin-vue": "^6.0.8",
+    "@vitejs/plugin-vue-jsx": "^5.1.6",
+    "@playwright/test": "^1.56.0",
+    "@vitest/eslint-plugin": "^1.6.23",
+    "@vue/test-utils": "^2.4.0",
+    "jsdom": "^29.1.1",
+    "oxfmt": "^0.59.0",
+    "oxlint": "~1.76.0",
+    "playwright": "^1.62.0",
+    "start-server-and-test": "^3.0.11",
+    "typedoc": "^0.28.20",
+    "typescript": "~6.0.0",
+    "vite": "^8.1.5",
+    "vite-plugin-vue-devtools": "^8.1.5",
+    "vitest": "^4.1.10",
+    "vue-tsc": "~3.3.0"
+  },
+  "optionalDependencies": {
+    "@meddleware/sui-token-template": "^1.0.0"
+  },
+  "engines": {
+    "node": "^22.18.0 || >=24.12.0"
+  }
+}

package/playwright.config.ts

@@ -0,0 +1,30 @@
+import { defineConfig, devices } from '@playwright/test'
+
+// Mocked-RPC UI e2e. Standardised on Playwright (robust; replaces the former
+// Cypress mocked suite, which exits SIGILL in the sandbox). The app is built with
+// VITE_E2E=1 so main.ts registers the mock wallet + fetch mock (tree-shaken from
+// prod). Real-chain e2e stays in scripts/e2e-deploy.mjs (npm run e2e:localnet…).
+const PORT = 4173
+
+export default defineConfig({
+  testDir: './e2e',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  reporter: 'list',
+  use: {
+    baseURL: `http://localhost:${PORT}`,
+    viewport: { width: 1280, height: 800 },
+    trace: 'on-first-retry',
+  },
+  webServer: {
+    command: `npm run build:e2e && npm run preview -- --port ${PORT} --strictPort`,
+    url: `http://localhost:${PORT}/`,
+    reuseExistingServer: !process.env.CI,
+    timeout: 180_000,
+  },
+  projects: [
+    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
+  ],
+})

package/public/CNAME

@@ -0,0 +1 @@
+sui-token-deployer.meddleware.co.uk

package/public/_headers

@@ -0,0 +1,12 @@
+# Cloudflare Pages headers. Security baseline; connect-src stays broad because
+# wallet extensions, Walrus relays, and per-network Sui RPCs vary.
+/*
+  X-Content-Type-Options: nosniff
+  Referrer-Policy: strict-origin-when-cross-origin
+  X-Frame-Options: DENY
+  Permissions-Policy: geolocation=(), camera=(), microphone=(), payment=()
+  Content-Security-Policy: default-src 'self'; script-src 'self' 'wasm-unsafe-eval'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self'; connect-src 'self' https: wss:; object-src 'none'; base-uri 'self'; frame-ancestors 'none'
+
+# Long-cache hashed build assets.
+/assets/*
+  Cache-Control: public, max-age=31536000, immutable

package/public/_redirects

@@ -0,0 +1 @@
+/*  /index.html  200

package/public/favicon.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" role="img" aria-label="Token Deployer">
+  <circle cx="16" cy="16" r="15" fill="#2f6feb"/>
+  <circle cx="16" cy="16" r="15" fill="none" stroke="#1b4fc0" stroke-width="2"/>
+  <text x="16" y="21" font-family="system-ui, sans-serif" font-size="14" font-weight="700" fill="#fff" text-anchor="middle">S</text>
+</svg>

package/public/robots.txt

@@ -0,0 +1,3 @@
+User-agent: *
+Allow: /
+Sitemap: https://tokens.meddleware.co.uk/sitemap.xml

package/public/sitemap.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+  <url>
+    <loc>https://tokens.meddleware.co.uk/</loc>
+    <changefreq>monthly</changefreq>
+    <priority>1.0</priority>
+  </url>
+</urlset>

package/scripts/e2e-browser.mjs

@@ -0,0 +1,15 @@
+// Thin wrapper: localnet deploy e2e. The real implementation is the network-parametrized
+// `e2e-deploy.mjs`; this just pins E2E_NETWORK=localnet so the historical entry point and its
+// localnet defaults (fresh keypair + faucet, 0xfee… treasury, 1 SUI fee assertion) keep working.
+//
+// Prereq (as before): build the app with the testnet RPC pointed at the local node and a
+// treasury set, then serve dist on APP_URL (default http://localhost:4173):
+//   VITE_RPC_TESTNET=http://127.0.0.1:9000 VITE_FEE_TREASURY_TESTNET=<addr> vite build
+//
+// Equivalent to `E2E_NETWORK=localnet node scripts/e2e-deploy.mjs` — or just `npm run e2e:localnet`.
+
+process.env.E2E_NETWORK = 'localnet'
+// Preserve the legacy FEE_ADDR override name for anyone still setting it.
+if (process.env.FEE_ADDR && !process.env.E2E_FEE_ADDR) process.env.E2E_FEE_ADDR = process.env.FEE_ADDR
+
+await import('./e2e-deploy.mjs')

package/scripts/e2e-deploy.mjs

@@ -0,0 +1,222 @@
+// Network-parametrized headless-browser deploy e2e. Loads the built app, injects a
+// wallet-standard wallet backed by a node-held keypair, drives the full UI, and performs a
+// REAL publish against the target chain — then verifies coin type + operator fee on-chain.
+//
+// This is the single source of truth for the real-chain deploy path; `e2e-browser.mjs` is a
+// thin localnet wrapper over it. It covers exactly what the mocked Cypress suite cannot: real
+// confirmation, the result panel, the source-zip download, and on-chain verification.
+//
+// Two axes matter and are DISTINCT:
+//   - E2E_NETWORK  = the physical chain the RPC talks to: localnet | testnet | mainnet.
+//   - APP_NETWORK  = the network the app runs in (its only UI options are testnet/mainnet;
+//                    it drives the `sui:<net>` chain label and which fee treasury applies).
+// localnet is run as APP_NETWORK=testnet with the testnet RPC overridden to the local node,
+// so the app believes it is on testnet while publishing to 127.0.0.1:9000. mainnet is the
+// only case that changes the in-UI network selector.
+//
+// The npm scripts (e2e:localnet / e2e:testnet / e2e:mainnet) build the app with the matching
+// VITE_RPC_* / VITE_FEE_TREASURY_* envs and serve dist on APP_URL before invoking this runner.
+
+import { readFileSync, existsSync } from 'node:fs'
+import { chromium } from 'playwright'
+import { SuiJsonRpcClient } from '@mysten/sui/jsonRpc'
+import { requestSuiFromFaucetV2 } from '@mysten/sui/faucet'
+import { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519'
+import { Transaction } from '@mysten/sui/transactions'
+import { toBase64 } from '@mysten/sui/utils'
+
+const ZERO_ADDR = '0x' + '0'.repeat(64)
+
+const NETWORK = process.env.E2E_NETWORK || 'localnet'
+if (!['localnet', 'testnet', 'mainnet'].includes(NETWORK)) {
+  fail(`E2E_NETWORK must be localnet|testnet|mainnet (got "${NETWORK}")`)
+}
+
+// The app only ever runs in testnet or mainnet mode; localnet borrows testnet mode.
+const APP_NETWORK = NETWORK === 'mainnet' ? 'mainnet' : 'testnet'
+
+const DEFAULT_RPC = {
+  localnet: 'http://127.0.0.1:9000',
+  testnet: 'https://sui-testnet-rpc.publicnode.com',
+  mainnet: 'https://fullnode.mainnet.sui.io:443',
+}
+const RPC = process.env.E2E_RPC || DEFAULT_RPC[NETWORK]
+
+const APP_URL = process.env.APP_URL || 'http://localhost:4173'
+const FAUCET = process.env.E2E_FAUCET || 'http://127.0.0.1:9123'
+const FEE_ADDR = process.env.E2E_FEE_ADDR || (NETWORK === 'localnet' ? '0xfee' + '0'.repeat(61) : '')
+const EXPECT_FEE_MIST = BigInt(process.env.E2E_FEE_MIST || '1000000000') // 1 SUI, matches VITE_FEE_MIST default
+const RESULT_TIMEOUT = Number(process.env.E2E_RESULT_TIMEOUT || '60000')
+
+function fail(msg) {
+  console.error('E2E FAIL:', msg)
+  process.exit(1)
+}
+
+// ---------------------------------------------------------------------------
+// Mainnet is fail-safe by default: it must never publish a real token — and spend real
+// SUI — by accident or in CI. Require an explicit opt-in and abort cleanly otherwise.
+// ---------------------------------------------------------------------------
+if (NETWORK === 'mainnet' && process.env.E2E_MAINNET_CONFIRM !== '1') {
+  console.log(
+    'e2e-deploy: mainnet run is gated. Set E2E_MAINNET_CONFIRM=1 to publish a REAL token on mainnet.\n' +
+      'Skipping (this is the expected, safe default).',
+  )
+  process.exit(0)
+}
+
+// ---------------------------------------------------------------------------
+// Keypair + funding. localnet mints a throwaway key from the faucet; testnet/mainnet use an
+// externally funded key supplied via SUI_PRIV (never a faucet on a real network).
+// ---------------------------------------------------------------------------
+let keypair
+if (NETWORK === 'localnet') {
+  keypair = new Ed25519Keypair()
+} else {
+  if (!process.env.SUI_PRIV) {
+    fail(
+      `SUI_PRIV is required for a ${NETWORK} run (bech32 suiprivkey1… — export the funded key with ` +
+        `\`sui keytool export --key-identity <addr>\`). Never funds from a faucet on ${NETWORK}.`,
+    )
+  }
+  keypair = Ed25519Keypair.fromSecretKey(process.env.SUI_PRIV)
+}
+const address = keypair.toSuiAddress()
+
+// Node-side client points at the PHYSICAL RPC; its `network` label is the app network so the
+// built transaction's chain identifier matches what the wallet/app sign under.
+const client = new SuiJsonRpcClient({ url: RPC, network: APP_NETWORK })
+
+const EXPECT_FEE = Boolean(FEE_ADDR) && FEE_ADDR !== ZERO_ADDR
+
+async function main() {
+  console.log(`e2e-deploy: E2E_NETWORK=${NETWORK} APP_NETWORK=${APP_NETWORK} RPC=${RPC}`)
+
+  if (NETWORK === 'localnet') {
+    await requestSuiFromFaucetV2({ host: FAUCET, recipient: address })
+    for (let i = 0; i < 25; i++) {
+      const b = await client.getBalance({ owner: address })
+      if (BigInt(b.totalBalance) > 0n) break
+      await new Promise((r) => setTimeout(r, 1000))
+    }
+  }
+
+  const balance = BigInt((await client.getBalance({ owner: address })).totalBalance)
+  console.log('sender:', address, 'balance:', balance.toString(), 'MIST')
+  if (balance === 0n) fail(`sender ${address} has no SUI on ${NETWORK}`)
+
+  const feeBefore = EXPECT_FEE
+    ? BigInt((await client.getBalance({ owner: FEE_ADDR })).totalBalance)
+    : 0n
+
+  // Browser resolution: explicit CHROME_PATH → a locally-installed Chrome → Playwright's
+  // bundled Chromium (CI installs it via `npx playwright install chromium`).
+  const chromePath =
+    process.env.CHROME_PATH ||
+    (existsSync('/usr/bin/google-chrome') ? '/usr/bin/google-chrome' : undefined)
+  const browser = await chromium.launch({ headless: true, executablePath: chromePath })
+  const page = await browser.newPage()
+  page.on('console', (m) => m.type() === 'error' && console.log('[browser error]', m.text()))
+  page.on('pageerror', (e) => console.log('[pageerror]', e.message))
+
+  // Node-side signer: build + sign the transaction the wallet forwards.
+  await page.exposeFunction('__mockSign', async (txJson) => {
+    const tx = Transaction.from(txJson)
+    const bytes = await tx.build({ client })
+    const { signature } = await keypair.signTransaction(bytes)
+    return { bytes: toBase64(bytes), signature }
+  })
+
+  // Inject a wallet-standard wallet before app scripts run. The account advertises the app
+  // network's chain so wallet-standard's required-feature/chain checks are satisfied.
+  await page.addInitScript(
+    ({ address, pubkey, chain }) => {
+      const account = {
+        address,
+        publicKey: new Uint8Array(pubkey),
+        chains: [chain],
+        features: ['sui:signTransaction'],
+        label: 'Mock',
+      }
+      const wallet = {
+        version: '1.0.0',
+        name: 'Mock Test Wallet',
+        icon: 'data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciLz4=',
+        chains: [chain],
+        accounts: [account],
+        features: {
+          'standard:connect': { version: '1.0.0', connect: async () => ({ accounts: [account] }) },
+          'standard:events': { version: '1.0.0', on: () => () => {} },
+          'sui:signTransaction': {
+            version: '2.0.0',
+            signTransaction: async (input) => {
+              const txJson = await input.transaction.toJSON()
+              return await window.__mockSign(txJson)
+            },
+          },
+        },
+      }
+      const callback = ({ register }) => register(wallet)
+      window.dispatchEvent(new CustomEvent('wallet-standard:register-wallet', { detail: callback }))
+      window.addEventListener('wallet-standard:app-ready', (e) => callback(e.detail))
+    },
+    { address, pubkey: Array.from(keypair.getPublicKey().toRawBytes()), chain: `sui:${APP_NETWORK}` },
+  )
+
+  await page.goto(APP_URL, { waitUntil: 'networkidle' })
+
+  // Connect: open the dialog, select the app network if it differs from the testnet default,
+  // then pick the injected wallet.
+  await page.getByRole('button', { name: 'Connect Wallet' }).click()
+  if (APP_NETWORK !== 'testnet') {
+    await page.locator('#dialog-network-select').selectOption(APP_NETWORK)
+  }
+  await page.getByRole('button', { name: /Mock Test Wallet/ }).click()
+  await page.getByText(/Mock Test Wallet ·/).waitFor({ timeout: 10000 })
+  console.log('wallet connected in UI')
+
+  // Fill the form.
+  await page.locator('#name').fill('Browser Coin')
+  await page.locator('#symbol').fill('BRWC')
+  await page.locator('#description').fill('Deployed via headless browser e2e')
+  await page.locator('#decimals').fill('6')
+  await page.locator('#package').fill('browser_coin')
+  await page.locator('#module').fill('browsercoin')
+
+  await page.getByRole('button', { name: /Review & deploy/ }).click()
+  await page.getByRole('button', { name: /Confirm & deploy/ }).click()
+  console.log('confirmed; deploying (real publish + confirmation)…')
+
+  // Wait for the result screen — this is the confirmation the mocked suite cannot reach.
+  await page.getByRole('heading', { name: /is live on/ }).waitFor({ timeout: RESULT_TIMEOUT })
+  const coinType = await page.locator('dd.mono').first().innerText()
+  console.log('UI result coinType:', coinType)
+
+  // Verify the in-browser source-package download (generatePackage + zip + SPDX license fetch).
+  const [download] = await Promise.all([
+    page.waitForEvent('download', { timeout: 30000 }),
+    page.getByRole('button', { name: /Download source package/ }).click(),
+  ])
+  const zipBuf = readFileSync(await download.path())
+  const isZip = zipBuf[0] === 0x50 && zipBuf[1] === 0x4b
+  console.log('download:', download.suggestedFilename(), zipBuf.length, 'bytes, zip:', isZip)
+  if (!isZip) fail('downloaded file is not a zip')
+
+  await browser.close()
+
+  // Independent on-chain verification.
+  if (!coinType.includes('::browsercoin::BROWSERCOIN')) fail(`unexpected coin type: ${coinType}`)
+
+  if (EXPECT_FEE) {
+    const feeAfter = BigInt((await client.getBalance({ owner: FEE_ADDR })).totalBalance)
+    const feeDelta = feeAfter - feeBefore
+    console.log('fee delivered this run:', feeDelta.toString(), 'MIST (to', FEE_ADDR + ')')
+    if (feeDelta !== EXPECT_FEE_MIST) fail(`expected ${EXPECT_FEE_MIST} MIST fee this run, got ${feeDelta}`)
+  } else {
+    console.log('no treasury configured — fee assertion skipped (app charges no fee)')
+  }
+
+  console.log(`\nDEPLOY E2E PASS ✓ (${NETWORK}: injected wallet, real publish, result panel, zip${EXPECT_FEE ? ', fee delivered' : ''})`)
+}
+
+main().catch((e) => fail(e.message))