docs(web-demo): add consumer config matrix for retail and UI

Document planned CONSUMER_PROFILE setups and map demo routes to
production patterns from bitgo-retail and bitgo-ui.

WEB-000

Author: mmcshinsky-bitgo

modules/web-demo/README.md

@@ -1,13 +1,63 @@
 # web-demo
 
-This module serves as an example on how you can integrate the BitGo SDK into your own UI.
+Reference UI for integrating the BitGo SDK in the browser. Routes mirror problems solved in production apps (**bitgo-retail**, **bitgo-ui**) using SDK packages directly — no private `@bitgo-private/*` dependencies.
 
-## Usage
+## Quick start
 
-In order to start the server, run the following command after having already run `yarn install` in the root of the repo.
+From the BitGoJS repo root (after `yarn install`):
 
-```
+```bash
+cd modules/web-demo
 yarn dev
 ```
 
-This will spin up a server serving the UI at [localhost:8080](localhost:8080).
+Opens [localhost:8080](http://localhost:8080).
+
+## Consumer config matrix
+
+Production apps bundle the SDK differently. web-demo will support **consumer profiles** (via `CONSUMER_PROFILE` env) so each profile documents one real-world setup. Profiles are added incrementally; only `classic-webpack` is active today.
+
+| Profile | Status | Mirrors | Bundler | WASM | SDK auth |
+| --- | --- | --- | --- | --- | --- |
+| `classic-webpack` | **active** (default) | bitgo-ui classic app, default web-demo | Webpack + [`webpack/bitgojs.config.js`](../../webpack/bitgojs.config.js) | Partial ESM aliases in shared config | Access token or `/webcrypto-auth` |
+| `retail-browser` | planned | bitgo-retail web (`MOBILE_MODE` off) | Webpack profile | Full `@bitgo/wasm-*` ESM paths, DKLS/cardano browser swaps | `WebCryptoHmacStrategy` + `requestIdPrefix` |
+| `retail-mobile-stub` | planned | bitgo-retail mobile webview | Webpack profile | Empty WASM shims (no heavy signing WASM) | Bridge / token (documented only) |
+| `direct-sdk` | planned | bitgo-retail mock server, `examples/ts` | Either | Per profile | `BitGoAPI` + `customRootURI`, no Express |
+| `express-proxy` | planned | Self-hosted Express users | Either | Per profile | Local Express signing proxy |
+
+**Planned usage** (not wired yet):
+
+```bash
+yarn dev                                          # classic-webpack
+CONSUMER_PROFILE=retail-browser yarn dev          # future
+CONSUMER_PROFILE=retail-mobile-stub yarn dev      # future
+```
+
+### What each production app solved
+
+| Problem | bitgo-retail | bitgo-ui | web-demo route |
+| --- | --- | --- | --- |
+| Browser WASM loading | Vite ESM aliases for `@bitgo/wasm-utxo`, `wasm-ton`, `wasm-mps` | Webpack aliases (similar) | `/wasm-miniscript` |
+| HMAC without raw token in storage | `WebCryptoHmacStrategy` + IndexedDB | Classic token flow | `/webcrypto-auth` |
+| Passkey PRF wallet flows | `@bitgo-private/web-client` (retail); SDK: `@bitgo/passkey-crypto` | Partial | `/passkey-demo` |
+| Keycard generation | `@bitgo/key-card` in wallet create / migration | Keycard flows | `/keycard` |
+| Lazy coin registration | `retail-sdk-client/coinFactory` | `~/utils/coinFactory` | `/coins` |
+| Token enable prebuild | React Query + `PrebuildTransactionResult` | `useBuildTokenEnablementMutation` | planned `/token-enable` |
+
+## Demo routes
+
+| Path | Description |
+| --- | --- |
+| `/` | Home |
+| `/bitgo-js` | BitGo SDK object inspect |
+| `/bitgo-api` | BitGoAPI usage |
+| `/coins` | Coin factory / registration |
+| `/keycard` | Keycard download fixtures |
+| `/wasm-miniscript` | WASM miniscript smoke |
+| `/ecdsachallenge` | ECDSA challenge generation |
+| `/webcrypto-auth` | WebCrypto HMAC strategy + IndexedDB session |
+| `/passkey-demo` | Passkey register / attach / wallet (uses `@bitgo/passkey-crypto`) |
+
+## Contributing
+
+Owned by **@BitGo/web-experience** (`CODEOWNERS`). Prefer small PRs: one profile, one route, or one README section at a time. See the local BitGoJS side-improvements plan for micro-PR sizing.

scripts/prepare-commit-msg.js

@@ -5,21 +5,30 @@ const childProcess = require('child_process');
 const fs = require('fs');
 const exec = promisify(childProcess.exec);
 
-// ex WP-1234 or WEB-000 (case-insensitive)
-const branchRegex = /([A-Za-z]+-)(\d+)/i;
+// Build regex from commitlint's known issuePrefixes so arbitrary branch segments
+// (e.g. "release-2-hotfix") don't produce bogus TICKET footers.
+const { issuePrefixes } = require('../commitlint.config.js').parserPreset.parserOpts;
+const escapedPrefixes = issuePrefixes
+  .filter((p) => p !== '#')
+  .map((p) => p.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+// Anchored at branch start; case-insensitive so "web-000-desc" matches "WEB-"
+const branchRegex = new RegExp(`^(${escapedPrefixes.join('|')})(\\d+)`, 'i');
 // ex TICKET: WP-1234
 const commitRegex = /(ticket|issue):\s(\S+)/gim;
 
+function extractTicket(branch) {
+  const found = branch.match(branchRegex);
+  return found ? found[0].toUpperCase() : null;
+}
+
 async function main() {
   const commitMsgFilepath = process.argv[2];
   try {
     const branch = (await exec(`git branch --show-current`)).stdout.trim();
-    const found = branch.match(branchRegex);
-    // Do not append message if branch name does not match regex
-    if (!found) {
+    const ticket = extractTicket(branch);
+    if (!ticket) {
       return;
     }
-    const ticket = found[0].toUpperCase();
     const data = fs.readFileSync(commitMsgFilepath, 'utf8');
     // Exit if ticket is already in commit footer
     if (data.match(commitRegex)) {
@@ -29,4 +38,5 @@ async function main() {
   } catch (e) {}
 }
 
+module.exports = { extractTicket };
 main();

scripts/tests/prepare-commit-msg.test.js

@@ -0,0 +1,26 @@
+const assert = require('assert');
+const { extractTicket } = require('../prepare-commit-msg');
+
+describe('extractTicket', () => {
+  it('extracts uppercase ticket from uppercase branch', () => {
+    assert.strictEqual(extractTicket('WEB-000-my-feature'), 'WEB-000');
+  });
+
+  it('extracts and uppercases ticket from lowercase branch', () => {
+    assert.strictEqual(extractTicket('web-000-my-feature'), 'WEB-000');
+  });
+
+  it('extracts WP ticket', () => {
+    assert.strictEqual(extractTicket('WP-1234-some-work'), 'WP-1234');
+  });
+
+  it('returns null for branches without a known prefix', () => {
+    assert.strictEqual(extractTicket('release-2-hotfix'), null);
+    assert.strictEqual(extractTicket('main'), null);
+    assert.strictEqual(extractTicket('feature-no-ticket'), null);
+  });
+
+  it('returns null for empty branch', () => {
+    assert.strictEqual(extractTicket(''), null);
+  });
+});