@bwalletx/connect 0.1.0 → 0.3.0

package/BRAND.md

@@ -0,0 +1,84 @@
+# Sign in with bWalletX: brand guidelines
+
+The standard button is the gold one from bit-sign's sign-in card. Use `<bwalletx-signin>` (or the React wrapper) and you get it right by default. These rules are for when you place it, size it, or draw your own.
+
+## Variants and where to use them
+
+| Variant | Use it for |
+|---|---|
+| `theme="gold"` (default) | The main way in. Sign-in pages, the first button in a list of sign-in options. |
+| `theme="dark"` | Dark UIs where gold would compete with your own primary button, or a secondary row of sign-in options. |
+| `theme="light"` | Light pages, and lists of outlined "Continue with …" buttons beside Google, Apple and so on. |
+| `size="lg"` (default) | Sign-in cards and landing pages. Shows the subtitle. |
+| `size="md"` | Dialogs and narrow cards. Shows the subtitle. |
+| `size="sm"` | Navigation bars and toolbars. No subtitle. |
+| `size="icon"` | Only where space is very tight and the context already says "sign in" (a row of provider icons). Always keep the aria-label. |
+| `label="signin"` / `"continue"` / `"connect"` | "Sign in with" on sign-in pages, "Continue with" in mixed provider lists and onboarding, "Connect" when the user is already signed in and is linking a wallet. |
+| `brand="bWallet"` | Store builds and pages shown inside the App Store / Play edition. Drops the subtitle. |
+
+## Do
+
+- Keep the black circle with the gold "b" on the left of the text.
+- Keep the text exactly as given ("Sign in with bWalletX", "Continue with bWalletX", "Connect bWalletX"). Translations are fine.
+- Give the gold button the most prominent position when bWalletX is your main sign-in.
+- Keep the subtitle "also works with bWallet" on lg and md, so store users know the button is for them.
+- Make it the same height as the other sign-in buttons next to it.
+
+## Don't
+
+- Don't recolour the gold, change the gradient direction, or put the mark on a coloured circle.
+- Don't stretch, rotate, outline or add effects to the mark.
+- Don't use the "b" mark alone as a generic Bitcoin or wallet icon.
+- Don't write "BWalletX", "bwalletx", "B Wallet X" or "bWallet X" in the button.
+- Don't make the bWalletX button smaller or less visible than other providers' buttons in the same list.
+- Don't imply that bWalletX endorses your product.
+
+## Minimum sizes
+
+| | Minimum |
+|---|---|
+| Button height | 36px (`sm`). 48px or more on touch screens (`md`, `lg`, `icon`). |
+| Icon-only button | 40px across. 48px recommended. |
+| Mark on its own | 16px tall on screen, 6mm in print. |
+| Label text | 13px. Subtitle 10.5px, and only on `md` and `lg`. |
+
+## Clear space
+
+Leave space around the button equal to half its height (at least 8px) free of other text and logos. Around the mark on its own, leave the width of the mark's bowl (about a third of the mark's height).
+
+## Colours
+
+| Token | Value |
+|---|---|
+| Gold gradient top / bottom | `#fcd34d` → `#f59e0b` (hover `#fde68a` → `#fbbf24`) |
+| Mark gradient | `#FFE58A` → `#FFD24D` (55%) → `#C98F00` |
+| Mark circle | `#000000` |
+| Label on gold | `#000000`, subtitle `rgba(0,0,0,.65)` |
+| Corner radius | 12px (lg), 10px (md), 8px (sm), round (icon) |
+| Shadow (gold) | `0 10px 15px -3px rgba(245,158,11,.2), 0 4px 6px -4px rgba(245,158,11,.2)` |
+
+Black on the gold gradient is above 9:1, and the subtitle stays above 4.5:1 (WCAG AA) at every point of the gradient.
+
+## bApp shell (bar, top bar, drawer)
+
+The shell copies the bWalletX dock exactly. Don't restyle it per app; `theme.accent` in bapp.json is the only override.
+
+| Token | Value |
+|---|---|
+| Bar | 88px, background `#0A0B0D`, 1px top hairline `#1C1C1E` |
+| Slot icons | 20px, inactive `#F2F2F0`, active `#FFD24D` |
+| Slot labels | 10px, `#98A2B3`; active gold and bold |
+| (b) | 52px black disc, 2px gold ring, snug in the bar (no float gap) |
+| Disabled slot | 35% opacity, not clickable, never hidden |
+| Top bar | 28px strip + 56px row; round 36px tools, ring `#2A2A2C`, icons `#F5B800` |
+| Order | Wallet · Exchange · (b) · Feed · Chat. Top left: ☰ (in the wallet) then the app icon; ✕ on the right in the wallet |
+
+Wording on Feed likes: "fund", "back", "support". Never "invest", "returns" or "earn".
+
+## Files
+
+`assets/` has the mark (`bwalletx-mark.svg`, `bwalletx-mark-circle.svg`), full buttons (`signin-gold.svg`, `signin-dark.svg`, `signin-light.svg`) and a no-JavaScript HTML/CSS version (`snippet.html`).
+
+## Trademarks
+
+The code in this package is MIT. The names bWalletX and bWallet, and the "b" mark, are not covered by that licence. See [TRADEMARKS.md](./TRADEMARKS.md).

