@meddleware/token-deployer-ui 0.0.1

package/.env.example

@@ -0,0 +1,75 @@
+# Copy to .env (or set in the Cloudflare Pages dashboard) before deploying.
+# All are optional; sensible public defaults are used when unset.
+#
+# Canonical domain: sui-token-deployer.meddleware.co.uk (k8s SPA, primary)
+# GitHub Pages mirror: meddleware.github.io/vault/token-deployer-ui/
+
+# Operator fee (MIST) split from the user's gas coin into your treasury.
+# Default 1 SUI (1000000000 MIST) — trivial, ~7.5x under competitor pricing.
+VITE_FEE_MIST=1000000000
+
+# Operator treasury addresses per network (REQUIRED for the fee to be collected).
+# The committed operator defaults live in `.env.production` (auto-loaded by
+# `vite build`). A production build FAILS if a selectable network's treasury is
+# still the zero address, so revenue can never silently burn — set both below or
+# in `.env.production`. Set VITE_ALLOW_UNSET_TREASURY=1 to bypass (dev/e2e only).
+VITE_FEE_TREASURY_TESTNET=0xe6b2810abfc5a6f37a375f73e3ba76cfc37584196e453255ad3c9ca2f0ede0ed
+VITE_FEE_TREASURY_MAINNET=0xe6b2810abfc5a6f37a375f73e3ba76cfc37584196e453255ad3c9ca2f0ede0ed
+
+# Optional RPC overrides. Set a paid/private endpoint for production to avoid public
+# rate limits. NOTE: the official testnet fullnode (fullnode.testnet.sui.io) is gRPC-only
+# and 404s for JSON-RPC — use a JSON-RPC-capable endpoint for testnet (the app defaults to
+# https://sui-testnet-rpc.publicnode.com). The same VITE_RPC_TESTNET is what the real-chain
+# e2e (npm run e2e:testnet) builds against; point E2E_RPC at the same endpoint.
+# VITE_RPC_TESTNET=https://sui-testnet-rpc.publicnode.com
+# VITE_RPC_MAINNET=https://fullnode.mainnet.sui.io:443
+
+# Optional publish gas budget (MIST).
+# VITE_PUBLISH_GAS_BUDGET=500000000
+
+# --- Walrus icon upload -----------------------------------------------------
+# Operator's own upload relay per network. Set these to a relay YOU run (the
+# stock mysten/walrus-upload-relay container) to collect the native per-upload
+# tip as revenue. Unset → the public Mysten relay is used (uploads still work
+# but tip Mysten, not you). See the relay runbook in README.md / CLAUDE.md.
+# VITE_WALRUS_RELAY_TESTNET=https://sui-walrus-relay-testnet.meddleware.co.uk
+# VITE_WALRUS_RELAY_MAINNET=https://sui-walrus-relay.meddleware.co.uk
+
+# gRPC fullnode for the Walrus icon-upload client (a SuiGrpcClient). This is a
+# *gRPC* endpoint and is SEPARATE from VITE_RPC_* (the JSON-RPC deploy endpoints) —
+# the two protocols are not interchangeable. Defaults to the public gRPC fullnodes
+# (rate-limited); set your own for production to avoid limits.
+# VITE_WALRUS_RPC_TESTNET=https://fullnode.testnet.sui.io:443
+# VITE_WALRUS_RPC_MAINNET=https://fullnode.mainnet.sui.io:443
+
+# Client-side max relay tip (MIST). COUPLING: the Walrus SDK hard-fails an upload
+# if your relay's tip exceeds this, so keep it comfortably ABOVE the relay tip.
+# Default 0.05 SUI. Raising the relay tip past this needs a frontend redeploy.
+# VITE_WALRUS_MAX_TIP_MIST=50000000
+
+# NFT-gated relay access (OPTIONAL). If your operator relay runs behind an
+# `nft-gate` gateway, set these to require holders of the access NFT. When UNSET,
+# the relay behaves exactly as before (no gating). Values come from the
+# access_gate publish (`.env.<network>`: ACCESS_GATE_PACKAGE_ID, ACCESS_GATE_GATE_ID,
+# and ACCESS_NFT_TYPE or SOULBOUND_NFT_TYPE). Set all three (PACKAGE/ID/NFT_TYPE)
+# to enable. Per-network isolation is automatic (the NFT type embeds the package id).
+# VITE_ACCESS_GATE_PACKAGE_TESTNET=0x…
+# VITE_ACCESS_GATE_ID_TESTNET=0x…
+# VITE_ACCESS_GATE_NFT_TYPE_TESTNET=0x…::access_gate::SoulboundAccessNFT
+# VITE_ACCESS_GATE_SOULBOUND_TESTNET=true      # selects consume vs consume_soulbound
+# VITE_ACCESS_GATE_PRICE_MIST_TESTNET=0        # display + purchase price
+# VITE_ACCESS_GATE_PACKAGE_MAINNET=0x…
+# VITE_ACCESS_GATE_ID_MAINNET=0x…
+# VITE_ACCESS_GATE_NFT_TYPE_MAINNET=0x…::access_gate::SoulboundAccessNFT
+# VITE_ACCESS_GATE_SOULBOUND_MAINNET=true
+# VITE_ACCESS_GATE_PRICE_MIST_MAINNET=0
+
+# Icon constraints (UX/cost guard only — the authoritative cap is the edge body
+# limit in front of the relay). Default 100 KiB; PNG/JPEG/WebP/SVG.
+# VITE_ICON_MAX_BYTES=102400
+# VITE_ICON_ALLOWED_TYPES=image/png,image/jpeg,image/webp,image/svg+xml
+
+# Public site origin for canonical/OpenGraph/JSON-LD URLs (index.html). Committed
+# defaults live in .env.production / .env.development; a staging deploy should set
+# this so it never claims the production URL.
+# VITE_PUBLIC_URL=https://tokens.meddleware.co.uk

