docs: README Screen Map omits three shipped screens and misdescribes four flows #164

New Issue

clawbot · 2026-08-09T03:46:51+02:00

clawbot commented

2026-08-09 03:46:51 +02:00

Problem

README.md declares itself "the complete authoritative technical
documentation" (README.md:906-907). Its Screen Map (README.md:263-571) has
drifted from the code in both directions.

Screens that exist and are reachable but are absent from the Screen Map:

DeleteWallet — src/popup/views/deleteWallet.js, view id
delete-wallet-confirm (helpers.js:27), markup index.html:1066.
Reachable from Settings via the per-wallet [x].
ExportPrivKey — view id export-privkey (helpers.js:33), markup
index.html:352-405, logic in addressDetail.js:297-374. Reachable from the
AddressDetail "more" dropdown. This one discloses secret material and
belongs in the documentation more than any other screen.
SettingsAddToken — src/popup/views/settingsAddToken.js, view id
settings-addtoken (helpers.js:28), markup index.html:1102. Reachable
via settings.js:322-325.

Flows the Screen Map describes incorrectly:

ImportKey (README.md:318-330) is documented as its own screen with its
own heading and a "Back to AddWallet" transition, reached from a "Have a
private key instead?" link on AddWallet (README.md:312, :316). No such
screen and no such link exist. AddWallet has three tabs —
tab-mnemonic, tab-privkey, tab-xprv (index.html:63-84, wired at
addWallet.js:280-282).
The xprv import mode is undocumented entirely. addWallet.js:35 defines
MODES = ["mnemonic","privkey","xprv"] and addWallet.js:209-276 handles
it, creating a wallet with type: "xprv" (addWallet.js:242). The README
Data Model (README.md:243-253) describes only HD wallets and key wallets,
so this third type is missing from the data model too.
ConfirmTx password modal (README.md:402-403) — there is no modal. The
password is an inline field (index.html:646-661, confirmTx.js:291); the
module header comment at confirmTx.js:1-3 even says "inline password".
Approval popup mechanisms are swapped. README.md:524-525 says
SiteApproval is "Opened in a separate popup by the background script" and
README.md:537-538 says TxApproval is "Opened via the toolbar popup". The
code does the opposite: site approval prefers actionApi.openPopup() with a
windows.create fallback (background/index.js:143-157), while tx and sign
approvals always use windows.create (background/index.js:165-197, with
explanatory comments at :162-164 and :181-183).

Settings section is incomplete (README.md:506-517) — it omits the network
selector (settings.js:150-153, :263-272), the theme selector
(settings.js:280-285), the UTC timestamps checkbox (settings.js:314-318),
the tracked-token list with remove (settings.js:64-89), "+ Add token"
(settings.js:322-325), per-wallet rename and delete (settings.js:91-145),
and the About well with its debug easter egg (settings.js:158-178,
:339-382).

Stale TODO checkbox: README.md:884 "Gas estimation and fee display before
confirming" is unchecked, but it is fully implemented
(confirmTx.js:205-265, markup index.html:584-589) and matches the ConfirmTx
spec at README.md:397.

Scope

Documentation-only. Touch README.md and nothing else. Do not change code.
Do not touch docs/README.md — that is tracked separately.

Coordinate lightly: the "Delete wallet" TODO checkbox is ticked by #156, and
new screens introduced by #161 and #162 add their own Screen Map entries. If
those have already landed, do not duplicate their edits; if they have not,
leave those specific lines alone.

RULES.md must not be modified — it is owner-maintained and agent-read-only.

Definition of done

DeleteWallet, ExportPrivKey, and SettingsAddToken each have a Screen Map
entry in the established format (When / Elements / Transitions),
accurate to the code.
The ImportKey section is rewritten to describe the actual tabbed
AddWallet UI, including the xprv tab.
The xprv wallet type is added to the Data Model section
(README.md:243-253).
The ConfirmTx "password modal" wording is corrected to the inline
password field.
The SiteApproval and TxApproval popup-mechanism descriptions are swapped
to match background/index.js:143-197.
The Settings Screen Map entry lists every element Settings actually has.
The "Gas estimation and fee display before confirming" TODO checkbox is
ticked.
Every Screen Map entry has been checked against the code; the PR states
which were verified.
make fmt has been run and the result is in the commit.
TODO.md updated in the same commit.
make check passes.