package/README.md

@@ -14,6 +14,45 @@ pnpm add @bwalletx/connect @bsv/sdk
 
 `@bsv/sdk` (2.2 or later, 2.x or 3.x) is a peer dependency.
 
+## The button
+
+`<bwalletx-signin>` is the standard "Sign in with bWalletX" button: a web component with no dependencies (Shadow DOM), plus a React wrapper. It is the gold button from bit-sign's sign-in card.
+
+```html
+<script src="https://unpkg.com/@bwalletx/connect@0.2.0"></script>
+<bwalletx-signin challenge-url="/auth/bwalletx/challenge" verify-url="/auth/bwalletx/verify"></bwalletx-signin>
+<script>
+  document.addEventListener('bwalletx-signed-in', (e) => location.assign('/'));
+</script>
+```
+
+With a bundler: `import '@bwalletx/connect/element'` registers the element. In React:
+
+```tsx
+import { BwalletxSignin } from '@bwalletx/connect/react';
+
+<BwalletxSignin challengeUrl="/auth/bwalletx/challenge" verifyUrl="/auth/bwalletx/verify" onSignedIn={(d) => console.log(d.identityKey)} />
+```
+
+| Attribute | Values |
+|---|---|
+| `size` | `lg` (default), `md`, `sm`, `icon` |
+| `theme` | `gold` (default), `dark`, `light` |
+| `label` | `signin` (default), `continue`, `connect` |
+| `brand` | `bWalletX` (default), `bWallet` (store edition) |
+| `subtitle` | `on`, `off`, or your own text. Default "also works with bWallet" on lg/md |
+| `full-width`, `loading`, `disabled` | flags |
+| `challenge-url`, `verify-url` | run the sign-in flow on click: POST `{ identityKey }`, then POST `{ identityKey, nonce, signature }` |
+| `get-url`, `web-url` | where "Get bWalletX" and the web wallet link go (bwalletx.com/get, web.bwalletx.com) |
+| `href` | navigate on click instead |
+| `authorize-url`, `client-id`, `redirect-uri`, `scope` | OAuth 2.1 redirect with S256 PKCE (verifier, state and nonce in `sessionStorage["bwalletx:oauth"]`). For auth.bwalletx.com, which is planned and not live yet |
+
+Events (bubbling, composed): `bwalletx-signin` on every click (call `preventDefault()` to run your own flow instead), `bwalletx-signed-in` with `{ identityKey, method, nonce, signature, response }`, `bwalletx-not-found` (the button then shows "Get bWalletX" and a web wallet link), `bwalletx-error` with `{ error }`.
+
+Without `challenge-url`, `href` or `authorize-url` the button only fires `bwalletx-signin`. The built-in flow uses the extension or in-app browser only. For phone pairing, listen for `bwalletx-signin`, call `preventDefault()`, and call `signInWithBwalletX` with `pairing` as shown above.
+
+SVG files, and an HTML/CSS version with no JavaScript, are in `assets/`. All variants: `examples/buttons.html`. Placement, sizes and do/don't: [BRAND.md](./BRAND.md). The names and logo are not MIT licensed: [TRADEMARKS.md](./TRADEMARKS.md).
+
 ## Server
 
 ```ts
@@ -153,6 +192,50 @@ The phone sends a plain `hello` and then, as soon as the user taps Connect, an e
 
 This build includes `@bsv/sdk` (about 125 KB minified). The server functions are not in it.
 
+## bApp shell
+
+`@bwalletx/connect/shell` gives every bApp the same 5-slot bar as the bWalletX dock: **Wallet · Exchange · (b) · Feed · Chat**, each scoped to your app. Your app's Home and sections live in a drawer opened from the app icon, top left. On the web the package draws the bar; inside bWalletX it hides it and the wallet's native dock drives your app instead.
+
+![bApp shell at 390px](docs/screens/shell-390.png)
+
+1. Serve `/.well-known/bapp.json` (schema: [`schema/bapp.schema.json`](schema/bapp.schema.json), sample: [`examples/bapp.bmovies.json`](examples/bapp.bmovies.json)). All paths are same-origin; a slot you don't use is `"enabled": false` (shown greyed out, never hidden).
+2. Add the elements:
+
+```html
+<bwalletx-topbar drawer="sections"></bwalletx-topbar>
+<main>…</main>
+<bwalletx-drawer id="sections"></bwalletx-drawer>
+<bwalletx-bar active="feed"></bwalletx-bar>
+<script type="module">
+  import { defineBappShell, loadManifest, applyManifest, startShellBridge } from '@bwalletx/connect/shell';
+  defineBappShell();
+  const manifest = await loadManifest();      // fetches and validates /.well-known/bapp.json
+  applyManifest(manifest);
+  startShellBridge({ manifest });             // inside bWalletX: hide the bar, follow the wallet's dock
+</script>
+```
+
+React:
+
+```tsx
+import { BappTopbar, BappDrawer, BappBar } from '@bwalletx/connect/shell/react';
+<BappTopbar manifest={m} drawer="sections" />
+<BappDrawer id="sections" manifest={m} manualNavigation onNavigate={(d) => router.push(d.path!)} />
+<BappBar manifest={m} active={slot} manualNavigation onNavigate={(d) => router.push(d.path!)} />
+```
+
+No bundler: `<script src="https://unpkg.com/@bwalletx/connect/dist/bwalletx-shell.global.js">` registers the elements and exposes `window.bWalletXShell`.
+
+| Element | Attributes | Events (bubble, composed) |
+|---|---|---|
+| `<bwalletx-bar>` | `active`, `in-wallet` (`auto`/`true`/`false`), `navigate="manual"`; property `manifest` | `bapp-navigate {slot, path}` (cancelable), `bapp-active {slot}`, `bapp-b-press`, `bapp-b-hold {phase}` |
+| `<bwalletx-topbar>` | `title`, `subtitle`, `drawer` (id), `menu="true"`, `strip="off"`, `in-wallet`; slots `strip-left`, `strip-right`, `tools` | `bapp-menu`, `bapp-close`, `bapp-drawer-toggle` (cancelable) |
+| `<bwalletx-drawer>` | `open`, `current` (path), `in-wallet`, `navigate="manual"` | `bapp-navigate {path}` (cancelable), `bapp-close` |
+
+`bapp-navigate` goes to the manifest path with `location.assign` unless you call `preventDefault()` or set `navigate="manual"`, so SPAs route themselves. Inside the wallet, ☰ and ✕ appear in the top bar and the drawer gets "Back to bWalletX".
+
+API: `validateManifest(json)` → `{ok, manifest, errors}`, `parseManifest`, `loadManifest(path?)`, `isSameOriginPath`, `slotPath`, `detectWalletUA(ua?)`, `walletState()`, `ShellBridge` / `startShellBridge({manifest, walletOrigins?})`, `defineBappShell()`, `applyManifest(m)`, `TOKENS`. The wallet message protocol is in [docs/SHELL-PROTOCOL.md](docs/SHELL-PROTOCOL.md). Demo: `examples/shell.html` (after `pnpm build`; `?wallet=1` shows the in-wallet top bar, `#drawer` opens the drawer).
+
 ## Limits
 
 - You get the identity key and nothing else: no handle, paymail or name.