package/.env.production

@@ -0,0 +1,7 @@
+# Committed defaults for the standalone SPA production build (auto-loaded by `vite build`).
+# These are public Sui addresses — not secrets — so they are safe to commit.
+# Override at deploy time via Cloudflare Pages environment variables (takes precedence).
+# Local dev: copy .env.example to .env.local and edit there (never commit .env.local).
+
+VITE_FEE_TREASURY_TESTNET=0xe6b2810abfc5a6f37a375f73e3ba76cfc37584196e453255ad3c9ca2f0ede0ed
+VITE_FEE_TREASURY_MAINNET=0xe6b2810abfc5a6f37a375f73e3ba76cfc37584196e453255ad3c9ca2f0ede0ed

package/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

package/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  ci:
+    name: Lint, type-check, test, build
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v7.0.1
+
+      - uses: actions/setup-node@v6.5.0
+        with:
+          node-version: '24'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Audit dependencies
+        run: npm audit --audit-level=high
+
+      - name: Type-check
+        run: npm run type-check
+
+      - name: Unit tests
+        run: npm test
+
+      - name: Build (dev — treasury guard bypassed for CI)
+        run: VITE_ALLOW_UNSET_TREASURY=1 npm run build

package/.github/workflows/token-deployer-e2e.yml

@@ -0,0 +1,64 @@
+# Real-chain deploy e2e for blockchain/sui/apps/token-deployer-ui.
+#
+# MANUAL ONLY (workflow_dispatch). This workflow publishes a REAL token and spends REAL SUI, so
+# it is never triggered on push or pull_request — it must be started by hand and mainnet requires
+# an explicit confirmation input. The automatic gates for the package remain `npm test` (Vitest)
+# and `npm run test:e2e` (Cypress, fully mocked), which should live in a separate always-on CI job.
+#
+# Secrets required (repository or environment secrets):
+#   SUI_PRIV_TESTNET / SUI_PRIV_MAINNET  — bech32 suiprivkey1… for a funded deployer key.
+#   FEE_TREASURY_TESTNET / FEE_TREASURY_MAINNET — operator treasury address (fee recipient).
+#   RPC_TESTNET / RPC_MAINNET (optional) — JSON-RPC endpoint override (public testnet is gRPC-only).
+
+name: token-deployer real-chain e2e
+
+on:
+  workflow_dispatch:
+    inputs:
+      network:
+        description: Target network (mainnet publishes a REAL token and spends REAL SUI)
+        required: true
+        default: testnet
+        type: choice
+        options:
+          - testnet
+          - mainnet
+      confirm_mainnet:
+        description: Type "1" to confirm a mainnet run (ignored for testnet)
+        required: false
+        default: ""
+
+defaults:
+  run:
+    working-directory: blockchain/sui/apps/token-deployer-ui
+
+jobs:
+  deploy-e2e:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright Chromium
+        run: npx playwright install --with-deps chromium
+
+      - name: Run real-chain deploy e2e
+        env:
+          # Select the funded key + treasury + RPC for the chosen network.
+          SUI_PRIV: ${{ inputs.network == 'mainnet' && secrets.SUI_PRIV_MAINNET || secrets.SUI_PRIV_TESTNET }}
+          VITE_FEE_TREASURY_TESTNET: ${{ secrets.FEE_TREASURY_TESTNET }}
+          VITE_FEE_TREASURY_MAINNET: ${{ secrets.FEE_TREASURY_MAINNET }}
+          VITE_RPC_TESTNET: ${{ secrets.RPC_TESTNET }}
+          VITE_RPC_MAINNET: ${{ secrets.RPC_MAINNET }}
+          E2E_RPC: ${{ inputs.network == 'mainnet' && secrets.RPC_MAINNET || secrets.RPC_TESTNET }}
+          E2E_FEE_ADDR: ${{ inputs.network == 'mainnet' && secrets.FEE_TREASURY_MAINNET || secrets.FEE_TREASURY_TESTNET }}
+          # Mainnet fail-safe: only proceeds when the operator typed "1".
+          E2E_MAINNET_CONFIRM: ${{ inputs.network == 'mainnet' && inputs.confirm_mainnet || '' }}
+          # CHROME_PATH intentionally unset — the harness falls back to Playwright's bundled Chromium.
+        run: npm run "e2e:${{ inputs.network }}"

