fix: explain a rejected dust threshold instead of silently snapping back (closes #233)

The dust-threshold field was the only validated input in Settings that rejected
without saying anything: the value silently changed back to the stored one with
no explanation. It now flashes "Please enter a whole number of gwei, zero or
greater." alongside the existing resync, matching the idiom the RPC URL field
already uses.

The parse moves to its own module and accepts plain decimal digits only, zero
or greater. Hex and exponent notation are refused rather than accepted: Number()
reads "0x10" as 16 and "1e3" as 1000, neither of which the previous parseInt
produced, and storing a number the user did not type is the same silent
substitution this change exists to remove.

The message must fit one line of the reserved flash area -- a wrapped message
pushes the settings view down, which the No Layout Shift policy forbids. That is
pinned by an end-to-end test measuring the rendered line height and the position
of the elements below it, in a single round trip because the flash clears after
two seconds.

tests/dustThreshold.test.js

@@ -0,0 +1,243 @@
+// Tests for the dust threshold field in Settings (issue #233).
+//
+// Two halves: what the parse accepts, and what the settings view does with a
+// rejection. The view half runs against the real change handler with the DOM
+// helpers stubbed out, because the bug was not in the parse — it was that a
+// rejection said nothing.
+
+const {
+    DUST_THRESHOLD_MESSAGE,
+    parseDustThresholdGwei,
+} = require("../src/popup/dustThreshold");
+
+describe("parsing the dust threshold", () => {
+    test("accepts a whole number of gwei", () => {
+        expect(parseDustThresholdGwei("100000")).toBe(100000);
+        expect(parseDustThresholdGwei("1")).toBe(1);
+    });
+
+    // Zero is a real setting, not an empty field: it hides nothing.
+    test("accepts zero", () => {
+        expect(parseDustThresholdGwei("0")).toBe(0);
+    });
+
+    test("accepts surrounding whitespace", () => {
+        expect(parseDustThresholdGwei("  250  ")).toBe(250);
+    });
+
+    test("rejects an empty field", () => {
+        expect(parseDustThresholdGwei("")).toBe(null);
+        expect(parseDustThresholdGwei("   ")).toBe(null);
+    });
+
+    test("rejects a negative threshold", () => {
+        expect(parseDustThresholdGwei("-1")).toBe(null);
+    });
+
+    // parseInt used to read this as 1, which is not what was typed.
+    test("rejects a fractional value", () => {
+        expect(parseDustThresholdGwei("1.5")).toBe(null);
+        expect(parseDustThresholdGwei("1.0")).toBe(null);
+    });
+
+    // parseInt used to read this as 100. The unit is printed beside the
+    // field already.
+    test("rejects a value carrying its unit", () => {
+        expect(parseDustThresholdGwei("100 gwei")).toBe(null);
+    });
+
+    // Number() reads this as 16. Storing 16 for a field that was told to
+    // want a whole number of gwei would be the same silent substitution the
+    // message exists to end.
+    test("rejects hex notation", () => {
+        expect(parseDustThresholdGwei("0x10")).toBe(null);
+    });
+
+    // Number() reads this as 1000.
+    test("rejects exponent notation", () => {
+        expect(parseDustThresholdGwei("1e3")).toBe(null);
+    });
+
+    test("rejects other non-numeric input", () => {
+        expect(parseDustThresholdGwei("lots")).toBe(null);
+        expect(parseDustThresholdGwei("+5")).toBe(null);
+        expect(parseDustThresholdGwei("Infinity")).toBe(null);
+        expect(parseDustThresholdGwei(undefined)).toBe(null);
+        expect(parseDustThresholdGwei(5)).toBe(null);
+    });
+
+    // Beyond 2^53 the digits would round on the way in, so the stored
+    // threshold would not be the one typed.
+    test("rejects a value too large to hold exactly", () => {
+        expect(parseDustThresholdGwei("9007199254740993")).toBe(null);
+    });
+});
+
+describe("the rejection message", () => {
+    // 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");
+        expect(DUST_THRESHOLD_MESSAGE).toContain("zero or greater");
+    });
+});
+
+describe("the flash line the message is shown in", () => {
+    const fs = require("fs");
+    const path = require("path");
+
+    const POPUP_HTML = fs.readFileSync(
+        path.join(__dirname, "..", "src", "popup", "index.html"),
+        "utf8",
+    );
+
+    // This asserts only that the reservation exists in the markup. It does
+    // 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
+    // No Layout Shift policy with this regex, and it passed at any message
+    // length, including one that wrapped to two lines and pushed the
+    // settings view down 12px.
+    //
+    // The assertion that actually measures — empty line vs. the message,
+    // real Chromium, documented 360x600 popup — is
+    // "a rejected dust threshold shifts no layout (#233)" in
+    // tests/e2e/run.js, run by make test-e2e. It is not in make check
+    // because REPO_POLICIES.md caps make test at 20 seconds and a browser
+    // suite does not fit; run it before changing the wording.
+    test("reserves its height in the markup", () => {
+        const flashLine = POPUP_HTML.match(
+            /<div\s+id="flash-msg"\s+class="([^"]*)"/,
+        );
+        expect(flashLine).not.toBeNull();
+        expect(flashLine[1]).toMatch(/min-h-\[/);
+    });
+});
+
+describe("the settings view on a change to the field", () => {
+    let elements;
+    let flashes;
+    let saves;
+    let state;
+
+    // A stand-in for one DOM node: enough of an element for init() to set
+    // properties on it and hang listeners off it.
+    function fakeElement() {
+        return {
+            value: "",
+            checked: false,
+            textContent: "",
+            href: "",
+            style: {},
+            dataset: {},
+            classList: { add() {}, remove() {} },
+            listeners: {},
+            addEventListener(event, handler) {
+                this.listeners[event] = handler;
+            },
+            querySelectorAll: () => [],
+        };
+    }
+
+    function loadSettingsView() {
+        elements = {};
+        flashes = [];
+        saves = 0;
+
+        jest.resetModules();
+
+        jest.doMock("../src/popup/views/helpers", () => ({
+            $: (id) => (elements[id] ||= fakeElement()),
+            showView: () => {},
+            updateDebugBanner: () => {},
+            showFlash: (msg) => flashes.push(msg),
+            escapeHtml: (s) => s,
+            flashCopyFeedback: () => {},
+            goBack: () => {},
+            pushCurrentView: () => {},
+            onViewLeave: () => {},
+            VIEWS: [],
+        }));
+
+        state = require("../src/shared/state").state;
+        state.dustThresholdGwei = 100000;
+
+        const settings = require("../src/popup/views/settings");
+        settings.init({});
+        return elements["settings-dust-threshold"];
+    }
+
+    beforeEach(() => {
+        globalThis.chrome = {
+            runtime: { sendMessage: () => {} },
+            storage: {
+                local: {
+                    get: async () => ({}),
+                    set: async () => {
+                        saves++;
+                    },
+                },
+            },
+        };
+    });
+
+    afterEach(() => {
+        jest.dontMock("../src/popup/views/helpers");
+        delete globalThis.chrome;
+    });
+
+    async function change(field, typed) {
+        field.value = typed;
+        await field.listeners.change();
+    }
+
+    test("a valid value is stored and says nothing", async () => {
+        const field = loadSettingsView();
+
+        await change(field, "250");
+
+        expect(state.dustThresholdGwei).toBe(250);
+        expect(field.value).toBe(250);
+        expect(flashes).toEqual([]);
+        expect(saves).toBe(1);
+    });
+
+    test("a rejected value shows the message and is not stored", async () => {
+        const field = loadSettingsView();
+
+        await change(field, "1.5");
+
+        expect(state.dustThresholdGwei).toBe(100000);
+        expect(flashes).toEqual([DUST_THRESHOLD_MESSAGE]);
+        expect(saves).toBe(0);
+    });
+
+    // The snap-back is the behaviour the message explains, so it stays.
+    test("a rejected value still resyncs the field to what is stored", async () => {
+        const field = loadSettingsView();
+
+        await change(field, "100 gwei");
+
+        expect(field.value).toBe(100000);
+    });
+
+    test("every rejected notation gets the same one message", async () => {
+        for (const typed of ["", "-1", "1.5", "100 gwei", "0x10", "1e3"]) {
+            const field = loadSettingsView();
+
+            await change(field, typed);
+
+            expect(flashes).toEqual([DUST_THRESHOLD_MESSAGE]);
+            expect(state.dustThresholdGwei).toBe(100000);
+        }
+    });
+
+    test("zero is accepted, not treated as an empty field", async () => {
+        const field = loadSettingsView();
+
+        await change(field, "0");
+
+        expect(state.dustThresholdGwei).toBe(0);
+        expect(flashes).toEqual([]);
+    });
+});

