docs: code comments name the headings README has now (closes #724)

The README rewrite renamed or merged several headings that comments still
cited. Each comment now names the current heading.

The comment on withLock() drops its reference, because no README section states
its Firefox private window exception.

Two comments also take corrections from reviews: the cases with no total in
DeleteAddress's warning, and the screens that say a swap's amount could not be
decoded.

Comments under tests/ are not changed.

Model: opus-5-5

.gitea/workflows/e2e.yml

@@ -23,8 +23,9 @@ on: [push]
 # Gitea branch protection, which this repo does not configure, so a failure
 # here is a red mark a reviewer has to account for rather than a hard
 # block. Making e2e-chrome a required check is blocked while reports of the
-# Chrome suite failing under load are still open. A gate that fails at random
+# Chrome suite failing under load are still open; the "In CI" section of
-# teaches people to merge past red.
+# README.md names them. A gate that fails at random teaches people to merge
+# past red.
 #
 # Nothing here may pass vacuously. There is no continue-on-error and no
 # `|| true`. Both scripts exit non-zero when docker is missing, when the
@@ -35,7 +36,8 @@ jobs:
     e2e-chrome:
         runs-on: ubuntu-latest
         # Bounds the image build, a cold cache included, and the three Chrome
-        # programs, so a hung browser frees the shared runner.
+        # programs, so a hung browser frees the shared runner. README.md
+        # "In CI" has the measured times.
         timeout-minutes: 40
         steps:
             # actions/checkout v4.2.2, 2026-02-22
@@ -45,7 +47,8 @@ jobs:
     e2e-firefox:
         runs-on: ubuntu-latest
         # Bounds the image build, a cold cache included, and both Firefox
-        # programs, so a hung browser frees the shared runner.
+        # programs, so a hung browser frees the shared runner. README.md
+        # "In CI" has the measured times.
         timeout-minutes: 15
         steps:
             # actions/checkout v4.2.2, 2026-02-22

README.md

@@ -89,13 +89,9 @@ Load it:
     2. Turn on "Developer mode".
     3. Click "Load unpacked".
     4. Pick `dist/chrome/`.
-- Firefox:
+- Firefox: open `about:debugging#/runtime/this-firefox`, click "Load Temporary
-    1. Open `about:debugging#/runtime/this-firefox`.
+  Add-on" and pick `dist/firefox/manifest.json`. A temporary add-on is unloaded
-    2. Click "Load Temporary Add-on".
+  when Firefox exits. Read Installing on Firefox below before relying on it.
-    3. Pick `dist/firefox/manifest.json`.
-
-A temporary add-on is unloaded when Firefox exits. Read Installing on Firefox
-below before relying on it.
 
 The user guide, [`docs/README.md`](docs/README.md), explains how to use the
 wallet. The release procedure is in [`docs/RELEASE.md`](docs/RELEASE.md).
@@ -379,18 +375,12 @@ Three rules follow from the worker being stopped:
   worker stopping. Such a connection ends when the browser closes, when the
   active address changes, or when the site is removed in Settings.
 
-These things live only in the worker's memory and are lost when it stops:
+Two things live only in the worker's memory and are lost when it stops: pending
-
+approvals and the record of broadcast nonces. An approval, and the site's
-- pending approvals;
+request waiting on it, exist nowhere else. So while any approval is pending, the
-- the record of broadcast nonces;
+worker calls `runtime.getPlatformInfo()` every 20 seconds. Chrome counts that
-- the timer that keeps the worker running while an approval is pending;
+call as activity and keeps the worker running. The timer stops itself once
-- the record of the one open transaction approval;
+nothing is pending.
-- the job that sets up the alarms at every start, while it runs.
-
-An approval, and the site's request waiting on it, exist nowhere else. So while
-any approval is pending, the worker calls `runtime.getPlatformInfo()` every 20
-seconds. Chrome counts that call as activity and keeps the worker running. The
-timer stops itself once nothing is pending.
 
 Alarms the code no longer handles are listed in `OBSOLETE_ALARMS` and cleared on
 every start. The worker fetches nothing when it starts.
@@ -913,8 +903,7 @@ not change. A flash message refuses:
 
 - a token already tracked;
 - an address on the scam list;
-- a contract that fails the lookup;
+- a contract that fails the lookup.
-- a token that fakes a known symbol.
 
 A network switch before the lookup answers adds nothing, and a flash message
 says so.
@@ -1235,12 +1224,8 @@ holds for a new address, and for every address after a network switch. While it
 is `null`:
 
 - the balance lists show "quantity unknown";
-- Home's ETH balance reads `unknown (ETH)` on mainnet and `unknown (SepoliaETH)`
+- Home's ETH balance reads `unknown (ETH)`;
-  on Sepolia;
+- Send reads `Current balance: unknown (ETH)`, and "Max" fills in nothing;
-- with ETH selected, Send reads `Current balance: unknown (ETH)` on mainnet and
-  `Current balance: unknown (SepoliaETH)` on Sepolia;
-- with ETH selected, "Max" fills in nothing and shows the flash message "This
-  token's balance is unknown.";
 - "Send" is not refused for a zero balance;
 - the address has no total;
 - DeleteAddress shows its warning.
@@ -1740,9 +1725,7 @@ The `Makefile` targets are thin shims over `script/`:
 
 - `script/bootstrap`: install the dependencies. Node and yarn come from the
   system when present. Otherwise node comes from a pinned nvm install and yarn
-  from corepack. When corepack and nvm are both missing, yarn comes from
+  from corepack. Fails when node cannot find a package named in `package.json`.
-  `npm install -g`. Fails when node cannot find a package named in
-  `package.json`.
 - `script/setup`: `script/bootstrap`, then the git pre-commit hook.
 - `script/test`: build the `test` stage of the `Dockerfile` with `--no-cache`.
   The stage runs the jest suite, stopped at 90 seconds and rerun verbose on

docs/README.md

@@ -60,8 +60,7 @@ settings.
 - "Check recipients on Etherscan". Etherscan is a block explorer website. With
   the setting on, the wallet fetches the recipient's Etherscan page each time
   you review a send. The wallet warns when Etherscan labels the address as
-  phishing, scam, exploiter or wallet drainer. A wallet drainer is a contract
+  phishing, scam, exploiter or wallet drainer. Only the recipient's address is
-  that empties a wallet once given permission. Only the recipient's address is
   sent. The Etherscan server cannot be changed.
 
 Each time a site's request opens a window, the wallet checks the site against a
@@ -212,18 +211,10 @@ allowed or denied for it.
 
 Getting the address back is not easy. "+" computes only addresses that this
 wallet has never listed. The removed address was listed once, so "+" skips it.
-The way back is to delete the whole wallet and import its backup again. The
+The way back is to delete the whole wallet and import its backup again. After
-import lists the wallet's first address, then scans for used addresses. An
+the import, the scan lists the address again if it holds ETH or has sent a
-address is used when it holds ETH or has sent a transaction. A read that fails
+transaction. Otherwise "+" may reach it again, because the new wallet has never
-during the scan counts the address as unused. The scan stops after five unused
+listed it.
-addresses in a row. When the scan finds two or more used addresses, the wallet
-lists those instead. The wallet does not list the removed address when:
-
-- the scan finds two or more used addresses, and the address is not among them;
-- the scan finds fewer than two, and the address is not the first.
-
-When the wallet does not list the address, "+" may reach it again, because the
-new wallet has never listed it.
 
 ### Deleting a wallet
 
@@ -254,11 +245,9 @@ else is treated as spam and hidden. Turning "Use Blockscout" off removes every
 untracked token from the lists at once.
 
 The balance list and the send screen hide a token that carries a well-known
-symbol but comes from another contract. `ETH` and `SepoliaETH` are well-known
+symbol, `ETH` included, but comes from another contract. A token that fakes a
-symbols on every network. The symbols of the built-in list are well-known on
+known symbol cannot be tracked ("Not added: this token fakes a known symbol."),
-Ethereum Mainnet only. A token that fakes a known symbol cannot be tracked ("Not
+and is never listed at zero. See Scam protection.
-added: this token fakes a known symbol."), and is never listed at zero. See Scam
-protection.
 
 ### Tracking a token
 
@@ -274,9 +263,8 @@ From Settings, under Tracked Tokens, click "+ Add token". That screen offers the
 top 10 tokens as buttons, the top 100 in a dropdown, and a contract address
 field. The two lists are offered on Ethereum Mainnet only.
 
-While "Show tracked tokens with zero balance" is on, a line for the new token
+A line for the new token reads `quantity unknown` until a refresh has read its
-reads `quantity unknown` until a refresh has read its balance. With that setting
+balance.
-off, the token has no line until a refresh has read its balance.
 
 A token is tracked on the network that it was added on. Settings lists the
 tracked tokens of the active network, each with an `[x]` button that stops
@@ -286,8 +274,7 @@ The wallet refuses to track:
 
 - a token that is already tracked;
 - an address on its scam list;
-- a contract that does not answer as an ERC-20 token;
+- a contract that does not answer as an ERC-20 token.
-- a token that fakes a known symbol.
 
 ### The token screen
 
@@ -615,11 +602,11 @@ Blockscout reports no holder count for a token, the history and the send screen
 still show it. While "Use Blockscout" is off, no holder count is known.
 
 Fraud contracts. When the wallet detects a fake token transfer, it adds the
-token's contract to a list. A network switch empties the list. While "Hide
+token's contract to a list that it keeps. While "Hide transactions from detected
-transactions from detected fraud contracts" is on, the history hides transfers
+fraud contracts" is on, the history hides transfers from the contracts on that
-from the contracts on that list. The send screen never offers those tokens.
+list. The send screen never offers those tokens. Turning "Hide fake tokens
-Turning "Hide fake tokens impersonating a known symbol" off also stops new
+impersonating a known symbol" off also stops new contracts being added to the
-contracts being added to the list.
+list.
 
 Dust transactions. Scammers send tiny amounts of ETH from an address that
 resembles one you have dealt with, so that the similar address lands in your
@@ -629,10 +616,11 @@ threshold starts at 100,000 gwei, which is 0.0001 ETH. A threshold of 0 hides
 nothing.
 
 Known scam addresses. The wallet ships a list of addresses known for fraud,
-including phishing addresses and wallet drainers. Sending to a listed address
+including phishing addresses and wallet drainers. A wallet drainer is a contract
-raises a warning on the confirmation screen, and a listed address cannot be
+that empties a wallet once given permission. Sending to a listed address raises
-tracked as a token. The list holds only addresses involved in fraud; it is not a
+a warning on the confirmation screen, and a listed address cannot be tracked as
-sanctions list.
+a token. The list holds only addresses involved in fraud; it is not a sanctions
+list.
 
 Addresses and hashes are shown in full, because address poisoning relies on
 shortened ones. The only shortened address is the label of a token with no known

script/test-e2e-firefox

@@ -60,12 +60,12 @@ main() {
 
     echo "Running the Firefox e2e suite..."
     # --shm-size=1g: Firefox needs more than the default 64MB /dev/shm.
-    # --network none: the container has no network, and the suite reaches
+    # --network none: the suite stubs nothing, so this is what keeps the
-    #   only the test page and stub node on loopback (README.md, Browser
+    #   run offline and deterministic. The extension swallows its own
-    #   tests). The extension swallows its own fetch failures, so the popup
+    #   fetch failures, so the popup flows work unchanged; see the
-    #   flows work unchanged. Weaker than the Chrome suite's fixture
+    #   Browser tests section of README.md. Weaker than the Chrome suite's
-    #   interception, and honestly so — it proves no request escaped, but it
+    #   fixture interception, and honestly so — it proves no request
-    #   cannot report which ones were attempted.
+    #   escaped, but it cannot report which ones were attempted.
     # HOME=/tmp: the image's root home is not a reliable place for the
     #   browser profile.
     #

src/shared/browserApi.js

@@ -240,9 +240,10 @@ function onStorageChanged(listener) {
 /**
  * Run `fn` while holding the browser's lock called `name`
  * (`navigator.locks`), and settle as `fn` settles. Every page of the extension
- * and its background share these locks, so while one of them holds `name`
+ * and its background share these locks, except a page in a Firefox private
- * another asking for it waits, in the order they asked. The lock is let go when
+ * window, so while one of them holds `name` another asking for it waits, in
- * `fn` settles, whether it resolved or rejected.
+ * the order they asked. The lock is let go when `fn` settles, whether it
+ * resolved or rejected.
  *
  * Every write of the stored record holds the lock named after its key,
  * "autistmask", from its read to its write: saveState() in

tests/approvalDisplayFloor.test.js

@@ -1,11 +1,11 @@
 // The floor of the approval screen's amount line.
 //
 // Amounts are truncated to four decimal places for scannability (README.md,
-// Amounts). With the token's true scale resolved, that truncation can still
+// Display Consistency). With the token's true scale resolved, that truncation
-// take a real amount below the floor and print it as `0.0000`: one base unit of
+// can still take a real amount below the floor and print it as `0.0000`: one
-// an 18-decimal token, or a few hundred of an 8-decimal one. On the one screen
+// base unit of an 18-decimal token, or a few hundred of an 8-decimal one. On
-// whose job is to state what is being authorized, a nonzero transfer or
+// the one screen whose job is to state what is being authorized, a nonzero
-// allowance then reads as nothing.
+// transfer or allowance then reads as nothing.
 //
 // The invariant asserted here is narrow: a nonzero amount never renders as
 // zero. The four-decimal rule itself is unchanged, and the string the

tests/dustThreshold.test.js

@@ -74,7 +74,7 @@ describe("parsing the dust threshold", () => {
 });
 
 describe("the rejection message", () => {
-    // README, Wording: error messages are full sentences.
+    // README, Language & Labeling: error messages are full sentences.
     test("is a full sentence naming the constraint", () => {
         expect(DUST_THRESHOLD_MESSAGE).toMatch(/^[A-Z].*\.$/);
         expect(DUST_THRESHOLD_MESSAGE).toContain("whole number of gwei");
@@ -95,9 +95,9 @@ describe("the flash line the message is shown in", () => {
     // NOT and CANNOT assert that the message fits inside it: jest runs on
     // the node environment here, with no layout engine, so every rendered
     // height is zero. An earlier version of this block claimed to pin the
-    // reserved space rule in README, Appearance, with this regex, and it
+    // No Layout Shift policy with this regex, and it passed at any message
-    // passed at any message length, including one that wrapped to two lines
+    // length, including one that wrapped to two lines and pushed the
-    // and pushed the settings view down 12px.
+    // settings view down 12px.
     //
     // The line cuts a message too long for it with an ellipsis (see
     // showFlash() in src/popup/views/helpers.js). The assertions that

tests/e2e/run.js

@@ -1280,7 +1280,7 @@ test("the correct password reveals the full phrase, and nothing logs it (#161)",
         );
         assert(!promptShown, "the password prompt is still shown after unlock");
 
-        // README, ShowRecoveryPhrase: shown whole, and copyable.
+        // Full Identifiers Policy: shown whole, and copyable.
         const title = await env.page.getAttribute(
             "#show-phrase-value",
             "title",
@@ -2255,7 +2255,7 @@ async function waitForFilledFlashLine(page) {
     }
 }
 
-// README, Appearance: the rejection message goes into #flash-msg,
+// README, No Layout Shift: the rejection message goes into #flash-msg,
 // whose min-h-[1.25rem] reserves exactly ONE line at text-xs, and which
 // cuts a message too long for that line with an ellipsis rather than wrap
 // it. This shows the real message and measures that nothing moves; the
@@ -2603,7 +2603,7 @@ function toHexWei(wei) {
 }
 
 // A fee in wei as the confirmation screen writes it: truncated to four decimal
-// places (README.md, Amounts). Deliberately a second
+// places (README.md, Display Consistency). Deliberately a second
 // implementation rather than an import of src/shared/amountDisplay.js:
 // asserting against an independent rendering is stronger than asserting a
 // function equals itself. The fixture's fees are above 0.0001 ETH, so the
@@ -3298,7 +3298,7 @@ async function goToTokenConfirm(env) {
         amount: TOKEN_AMOUNT,
     });
     await waitForEstimate(env.page);
-    // TOKEN_AMOUNT to four decimal places (README.md, Amounts).
+    // TOKEN_AMOUNT to four decimal places (README.md, Display Consistency).
     const shown = await shownAmount(env.page);
     assert(
         shown === "0.2500 " + STUB_TOKEN.symbol,
@@ -3453,7 +3453,7 @@ test("a token that lies about decimals() at signing time broadcasts nothing (#30
 
 // ------------------------- a send Sign & Send refuses moves nothing (#583)
 //
-// README, Appearance. Sign & Send refuses a send on the confirmation
+// README, No Layout Shift. Sign & Send refuses a send on the confirmation
 // screen when the active network changed since review and when its gas limit
 // or fee is over its bound, and each refusal's sentence sits in a box that held
 // its space from the first paint. This drives the total fee refusal, the longer

tests/manifest.test.js

@@ -165,9 +165,9 @@ describe("declared icons", () => {
     });
 });
 
-// README, Installing on Firefox: the extension does not run in private windows.
 // Firefox gives a page in a private window locks of its own, so that page's
-// save could land between the background's read and its write.
+// save could land between the background's read and its write (README,
+// "Stored state and its version").
 describe("private windows", () => {
     test("a page in a firefox private window cannot read or write extension storage", () => {
         expect(readManifest("firefox").incognito).toBe("not_allowed");

tests/support/navigatorLocks.js

@@ -5,7 +5,7 @@
 // browser's own does for the one call the extension makes,
 // `navigator.locks.request(name, callback)`. Every module a test file loads
 // shares it, as the extension's background and its pages share the browser's
-// (README, "Stored data").
+// (README, "Stored state and its version").
 //
 // Run before each test file by `setupFiles` in package.json.
 

tests/timestampDisplay.test.js

@@ -1,7 +1,7 @@
 // A transaction's time is written by isoDate() and timeAgo() in
-// src/popup/views/helpers.js on every screen that shows one (README, Amounts;
+// src/popup/views/helpers.js on every screen that shows one (README, Display
-// https://git.eeqj.de/sneak/AutistMask/issues/168). AddressDetail and
+// Consistency; https://git.eeqj.de/sneak/AutistMask/issues/168). AddressDetail
-// AddressToken used to define their own copies, so a fix to the shared pair
+// and AddressToken used to define their own copies, so a fix to the shared pair
 // would not have reached them.
 //
 // The pair is replaced before the views are loaded, because a view takes it