package/TRADEMARKS.md

@@ -0,0 +1,9 @@
+# Trademarks
+
+bWalletX, bWallet and the gold "b" mark are trademarks of The Bitcoin Corporation Ltd. The MIT licence in [LICENSE](./LICENSE) covers the code in this package. It does not grant any right to the names or the logo.
+
+You may use the names and the mark, unchanged, to let your users sign in with bWalletX or bWallet: the button in this package, the SVG files in `assets/`, and text such as "Sign in with bWalletX". Follow [BRAND.md](./BRAND.md) when you do.
+
+You may not use them in your own product, company or domain name, in a way that suggests bWalletX sponsors or endorses you, or in a changed form.
+
+Questions: https://bwalletx.com

package/assets/bwalletx-mark-circle.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 120 120" role="img" aria-label="bWalletX"><defs><linearGradient id="g" gradientUnits="userSpaceOnUse" x1="0" y1="12" x2="0" y2="105"><stop offset="0" stop-color="#FFE58A"/><stop offset=".55" stop-color="#FFD24D"/><stop offset="1" stop-color="#C98F00"/></linearGradient><mask id="h"><rect width="140" height="140" fill="#fff"/><circle cx="60" cy="72" r="15" fill="#000"/></mask></defs><circle cx="60" cy="60" r="60" fill="#000"/><g transform="translate(60 60) scale(.62) translate(-60 -58)"><g fill="url(#g)" mask="url(#h)"><polygon points="45,12 45,76 27,76 27,30"/><circle cx="60" cy="72" r="33"/></g></g></svg>