package/.oxfmtrc.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "./node_modules/oxfmt/configuration_schema.json",
+  "semi": false,
+  "singleQuote": true
+}

package/.oxlintrc.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "plugins": ["eslint", "unicorn", "oxc", "vue", "vitest"],
+  "env": {
+    "browser": true
+  },
+  "categories": {
+    "correctness": "error"
+  }
+}

package/.vscode/extensions.json

@@ -0,0 +1,9 @@
+{
+  "recommendations": [
+    "Vue.volar",
+    "vitest.explorer",
+    "dbaeumer.vscode-eslint",
+    "EditorConfig.EditorConfig",
+    "oxc.oxc-vscode"
+  ]
+}

package/AGENTS.md

@@ -0,0 +1,39 @@
+# AGENTS.md — token-deployer-ui
+
+Browser app for permissionless Sui token deployment. See [CLAUDE.md](CLAUDE.md) for full architecture and invariant documentation.
+
+## Responsibilities
+
+- Bytecode patching of the pre-compiled Move template (`src/lib/template.ts`)
+- PTB construction for two-phase publish + finalize (`src/lib/buildPublishTx.ts`)
+- Source package generation and zip download (`src/lib/generatePackage.ts`)
+- Walrus icon upload via the operator relay (`@meddleware/sui-walrus`)
+- NFT-gate ownership check and access-proof attachment when `VITE_ACCESS_GATE_*` is configured
+
+## Non-responsibilities
+
+- On-chain accounting or financial enforcement — the contracts handle that
+- Any backend process; no server dependency
+- Custody of keys or user funds
+
+## Testing
+
+Three distinct categories — do not collapse:
+
+1. **Unit tests** (`npm test`, Vitest): validation, template patching, PTB builders, generatePackage, deploy orchestration.
+2. **Mocked-RPC e2e** (`npm run test:e2e`, Playwright, Chromium + Firefox): UI flow with fetch mock + mock wallet. Specs live in `integrations/token-deployer/e2e/`.
+3. **Real-chain e2e** (`npm run e2e:localnet|testnet|mainnet`): publishes a real token; **never run in automatic CI**; gated by `E2E_MAINNET_CONFIRM=1` on mainnet.
+
+## Key invariants
+
+- **Template parity:** `.mv` bytes and `files.json` must derive from the same `sui-token-template` commit. Verify with `npm run verify:template`; regenerate with `npm run regen:template && npm run sync:template`.
+- **Fee integrity:** treasury fee is split from gas inside the publish PTB. The vite prod build fails if `VITE_FEE_TREASURY` is unset (`assertTreasuryConfigured`).
+- **Injection safety:** validation in `validation.ts` + independent re-assertion in `generatePackage.ts` and `template.ts`. Never remove a downstream guard.
+- **No wallet-standard proxying:** Sui wallet objects must be wrapped in `markRaw()` before storing in Vue reactive state (private-field getters crash under Vue's Proxy).
+
+## Key paths
+
+- E2e specs: `e2e/` (mocked-RPC Playwright suite; `testDir` in `playwright.config.ts`)
+- Move template: `@meddleware/sui-token-template` (`optionalDependencies` in `package.json`; local checkout at `../sui-token-template/` if working from the workspace)
+- NFT gate client: `@meddleware/nft-gate-client` (`repos/nft-gate-client/` in the workspace)
+- CI workflow: `.github/workflows/token-deployer-e2e.yml`

package/CLAUDE.md

@@ -0,0 +1,159 @@
+# CLAUDE.md — `token-deployer-ui`
+
+`@meddleware/token-deployer-ui` is a Vue 3 + Vite browser app that lets any user deploy
+their own Sui coin fully client-side (their wallet signs + pays gas + a trivial fee to
+the operator treasury) and download a matching source package. It is the browser
+equivalent of the `@meddleware/sui-token-template` Move package (from which it derives
+its pre-compiled bytecode and source templates). See the repo-root
+[CLAUDE.md](../../../../CLAUDE.md) for context and [README.md](README.md) for the
+user/operator guide.
+
+## Dual app + library pattern
+
+This package ships as both a **standalone SPA** and an **embeddable library component**:
+
+- **Standalone SPA** (`npm run dev` / `npm run build`): `src/main.ts` mounts `App.vue`, which
+  is a thin shell that renders `WalletBar` + `TokenDeployerView`. All deploy logic lives in
+  `TokenDeployerView` — `App.vue` contains no state.
+- **Library component** (consumed by `@meddleware/dashboard`): `src/index.ts` exports
+  `TokenDeployerView`, which is imported via the `exports["."]` entry in `package.json`. The
+  dashboard's Vite build resolves TypeScript source directly — no separate lib build step.
+  The dashboard supplies the wallet connection via `@meddleware/wallet-adapter`'s shared
+  module singleton; `TokenDeployerView` reads `useWallet()` / `useNetwork()` from it and is
+  wrapped in `WalletGuard` so it shows a connect prompt when no wallet is connected.
+
+The pattern mirrors `@meddleware/walrus-ui`, `@meddleware/seal-ui`, and
+`@meddleware/access-gate-ui`. See the dashboard `CLAUDE.md` for the invariant: every tool view
+must **not** render its own wallet bar, header, or footer when embedded.
+
+**Deploy executor note:** The wallet-adapter `Executor` only returns `{ digest }` — insufficient
+for the deploy flow, which requires `objectChanges` to extract the packageId, coin type,
+TreasuryCap, and MetadataCap. `src/lib/deployExecutor.ts` uses the wallet-adapter singleton for
+wallet connection state, but builds its own `SuiJsonRpcClient` (`@mysten/sui/jsonRpc`) to execute
+with `showEffects + showObjectChanges`. This is intentional — do not replace it with the
+wallet-adapter `buildExecutor`.
+
+## Architecture (the money/parity paths matter most)
+
+- **Bytecode patching** — [src/lib/template.ts](src/lib/template.ts) deserialises
+  one pre-compiled template module ([src/move-template/](src/move-template/)),
+  renames the module/OTW-struct identifiers in place, and overwrites five DISTINCT
+  named constants (decimals, symbol, name, description, iconUrl), then re-serialises.
+  Binary format v7 cannot be round-tripped by `update_identifiers`/`update_constants`
+  ("missing field version"); `deserialize`→mutate JSON→`serialize` is the path.
+- **Two-phase publish** — TreasuryCap/MetadataCap are created in `init()` and sent
+  to the sender, so they are NOT `tx.publish` results. Publish PTB
+  ([src/lib/buildPublishTx.ts](src/lib/buildPublishTx.ts)) = publish + UpgradeCap
+  policy + fee split from gas. A finalize PTB (only when needed —
+  `needsFinalize`) mints supply and applies supply/metadata policies.
+- **Orchestration** — [src/lib/deploy.ts](src/lib/deploy.ts) sequences patch →
+  publish → wait → (finalize) via an injectable `Executor` (so it is unit-testable;
+  the real one is built from the wallet in
+  [src/composables/useWallet.ts](src/composables/useWallet.ts)).
+- **Package generation** — [src/lib/generatePackage.ts](src/lib/generatePackage.ts)
+  substitutes the same inputs into the canonical template text
+  ([src/template-src/files.json](src/template-src/files.json)) and zips it.
+
+## Invariants (do not break)
+
+1. **Bytecode ↔ source parity.** The shipped `.mv` and `files.json` must both derive
+   from the same `sui-token-template` commit. Enforced by
+   [tests/templateArtifact.test.ts](tests/templateArtifact.test.ts) (defaults present
+   in the `.mv`) and [tests/templateParity.test.ts](tests/templateParity.test.ts)
+   (`files.json` == canonical sources). After changing the template run
+   `npm run regen:template && npm run sync:template && npm run verify:template`.
+2. **Injection safety is layered.** `validation.ts` gates the form, but
+   `generatePackage.ts` (`assertSafeConfig`) and `template.ts` (`patchVecConstant`)
+   re-assert `SAFE_TEXT`/`MOVE_IDENT`/length/keyword rules independently. Never
+   remove a downstream guard on the assumption the form already checked.
+3. **Fee integrity.** The fee is split from `tx.gas` to the config treasury inside
+   the publish PTB. The vite production build fails on a zero-address treasury
+   (`assertTreasuryConfigured` in [vite.config.ts](vite.config.ts)).
+4. **No backend / no custody / no endorsement.** Keep all financial truth on-chain;
+   the app only previews and constructs transactions. Do not add a server dependency.
+5. **Lazy heavy deps.** `@mysten/walrus` and `@mysten/move-bytecode-template` (wasm)
+   are loaded on demand (dynamic import / `?url`). Keep the shared `ICON_EPOCHS`
+   constant in [src/lib/walrus-constants.ts](src/lib/walrus-constants.ts) so the
+   eagerly-rendered widget doesn't pull the Walrus chunk into the main bundle.
+
+## Walrus icons
+
+Icons are RAW blobs (not quilts) so `GET /v1/blobs/<id>` renders the exact image;
+an upload relay is required from browsers. `ICON_EPOCHS = 53` (Walrus's
+`max_epochs_ahead`; a larger single reservation aborts). Longer retention needs
+`extendBlobLifetime` (no keeper — operator step). Verified on testnet via
+`scripts/e2e-walrus-browser.mjs`.
+
+## Walrus relay economics & deferred decisions
+
+The icon upload can charge users per upload via Walrus's **native relay tip** —
+no custom backend. This section records the decisions and their rationale so they
+survive independently of any planning doc. (Verified against walrus SDK 1.1.7 and
+the relay source `crates/walrus-upload-relay`.)
+
+- **Native `linear` tip is enforced on-chain — chosen for launch.** `register`
+  bakes an auth payload `blobDigest ‖ SHA256(nonce) ‖ size` **plus** a tip transfer
+  to the operator's address into the *same* tx the user signs. The relay verifies
+  that on-chain tip (amount checked against the *actual received body length*, bound
+  by nonce/size) **before** the expensive storage-node fan-out. Stripping or lowering
+  the tip → the relay rejects the upload; no operator cost. This refutes an earlier
+  finding that the tip "could be removed" — it is enforced now.
+- **The relay does no on-chain tx** (README L27) → the operator never pays gas.
+  Storage (WAL) is paid by the **user** at registration; read/serve bandwidth is the
+  separate public **aggregator**. The tip only needs to cover the relay's
+  ingress + fan-out egress + RPC lookups.
+- **NFT / usage-ticket per-wallet gating is IMPLEMENTED (2026-08-05)** via the standalone
+  `nft-gate` project: an `nft-gate` gateway fronts the operator relay and admits only
+  holders of an `access_gate` NFT. The app gates the operator-relay option on ownership
+  (`useAccessGate` → `getOwnedObjects`), offers a permissionless purchase CTA, and attaches
+  a wallet-signed access proof (`sui:signPersonalMessage` → `uploadRelayAuthToken`) when the
+  operator relay is used. Unset `VITE_ACCESS_GATE_*` → no gating (unchanged behaviour). The
+  tip and the NFT are **independent levers** (tip = per-upload cost; NFT = access/abuse).
+- **Per-wallet rate limiting** — previously rejected at the edge (which can't resolve the
+  wallet), it is now enforced by the `nft-gate` gateway *after* verification. Keep a per-IP
+  edge limit as a coarse pre-auth control.
+- **Autonomous price-fed tip tuner DEFERRED** — the relay reads its tip only at
+  **startup** (no hot-reload/SIGHUP), so adjusting = rewrite YAML + restart. That's a
+  keeper with a liveness dependency. For launch use a **single static tip with a fat
+  SUI-denominated margin**: icons are cents-scale, so a large margin costs users
+  nothing and absorbs *both* SUI/fiat drift and storage-node retry amplification in
+  one lever. A later tuner (read Pyth on-chain, clamp to `[min,max]`, rolling-restart)
+  must stay under the client `max` headroom below.
+- **Client `WALRUS_MAX_TIP_MIST` ↔ relay-tip COUPLING** — the SDK **throws** if the
+  relay's tip exceeds this client ceiling ([config.ts](src/config.ts) documents it).
+  Set it with generous headroom above the relay tip; raising the relay tip past it
+  needs a frontend redeploy.
+- **Client-side icon size/type limits are UX only — NOT security.** The authoritative
+  cap is a hard request-body limit at the edge (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). See the relay runbook in [README.md](README.md).
+
+## Testing
+
+Three distinct categories — do not collapse them (repo convention):
+
+- **Pure unit (Vitest, `npm test`):** validation, licenses, github, template patch, PTB
+  builders, generatePackage, deploy orchestration, provenance/parity.
+- **Mocked-RPC UI e2e (Playwright, `npm run test:e2e`):** wallet/form/publish flow against the
+  `VITE_E2E` fetch mock + mock wallet in [src/main.ts](src/main.ts) (tree-shaken from prod). Specs
+  live in `e2e/` (`playwright.config.ts` builds with `VITE_E2E=1` + previews). **Migrated from Cypress
+  2026-08-07** (Cypress dropped — it exits SIGILL in the sandbox; Playwright is the one browser-e2e
+  tool now, shared with the real-chain harness). Run `npm run e2e:install` once, then `npm run test:e2e`.
+  Cannot reach real confirmation, the result panel, or the source download — those need a real chain
+  (see below). This is the automatic gate alongside `npm test`.
+- **Real-chain deploy e2e (Playwright, NOT in `npm test`):** `scripts/e2e-deploy.mjs` — the
+  single network-parametrized harness (`E2E_NETWORK=localnet|testnet|mainnet`) driven by
+  `npm run e2e:localnet|e2e:testnet|e2e:mainnet`. Injects a wallet-standard wallet backed by a
+  node keypair, does a REAL publish, waits for real confirmation, checks the result panel,
+  downloads the zip, and verifies coin type + fee on-chain. Two axes are distinct: `E2E_NETWORK`
+  (physical chain) vs the app network (testnet/mainnet UI mode; localnet borrows testnet mode with
+  the RPC pointed at the local node). Mainnet is fail-safe: aborts unless `E2E_MAINNET_CONFIRM=1`.
+  `scripts/e2e-browser.mjs` is a thin `E2E_NETWORK=localnet` wrapper; `scripts/e2e-walrus-browser.mjs`
+  (testnet icon upload) uses the E2E-only `window.__getSuiClient` hook in `src/main.ts`. Testnet/
+  mainnet are **manual only** — never in automatic CI (see the README launch runbook). The
+  `.github/workflows/token-deployer-e2e.yml` `workflow_dispatch` job is the gated manual runner.
+
+## Docs
+
+TSDoc on every exported symbol in `src/lib`, `src/composables`, and `src/config.ts`;
+`npm run docs` renders a TypeDoc site to `docs/api/` (config: [typedoc.json](typedoc.json)).

package/LICENSE

@@ -0,0 +1,121 @@
+Creative Commons Legal Code
+
+CC0 1.0 Universal
+
+    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
+    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
+    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+    HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without fear
+of later claims of infringement build upon, modify, incorporate in other
+works, reuse and redistribute as freely as possible in any form whatsoever
+and for any purposes, including without limitation commercial purposes.
+These owners may contribute to the Commons to promote the ideal of a free
+culture and the further production of creative, cultural and scientific
+works, or to gain reputation or greater distribution for their Work in
+part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or she
+is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under its
+terms, with knowledge of his or her Copyright and Related Rights in the
+Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not
+limited to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display,
+     communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+     likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+     subject to the limitations in paragraph 4(a), below;
+  v. rights protecting the extraction, dissemination, use and reuse of data
+     in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+     European Parliament and of the Council of 11 March 1996 on the legal
+     protection of databases, and under any national implementation
+     thereof, including any amended or successor version of such
+     directive); and
+vii. other similar, equivalent or corresponding rights throughout the
+     world based on applicable law or treaty, and any national
+     implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
+member of the public at large and to the detriment of Affirmer's heirs and
+successors, fully intending that such Waiver shall not be subject to
+revocation, rescission, cancellation, termination, or any other legal or
+equitable action to disrupt the quiet enjoyment of the Work by the public
+as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non exclusive,
+irrevocable and unconditional license to exercise Affirmer's Copyright and
+Related Rights in the Work (i) in all territories worldwide, (ii) for the
+maximum duration provided by applicable law or treaty (including future
+time extensions), (iii) in any current or future medium and for any number
+of copies, and (iv) for any purpose whatsoever, including without
+limitation commercial, advertising or promotional purposes (the
+"License"). The License shall be deemed effective as of the date CC0 was
+applied by Affirmer to the Work. Should any part of the License for any
+reason be judged legally invalid or ineffective under applicable law, such
+partial invalidity or ineffectiveness shall not invalidate the remainder
+of the License, and in such case Affirmer hereby affirms that he or she
+will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of
+action with respect to the Work, in either case contrary to Affirmer's
+express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+    surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+    warranties of any kind concerning the Work, express, implied,
+    statutory or otherwise, including without limitation warranties of
+    title, merchantability, fitness for a particular purpose, non
+    infringement, or the absence of latent or other defects, accuracy, or
+    the present or absence of errors, whether or not discoverable, all to
+    the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+    that may apply to the Work or any use thereof, including without
+    limitation any person's Copyright and Related Rights in the Work.
+    Further, Affirmer disclaims responsibility for obtaining any necessary
+    consents, permissions or other rights required for any use of the
+    Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+    party to this document and has no duty or obligation with respect to
+    this CC0 or use of the Work.