docs: special URLs + branching (Fixes #212, #208)

docs/BRANCHING.md

@@ -0,0 +1,57 @@
+# Git Branching & Release Flow
+
+This document proposes a branch model for [burner-wallet](https://github.com/austintgriffith/burner-wallet) to reduce instability on `master` while keeping fast iteration. It complements continuous deployment (see issue #203) once hosting access is configured.
+
+## Branches
+
+| Branch | Purpose | Deploy target (proposed) |
+|--------|---------|---------------------------|
+| `master` | Stable integration branch; only tested merges | Staging (e.g. `test.xdai.io`) |
+| `rim` | Active feature development (Rimble UI, xDAI theme) | Preview / dev |
+| `production` | Release branch tagged for mainnet xDAI deployment | Production (`xdai.io`) |
+| `develop` | Optional integration branch for larger efforts | None (CI only) |
+
+Feature branches should be short-lived: `feature/<issue>-<short-description>` or `fix/<issue>-<short-description>`.
+
+## Workflow for contributors
+
+1. **Fork** the repo and clone locally.
+2. **Branch** from `rim` (or `master` if fixing production-only bugs) — e.g. `git checkout -b fix/issue-200-qr-no-reload rim`.
+3. **Implement** with focused commits; reference the bounty issue in the PR body (`Fixes #200`).
+4. **Open a PR** against `rim` (or `master` as directed by maintainers).
+5. **Review** — bounty reviewers verify scope per the issue; gardener merges when approved.
+6. **Merge upstream** — `rim` → `master` on a schedule or after a release checklist; `master` → `production` for production deploys only.
+
+## Merge policy
+
+- **Into `rim`**: Bounty PRs, UI migrations, non-breaking fixes. CI must pass.
+- **Into `master`**: After QA on staging; no known regressions on send/receive/exchange.
+- **Into `production`**: Maintainer-only; requires @austintgriffith or delegated deploy access.
+
+## Protecting `master`
+
+- Require PR reviews (at least one maintainer or bounty reviewer).
+- Require CI (tests + lint + dependency pin check) — see `.github/workflows/ci.yml`.
+- No direct pushes to `production`.
+
+## New developer checklist
+
+```bash
+git clone https://github.com/<your-fork>/burner-wallet.git
+cd burner-wallet
+git remote add upstream https://github.com/austintgriffith/burner-wallet.git
+git fetch upstream
+git checkout -b my-fix upstream/rim
+npm install --legacy-peer-deps
+npm start
+```
+
+## Relation to other bounties
+
+- **#212** — URL behavior documented in `docs/SPECIAL_URLS.md`
+- **#203** — CD pipelines should trigger on `master` (staging) and `production` (xdai.io)
+- **#228** — CI runs on all PRs via GitHub Actions
+
+## Maintainer notes
+
+Branch names and deploy URLs should be confirmed with @austintgriffith before changing production DNS or Firebase/hosting config. This document can be moved to the [project wiki](https://github.com/austintgriffith/burner-wallet/wiki) if preferred.

docs/SPECIAL_URLS.md

@@ -0,0 +1,58 @@
+# Burner Wallet — Special URL Schemes
+
+This document describes the URL patterns that Burner Wallet recognizes on load and when scanning QR codes. Implementation lives primarily in `src/App.js` (`applyPathFromUrl`, `parseAndCleanPath`) and `src/components/SendByScan.js`.
+
+## Base URL
+
+The wallet is typically served at `https://xdai.io/` (or domain-specific variants such as `buffidai.io`, `burnerwallet.io`). Paths below are relative to the site root.
+
+## Private key import
+
+| Pattern | Example | Behavior |
+|---------|---------|----------|
+| Raw hex in path | `/{64-or-66-char-hex}` | Imports a private key (with or without `0x` prefix). Path length 65–67 characters, no semicolons. |
+| Raw hex in hash | `/#{64-or-66-char-hex}` | Same as above when the key is in the URL fragment. |
+| Base64 `/pk` route | `/pk#{base64url-encoded-private-key}` | Decodes base64url payload from the hash into a private key. |
+
+After processing, the URL is normalized to `/` via `history.pushState` (no full page reload when scanned from the in-app QR reader).
+
+## Send to address
+
+| Pattern | Example | Behavior |
+|---------|---------|----------|
+| Address only | `/{42-char-ethereum-address}` | Opens **Send to Address** with recipient prefilled (path length 43 including leading `/`). |
+| Address + amount + message | `/{address};{amount};{message}` | Opens **Send to Address** with parsed fields. Optional 4th segment `;{extraMessage}`. |
+| Address + amount (no message) | `/{address};{amount}` | Opens send flow when amount > 0 and address is 42 characters. |
+
+Semicolon-separated segments are parsed by `parseAndCleanPath`. Message segments are URI-decoded with replacements for `%23`, `%3B`, `%3A`, `%2F`.
+
+## Claim links
+
+| Pattern | Example | Behavior |
+|---------|---------|----------|
+| Claim ID + key | `/{claimId};{claimKey}` | Path length 134 characters. Sets `claimId` and `claimKey` in app state and opens the claimer flow. |
+
+## Vendors
+
+| Pattern | Example | Behavior |
+|---------|---------|----------|
+| Vendor list | `/vendors;` | Opens the **Vendors** view. |
+
+## Deep links (QR scan)
+
+The scanner in `SendByScan.js` strips protocol prefixes (`ethereum:`, `https://...`) and uses the path portion. Status.im payment links (`get.status.im`) are handled separately and return structured payment data to the calling view.
+
+## Ethereum URI scheme
+
+QR codes may encode `ethereum:{address}` or `ethereum:{address}@{chainId}`. The scanner extracts the segment after the last `:` or `/` before applying the patterns above.
+
+## Related code
+
+- `src/App.js` — `applyPathFromUrl`, `applyPathFromScan`, `componentDidMount` initial routing
+- `src/components/SendToAddress.js` — reads `window.location.pathname` on mount (legacy); prefers `scannerState` from parent when set after scan
+- `src/components/SendByScan.js` — QR handler; delegates to `applyPathFromScan` instead of `window.location` reload (see issue #200)
+
+## Security notes
+
+- Private keys in URLs may appear in browser history and server logs if shared as links. Prefer in-app QR scan or encrypted claim links when possible.
+- Always use HTTPS in production.