package/assets/bwalletx-mark.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="23 8 74 100" role="img" aria-label="bWalletX"><defs><linearGradient id="g" gradientUnits="userSpaceOnUse" x1="0" y1="12" x2="0" y2="105"><stop offset="0" stop-color="#FFE58A"/><stop offset=".55" stop-color="#FFD24D"/><stop offset="1" stop-color="#C98F00"/></linearGradient><mask id="h"><rect width="140" height="140" fill="#fff"/><circle cx="60" cy="72" r="15" fill="#000"/></mask></defs><g fill="url(#g)" mask="url(#h)"><polygon points="45,12 45,76 27,76 27,30"/><circle cx="60" cy="72" r="33"/></g></svg>

package/assets/signin-dark.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="260" height="60" viewBox="0 0 260 60" role="img" aria-label="Sign in with bWalletX, also works with bWallet">
+<defs><linearGradient id="g" gradientUnits="userSpaceOnUse" x1="0" y1="12" x2="0" y2="105"><stop offset="0" stop-color="#FFE58A"/><stop offset=".55" stop-color="#FFD24D"/><stop offset="1" stop-color="#C98F00"/></linearGradient><mask id="h"><rect width="140" height="140" fill="#fff"/><circle cx="60" cy="72" r="15" fill="#000"/></mask><linearGradient id="bg" x1="0" y1="0" x2="0" y2="1"><stop offset="0" stop-color="#fcd34d"/><stop offset="1" stop-color="#f59e0b"/></linearGradient></defs>
+<rect x="1" y=".5" width="252" height="59" rx="12" fill="#0a0a0a" stroke="#3f3f46" stroke-width="1"/>
+<circle cx="38" cy="30" r="14" fill="#000"/>
+<g transform="translate(38 30) scale(.2) translate(-60 -58)"><g fill="url(#g)" mask="url(#h)"><polygon points="45,12 45,76 27,76 27,30"/><circle cx="60" cy="72" r="33"/></g></g>
+<text x="64" y="28" font-family="Inter, ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif" font-size="16" font-weight="700" fill="#fafafa">Sign in with bWalletX</text>
+<text x="64" y="42" font-family="Inter, ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif" font-size="11" font-weight="500" fill="rgba(255,255,255,.65)">also works with bWallet</text>
+</svg>

package/assets/signin-gold.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="260" height="60" viewBox="0 0 260 60" role="img" aria-label="Sign in with bWalletX, also works with bWallet">
+<defs><linearGradient id="g" gradientUnits="userSpaceOnUse" x1="0" y1="12" x2="0" y2="105"><stop offset="0" stop-color="#FFE58A"/><stop offset=".55" stop-color="#FFD24D"/><stop offset="1" stop-color="#C98F00"/></linearGradient><mask id="h"><rect width="140" height="140" fill="#fff"/><circle cx="60" cy="72" r="15" fill="#000"/></mask><linearGradient id="bg" x1="0" y1="0" x2="0" y2="1"><stop offset="0" stop-color="#fcd34d"/><stop offset="1" stop-color="#f59e0b"/></linearGradient></defs>
+<rect x="0" y=".5" width="252" height="59" rx="12" fill="url(#bg)" stroke="none" stroke-width="0"/>
+<circle cx="38" cy="30" r="14" fill="#000"/>
+<g transform="translate(38 30) scale(.2) translate(-60 -58)"><g fill="url(#g)" mask="url(#h)"><polygon points="45,12 45,76 27,76 27,30"/><circle cx="60" cy="72" r="33"/></g></g>
+<text x="64" y="28" font-family="Inter, ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif" font-size="16" font-weight="700" fill="#000">Sign in with bWalletX</text>
+<text x="64" y="42" font-family="Inter, ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif" font-size="11" font-weight="500" fill="rgba(0,0,0,.65)">also works with bWallet</text>
+</svg>

