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

script/lib/package.js

@@ -1,7 +1,7 @@
 // Turn a verified dist/ into the two distributable archives.
 //
 // Invoked by script/package, which runs `make build` first so that dist/ has
-// already been checked against the build's own receipt (see the Build Receipts
+// already been checked against the build's own receipt (see the Builds
 // section of README.md). This program does not build anything and does not
 // write into dist/: it reads the emitted tree and writes release/.
 //

script/test-e2e-firefox

@@ -63,7 +63,7 @@ main() {
     # --network none: the suite stubs nothing, so this is what keeps the
     #   run offline and deterministic. The extension swallows its own
     #   fetch failures, so the popup flows work unchanged; see the
-    #   network note in README.md. Weaker than the Chrome suite's
+    #   Browser tests section of README.md. Weaker than the Chrome suite's
     #   fixture interception, and honestly so — it proves no request
     #   escaped, but it cannot report which ones were attempted.
     # HOME=/tmp: the image's root home is not a reliable place for the

src/background/state.js

@@ -18,11 +18,11 @@
 //   updateState(fn)   read fresh, apply fn to that fresh record, write it
 //                     back — all holding the lock every write of the stored
 //                     record takes, so no other write lands in between, by
-//                     the background or by any page (README, "Stored state
-//                     and its version"). The read is one storage round trip
-//                     ahead of the write rather than a page lifetime ahead of
-//                     it (which is what made the popup's saveState() need a
-//                     per-field merge against a baseline at all).
+//                     the background or by any page (README, "Stored data").
+//                     The read is one storage round trip ahead of the write
+//                     rather than a page lifetime ahead of it (which is what
+//                     made the popup's saveState() need a per-field merge
+//                     against a baseline at all).
 //
 // A handler that must both read and write therefore does its network work
 // against a snapshot it owns, and applies the RESULT inside updateState().
@@ -72,7 +72,7 @@ async function updateStateOnce(mutate) {
 // src/shared/browserApi.js) is held from the read to the write: two
 // background turns, or a turn and a page's save, never interleave
 // (https://git.eeqj.de/sneak/AutistMask/issues/641). Every page's save waits
-// while it is held (README, "Stored state and its version").
+// while it is held (README, "Stored data").
 //
 // `mutate` must also not call updateState() itself, directly or through
 // anything it awaits: the inner turn waits for the lock the outer one holds,

src/popup/views/approval.js

@@ -319,12 +319,12 @@ function showTxApproval(details) {
             );
         }
         // A swap the decoder read no amount for, such as one whose V4 swap
-        // action could not be read or a V4 exact-out swap. The wait and error
-        // screens say the amount could not be decoded, with no currency after
-        // it, rather than show the transaction's ETH value as the amount. A
-        // swap paid in native ETH keeps that value: it is the ETH the swap
-        // pays (for an exact-out swap, the most it pays), not a figure that
-        // had to be read from the calldata.
+        // action could not be read or a V4 exact-out swap. The wait, success
+        // and error screens say the amount could not be decoded, with no
+        // currency after it, rather than show the transaction's ETH value as
+        // the amount. A swap paid in native ETH keeps that value: it is the
+        // ETH the swap pays (for an exact-out swap, the most it pays), not a
+        // figure that had to be read from the calldata.
         const tokenIn = decoded.details.find((d) => d.label === "Token In");
         if (
             tokenIn &&

src/popup/views/deleteAddress.js

@@ -83,10 +83,11 @@ function recoveryPathText(wallet) {
 // rounded number would report "0.0000 ETH" for an address holding real money.
 // The lines below it carry the amounts, in the same format as Home and
 // AddressDetail, followed by the USD total when there is one to give — no
-// total line at all on testnet or before the first price fetch, and no figure
-// when every holding here is one with no price, since "$0.00" directly under
-// "This address holds a balance." is a contradiction. A token holding below
-// 0.000001 does not count, as the lines below leave it out.
+// total line at all on testnet, before the first price fetch or while no
+// refresh has read the ETH balance, and no figure when every holding here is
+// one with no price, since "$0.00" directly under "This address holds a
+// balance." is a contradiction. A token holding below 0.000001 does not count,
+// as the lines below leave it out.
 //
 // While no refresh has read the ETH balance the address may be empty, so the
 // sentence says "may hold".

src/popup/views/helpers.js

@@ -272,7 +272,7 @@ function clearFlash() {
 }
 
 // The flash line reserves exactly one line, and a message that wrapped would
-// push the screen below it down (README, No Layout Shift). So #flash-msg never
+// push the screen below it down (README, Appearance). So #flash-msg never
 // wraps: text too long for the line is cut with an ellipsis, and the whole
 // message is also put in the line's title. Write messages to fit, at most 50
 // characters, so none is cut.
@@ -528,9 +528,9 @@ const ADDRESS_MIN_DISPLAY_LEN = 32;
 
 // Truncate the middle of a string, replacing removed characters with "…".
 // Safety: refuses to truncate more than 10 characters, which is the maximum
-// that still prevents address spoofing attacks (see Display Consistency in
-// README).  Callers that need to display less should use a different UI
-// approach rather than silently making addresses insecure.
+// that still prevents address spoofing attacks (see Addresses in README).
+// Callers that need to display less should use a different UI approach rather
+// than silently making addresses insecure.
 function truncateMiddle(str, maxLen) {
     if (str.length <= maxLen) return str;
     const removed = str.length - maxLen + 1; // +1 for the ellipsis char
@@ -633,9 +633,9 @@ function formatAddressHtml(address, ensName, maxLen, title) {
     return renderAddressHtml(address, { title, ensName, maxLen });
 }
 
-// A transaction's time as every screen shows it (README, Display
-// Consistency): the ISO datetime, in UTC when the UTC Timestamps setting is
-// on, and the relative age. Views import these two; they keep no copies.
+// A transaction's time as every screen shows it (README, Amounts): the ISO
+// datetime, in UTC when the UTC Timestamps setting is on, and the relative age.
+// Views import these two; they keep no copies.
 function isoDate(timestamp) {
     const d = new Date(timestamp * 1000);
     const pad = (n) => String(n).padStart(2, "0");

src/popup/views/settings.js

@@ -265,7 +265,7 @@ async function renderSiteLists() {
 // A network switch, made by the user here or saved by the background once the
 // user approved a site's request (src/popup/index.js), leaves every screen on
 // the page showing the previous network. Two functions leave the page as
-// README's Screen Map describes:
+// README's Navigation section describes:
 //
 // - cutViewStack(), before the switch is saved, so that save keeps the cut for
 //   a popup closed straight after

src/shared/amountDisplay.js

@@ -1,4 +1,4 @@
-// The 4-decimal amount rule from README.md's Display Consistency section, and
+// The 4-decimal amount rule from README.md's Amounts section, and
 // the one exception to it, in one place. Three call sites had grown their own
 // copy of the truncation — the history and balance lists
 // (`src/shared/transactions.js`), the approval screen's ERC-20 amount line

src/shared/browserApi.js

@@ -241,9 +241,9 @@ 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, except a page in a Firefox private
- * window (README, "Stored state and its version"), so while one of them holds
- * `name` another asking for it waits, in the order they asked. The lock is let
- * go when `fn` settles, whether it resolved or rejected.
+ * window, so while one of them holds `name` another asking for it waits, in
+ * 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
@@ -266,8 +266,8 @@ function withLock(name, fn) {
 
 // `storage.session`, the browser's session storage: what is kept there lasts
 // until the browser closes. It survives the background worker being stopped
-// and started again, which module-level variables do not (README, Background
-// scheduling). The background keeps the connections allowed without
+// and started again, which module-level variables do not (README, The
+// background worker). The background keeps the connections allowed without
 // "Remember" there; see src/background/index.js. Firefox has it from version
 // 115, the minimum manifest/firefox.json declares.
 //