## Problem `README.md` declares itself "the complete authoritative technical documentation" (`README.md:906-907`). Its Screen Map (`README.md:263-571`) has drifted from the code in both directions. **Screens that exist and are reachable but are absent from the Screen Map:** - **DeleteWallet** — `src/popup/views/deleteWallet.js`, view id `delete-wallet-confirm` (`helpers.js:27`), markup `index.html:1066`. Reachable from Settings via the per-wallet `[x]`. - **ExportPrivKey** — view id `export-privkey` (`helpers.js:33`), markup `index.html:352-405`, logic in `addressDetail.js:297-374`. Reachable from the AddressDetail "more" dropdown. **This one discloses secret material and belongs in the documentation more than any other screen.** - **SettingsAddToken** — `src/popup/views/settingsAddToken.js`, view id `settings-addtoken` (`helpers.js:28`), markup `index.html:1102`. Reachable via `settings.js:322-325`. **Flows the Screen Map describes incorrectly:** - **ImportKey** (`README.md:318-330`) is documented as its own screen with its own heading and a "Back to AddWallet" transition, reached from a "Have a private key instead?" link on AddWallet (`README.md:312`, `:316`). No such screen and no such link exist. AddWallet has three tabs — `tab-mnemonic`, `tab-privkey`, `tab-xprv` (`index.html:63-84`, wired at `addWallet.js:280-282`). - **The xprv import mode is undocumented entirely.** `addWallet.js:35` defines `MODES = ["mnemonic","privkey","xprv"]` and `addWallet.js:209-276` handles it, creating a wallet with `type: "xprv"` (`addWallet.js:242`). The README Data Model (`README.md:243-253`) describes only HD wallets and key wallets, so this third type is missing from the data model too. - **ConfirmTx password modal** (`README.md:402-403`) — there is no modal. The password is an inline field (`index.html:646-661`, `confirmTx.js:291`); the module header comment at `confirmTx.js:1-3` even says "inline password". - **Approval popup mechanisms are swapped.** `README.md:524-525` says SiteApproval is "Opened in a separate popup by the background script" and `README.md:537-538` says TxApproval is "Opened via the toolbar popup". The code does the opposite: site approval prefers `actionApi.openPopup()` with a `windows.create` fallback (`background/index.js:143-157`), while tx and sign approvals always use `windows.create` (`background/index.js:165-197`, with explanatory comments at `:162-164` and `:181-183`). **Settings section is incomplete** (`README.md:506-517`) — it omits the network selector (`settings.js:150-153`, `:263-272`), the theme selector (`settings.js:280-285`), the UTC timestamps checkbox (`settings.js:314-318`), the tracked-token list with remove (`settings.js:64-89`), "+ Add token" (`settings.js:322-325`), per-wallet rename and delete (`settings.js:91-145`), and the About well with its debug easter egg (`settings.js:158-178`, `:339-382`). **Stale TODO checkbox:** `README.md:884` "Gas estimation and fee display before confirming" is unchecked, but it is fully implemented (`confirmTx.js:205-265`, markup `index.html:584-589`) and matches the ConfirmTx spec at `README.md:397`. ## Scope **Documentation-only.** Touch `README.md` and nothing else. Do not change code. Do not touch `docs/README.md` — that is tracked separately. Coordinate lightly: the "Delete wallet" TODO checkbox is ticked by #156, and new screens introduced by #161 and #162 add their own Screen Map entries. If those have already landed, do not duplicate their edits; if they have not, leave those specific lines alone. `RULES.md` must not be modified — it is owner-maintained and agent-read-only. ## Definition of done - [ ] DeleteWallet, ExportPrivKey, and SettingsAddToken each have a Screen Map entry in the established format (When / Elements / Transitions), accurate to the code. - [ ] The ImportKey section is rewritten to describe the actual tabbed AddWallet UI, including the xprv tab. - [ ] The xprv wallet type is added to the Data Model section (`README.md:243-253`). - [ ] The ConfirmTx "password modal" wording is corrected to the inline password field. - [ ] The SiteApproval and TxApproval popup-mechanism descriptions are swapped to match `background/index.js:143-197`. - [ ] The Settings Screen Map entry lists every element Settings actually has. - [ ] The "Gas estimation and fee display before confirming" TODO checkbox is ticked. - [ ] Every Screen Map entry has been checked against the code; the PR states which were verified. - [ ] `make fmt` has been run and the result is in the commit. - [ ] `TODO.md` updated in the same commit. - [ ] `make check` passes.

clawbot added this to the 1.0.0 milestone 2026-08-09 03:46:51 +02:00

clawbot referenced this issue

2026-08-09 03:47:31 +02:00

decision: Sepolia support contradicts "Non-Goals for 1.0", and isMetaMask names a competitor in shipped code #165

clawbot referenced this issue from a commit

2026-08-11 14:23:09 +02:00

docs: rebuild the README Screen Map from the code (closes #164)

clawbot referenced a pull request that will close this issue

2026-08-11 14:23:34 +02:00

docs: rebuild the README Screen Map from the code (closes #164) #202

clawbot referenced this issue from a commit

2026-08-11 14:27:47 +02:00