package/assets/signin-light.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="260" height="60" viewBox="0 0 260 60" role="img" aria-label="Sign in with bWalletX, also works with bWallet">
+<defs><linearGradient id="g" gradientUnits="userSpaceOnUse" x1="0" y1="12" x2="0" y2="105"><stop offset="0" stop-color="#FFE58A"/><stop offset=".55" stop-color="#FFD24D"/><stop offset="1" stop-color="#C98F00"/></linearGradient><mask id="h"><rect width="140" height="140" fill="#fff"/><circle cx="60" cy="72" r="15" fill="#000"/></mask><linearGradient id="bg" x1="0" y1="0" x2="0" y2="1"><stop offset="0" stop-color="#fcd34d"/><stop offset="1" stop-color="#f59e0b"/></linearGradient></defs>
+<rect x="1" y=".5" width="252" height="59" rx="12" fill="#ffffff" stroke="#d4d4d8" stroke-width="1"/>
+<circle cx="38" cy="30" r="14" fill="#000"/>
+<g transform="translate(38 30) scale(.2) translate(-60 -58)"><g fill="url(#g)" mask="url(#h)"><polygon points="45,12 45,76 27,76 27,30"/><circle cx="60" cy="72" r="33"/></g></g>
+<text x="64" y="28" font-family="Inter, ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif" font-size="16" font-weight="700" fill="#09090b">Sign in with bWalletX</text>
+<text x="64" y="42" font-family="Inter, ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif" font-size="11" font-weight="500" fill="#52525b">also works with bWallet</text>
+</svg>

package/assets/snippet.html

@@ -0,0 +1,17 @@
+<!-- "Sign in with bWalletX" without JavaScript or a build step. Gold, large. Wire the click yourself. -->
+<style>
+.bwx-btn{all:unset;box-sizing:border-box;display:inline-flex;align-items:center;gap:12px;padding:16px 20px;border-radius:12px;cursor:pointer;
+ background:linear-gradient(180deg,#fcd34d,#f59e0b);color:#000;font:700 16px/1.2 Inter,ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;
+ box-shadow:0 10px 15px -3px rgba(245,158,11,.2),0 4px 6px -4px rgba(245,158,11,.2)}
+.bwx-btn:hover{background:linear-gradient(180deg,#fde68a,#fbbf24)}
+.bwx-btn:active{background:linear-gradient(180deg,#fbbf24,#d97706)}
+.bwx-btn:focus-visible{outline:2px solid #b45309;outline-offset:3px}
+.bwx-btn:disabled{opacity:.6;cursor:not-allowed}
+.bwx-btn .bwx-mark{display:inline-flex;align-items:center;justify-content:center;width:28px;height:28px;border-radius:50%;background:#000;flex:none}
+.bwx-btn .bwx-txt{display:flex;flex-direction:column;align-items:flex-start}
+.bwx-btn small{font-size:11px;font-weight:500;color:rgba(0,0,0,.65)}
+</style>
+<button type="button" class="bwx-btn" aria-label="Sign in with bWalletX, also works with bWallet">
+  <span class="bwx-mark"><svg viewBox="23 8 74 100" width="15" height="20" aria-hidden="true"><defs><linearGradient id="bwxg" gradientUnits="userSpaceOnUse" x1="0" y1="12" x2="0" y2="105"><stop offset="0" stop-color="#FFE58A"/><stop offset=".55" stop-color="#FFD24D"/><stop offset="1" stop-color="#C98F00"/></linearGradient><mask id="bwxh"><rect width="140" height="140" fill="#fff"/><circle cx="60" cy="72" r="15" fill="#000"/></mask></defs><g fill="url(#bwxg)" mask="url(#bwxh)"><polygon points="45,12 45,76 27,76 27,30"/><circle cx="60" cy="72" r="33"/></g></svg></span>
+  <span class="bwx-txt">Sign in with bWalletX<small>also works with bWallet</small></span>
+</button>