tests/e2e/run.js

@@ -19,6 +19,7 @@ const {
     visible,
 } = require("./harness");
 const { STUB_TOKEN, STUB_TX_HASH } = require("./network");
+const { DUST_THRESHOLD_MESSAGE } = require("../../src/popup/dustThreshold");
 
 const TEST_TIMEOUT_MS = 120000;
 
@@ -493,6 +494,135 @@ test("confirming removes the address and returns Home (#162)", async (env) => {
     );
 });
 
+// ------------------------------------------------ dust threshold (#233)
+
+// The popup size README documents the UI as designed for. Pages in this
+// context otherwise get Playwright's 1280x720 default, at which the flash
+// line has room for any plausible message and never wraps — measuring
+// there would pass for every string and prove nothing.
+const POPUP_VIEWPORT = { width: 360, height: 600 };
+
+// Everything below the flash line that must not move when it fills, plus
+// the height of the line itself. Runs in the page.
+//
+// Positions are in document coordinates, not viewport coordinates:
+// tabbing out of the field to fire "change" scrolls the popup, and a
+// getBoundingClientRect().top read across that scroll reports a thousand
+// pixels of movement that is the scroll, not a layout shift.
+function measureFlashLine() {
+    const top = (id) =>
+        document.getElementById(id).getBoundingClientRect().top +
+        window.scrollY;
+    return {
+        text: document.getElementById("flash-msg").textContent,
+        flashHeight: document
+            .getElementById("flash-msg")
+            .getBoundingClientRect().height,
+        settingsTop: top("view-settings"),
+        fieldTop: top("settings-dust-threshold"),
+    };
+}
+
+// Polling one evaluate() rather than waitForFunction() plus a second
+// round trip to measure: showFlash() clears the line again after 2s, and
+// measuring in a separate call can land after that and read an empty
+// line — which would pass however long the message is. Here the text
+// check and the geometry come from the same page task, so what is
+// measured is always the filled line. Missing the 2s window entirely
+// throws; it cannot go green.
+async function waitForFilledFlashLine(page) {
+    const deadline = Date.now() + 15000;
+    for (;;) {
+        const m = await page.evaluate(measureFlashLine);
+        if (m.text.length > 0) return m;
+        if (Date.now() > deadline) {
+            throw new Error("the flash line never filled");
+        }
+        await sleep(25);
+    }
+}
+
+// README, No Layout Shift: the rejection message goes into #flash-msg,
+// whose min-h-[1.25rem] reserves exactly ONE line at text-xs. Reserving
+// the space is not enough on its own — a message too long for one line
+// wraps and pushes everything below it down anyway, which is what the
+// first version of this change shipped: 75 characters, 32px, the settings
+// view and the threshold field 12px lower than with an empty line.
+//
+// So this measures rather than inspects markup. It is the only assertion
+// in the repo that can see the wording grow: the unit suite runs on the
+// node environment with no layout engine, where every height is zero (see
+// the note in tests/dustThreshold.test.js). Lengthen
+// DUST_THRESHOLD_MESSAGE past one line and this test goes red.
+test("a rejected dust threshold shifts no layout (#233)", async (env) => {
+    const page = await openPopup(env.ctx, env.popupUrl);
+    try {
+        await page.setViewportSize(POPUP_VIEWPORT);
+        await openSettings(page);
+
+        const before = await page.evaluate(measureFlashLine);
+        assert(
+            before.text === "",
+            "the flash line was not empty at the baseline measurement: " +
+                JSON.stringify(before.text),
+        );
+
+        // "change" fires on blur, not on typing, so fill() alone is not
+        // enough — it only dispatches "input".
+        await page.fill("#settings-dust-threshold", "1.5");
+        await page.locator("#settings-dust-threshold").press("Tab");
+
+        const after = await waitForFilledFlashLine(page);
+
+        // Printed pass or fail: the numbers are the evidence, and a
+        // silent assertion would leave the reader taking this on trust.
+        console.log(
+            "# dust threshold flash: " +
+                after.text.length +
+                " chars, line height " +
+                before.flashHeight +
+                " -> " +
+                after.flashHeight +
+                ", view-settings top " +
+                before.settingsTop +
+                " -> " +
+                after.settingsTop +
+                ", field top " +
+                before.fieldTop +
+                " -> " +
+                after.fieldTop,
+        );
+
+        assert(
+            after.text === DUST_THRESHOLD_MESSAGE,
+            "the field flashed something other than DUST_THRESHOLD_MESSAGE: " +
+                JSON.stringify(after.text),
+        );
+        assert(
+            after.flashHeight === before.flashHeight,
+            "the message does not fit the reserved line: " +
+                before.flashHeight +
+                "px empty vs " +
+                after.flashHeight +
+                "px with the message. Shorten DUST_THRESHOLD_MESSAGE",
+        );
+        assert(
+            after.settingsTop === before.settingsTop,
+            "the settings view moved " +
+                (after.settingsTop - before.settingsTop) +
+                "px when the message appeared",
+        );
+        assert(
+            after.fieldTop === before.fieldTop,
+            "the dust threshold field moved " +
+                (after.fieldTop - before.fieldTop) +
+                "px when the message appeared",
+        );
+    } finally {
+        await page.close();
+    }
+});
+
 // ---------------------------------------------------------------- runner
 
 async function main() {