Follow the walk: watchPosition, gated so the list cannot re-sort under a thumb

[EnesYilmazcode]

Closes #87.

locate() asked the phone where it was exactly once, at boot, and every answer for the rest of the session was ranked from that point. The product is one number — usable = window - walk - packup — and the walk was measured from a place the student leaves the moment they set off toward the room.

This is #87 option 1: watchPosition, throttled, feeding the existing useOrigin → refresh() path, with the repaint gated so the list cannot re-sort under a thumb.

The suite was not evidence, and that was the reason to hold this

The first version of this PR reported "17 mutations, all caught". That was true of the seventeen chosen and it was the wrong conclusion. followFix and followAction are pure and genuinely mutation-checked, but the lifecycle around them was not: it lived in js/app.js, which touches the DOM at import and cannot be loaded under node, so follow.test.mjs asserted regexes over the source text. That kills a mutation which rewrites a quoted string and nothing else.

Reviewed with 26 mutations. Five survived a green suite, and grep -rn "watchId" scripts/test/ returned nothing:

mutation	what it would ship
clearWatch(0) instead of clearWatch(watchId)	the watch never actually stops
drop the watchId != null guard	two live watches, doubled battery
drop watchId = null in stopWatch	watch permanently off after one background cycle
drop either half of the throttle	every fix re-ranks

The handle is a state machine in js/state.js now (createWatch), with the geolocation object and the visibility predicate injected, so all five are unit-testable. Re-run against the new tests, every one fails:

clearWatch(0)                     1 failing
no double-start guard             1 failing
handle not nulled                 2 failing
opens a watch on a hidden page    1 failing
picked origin followed anyway     2 failing

It is spelled geolocation rather than geo because install.test.mjs forbids the string geo: anywhere in js/ — geo: URIs are inert on iOS — and a property named geo trips that guard for nothing.

Two false sentences on the privacy page

Both were introduced by the first version of this branch, and both are now true of the code:

• "never starts at all if you picked a building by hand" — false for a pick made mid-session. pickBuilding wrote the origin and left the watch open until the next position arrived to be judged, which with maximumAge: 0, no timeout and a student who has just walked indoors can be minutes away or never. It calls stopWatch() now.
• "stops the moment you switch away" — false if the page was hidden before the boot fix landed. follow() called startWatch() with no visibility check, after visibilitychange had already fired, so the watch ran until the user foregrounded and backgrounded again. createWatch refuses a hidden page.

Two more in the same paragraph were older than this branch and plainly wrong. The position is put in a URL: mapsHref puts the gps lat,lon into saddr/origin and hands it to Apple or Google on the Directions tap. And there are twelve JavaScript files, not four. The page describes the handoff now, says it happens only on a tap and never on its own, and says the old claim was wrong. A test holds all three to the code.

Two more from the review

• repaintRoom killed the compass and leaked its listeners. It rewrites #room's innerHTML, detaching the needle, its arrow and its label, while orientationOff still closed over the old nodes and its two window listeners stayed bound. The needle silently vanished every FOLLOW_M of the walk it exists for, and a second tap orphaned the first pair permanently. It releases the compass first.
• Nothing cleared state.selected on the way back from a room. followAction returned 'hold' forever, under 'hold' refresh() never ran, so answer() — the only other thing that nulls it — never ran either. Open the app, tap a room, press back, walk: the list held boot values for the rest of the session, which is exactly the staleness Your location is read once at boot and never again, so the walk times are wrong the moment you start walking #87 exists to remove. showList clears it.

The gates

refresh() carries the rule this change had to not break — a list that re-sorts under a thumb loses the row somebody was reaching for. followAction() is the whole gate, pure, and the order of its tests is the rule (screen === 'room' before selected, because opening a room always selects its row).

gate	behaviour
room open	walk minutes and "yours for" redrawn in place, ranking untouched
row selected	dot and line move, order stands
finger on the sheet	holds, on every screen
list scrolled below the top	holds — "idle and untouched"
idle, untouched list	re-ranks
origin picked by hand	the watch closes, the pick is never overwritten
page hidden	watch stopped, and never opened on an already-hidden page
off-campus check	runs on the boot fix and every accepted position

FOLLOW_M = 40 is 0.51 minutes at the engine's WALK_MPM of 78, under the COARSE_M of 75. FOLLOW_MS = 15000 is a guess and the comment says so — it is the number a battery run would move.

Tests

731 tests, 727 pass, 0 fail, 4 skipped. check-dead-code --strict: 84 files, no dead code. Shell gzip re-measured through the command the header documents: 98,246 bytes.

main had moved five lanes ahead; this merges it. showRoom's frames.wake() from #94 is kept alongside the wireRoom() extraction.

What is still NOT done

There is no battery measurement. The done-when "measured on a real phone: battery cost over a 15 minute walk with the app open" is not satisfied and stays open. No phone was involved in any part of this and no number was invented. The DECISIONS.md entry lists what has not been observed:

• what a coarse watch costs over a quarter hour of walking
• whether an installed iOS PWA holds a watch at all (SPIKE: does geolocation work in an installed PWA on current iOS? #5), and whether it survives backgrounding
• how often a stationary phone crosses the 40 m line, which is what FOLLOW_MS was guessed against
• whether repaintRoom's scroll and focus restoration is actually invisible to a reader

This remains the riskiest change of the batch: it alters runtime behaviour that cannot be validated without a device. The difference from the first version is that the suite now covers the parts that can be tested offline, rather than appearing to.

Also not done, on purpose: #88 is not fixed here (clearPickedOrigin is still unreachable; it gained one line so the watch returns if it is ever reached). sw.js is not re-stamped — the stamp is a HEAD sha and belongs to whatever commit merges.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_017xiX95r6nnUUmhD3KwMnWM