routine 2026-10-12: reloads put the reader back — no 2 px creep on an open README, every page restores (not only /), the browser's restore jumps

[physics515]

Three fixes to how pages come back on a reload or on Back. Run window: 21:10 → 01:09 CDT.

Increment 1: a reload of an open README lands where the reader was (2c2018d)

Roadmap item: "A reload of an unfolded README lands 2–9 px past the reader's place". This is the check:navigation flake that could turn CI red. Ticked.

Files: app/plugins/readme-restore.client.ts (new), app/composables/useReadmeFold.ts, ROADMAP.md

What was wrong. Two restores ran on each such reload: the fold's own, and Chromium's. Nuxt's router plugin leaves history.scrollRestoration = 'auto' for the first document, so Chromium also restored the page. It did so after the fold had already scrolled, and landed 2 px further. The next reload saved that position, so each reload crept 2 px more.

How it was found. A frame-by-frame trace: the fold's scrollTo({top: 4200}) read 4200, and the very next scroll event read 4202. A full-depth layout diff found no element that moved in between, so it was never layout or scroll anchoring. That also explains last night's contradictory overflow-anchor bisect: injecting any style at DOMContentLoaded changed the timing, and a no-op control style suppressed the drift too.

What decides it. Pinning manual from document start: 0 drifts in 42 reloads; the pass-through control: 14 in 42. Two things have to be true together:

• Nuxt's auto write must be held off in the same task. Re-setting manual in a microtask gave 0 in 26; in the next task, 13 in 28. Setting it from a plugin after the router's gave 16 in 42, and once mounted, 17 in 42.
• The entry must leave the previous document as manual. Without this, the first reload still drifted.

The fix.

• A client plugin runs before Nuxt's router plugin (order: -25, ahead of its pre at -20). It holds manual through Nuxt's write, but only when the fold will restore this entry: a reload or Back/Forward, readmeOpen === true, and a stored position. It releases at app:mounted.
• The fold sets manual when it opens, and gives back what it took when folded again.

Result: onyums at 390 px, 0 drifts in 42 reloads, at DPR 1 and at CI's phone profile (DPR 3, mobile).

Increment 2: a reload puts the reader back on every page, not only / (3a420e7)

Roadmap item: new (found while verifying increment 1). Ticked.

Files: app/router.options.ts, scripts/check-navigation.mjs, ROADMAP.md, README.md

What was wrong. In both engines, a reload of /projects at 1,200 px landed at 0, and so did an about page with its README folded. In Chromium, Back from another site to /projects, /news or a blog tab also landed at 0. Only / came back.

Why. Nuxt's router plugin runs one start-up navigation from START_LOCATION. With no saved position, it answers {top: 0}, and that cancelled the browser's own restore. / was spared only by Nuxt's same-path rule, because START_LOCATION's path is /. vue-router's saved position can't help: Chromium drops its beforeunload write, so history.state.scroll is false on every reload.

The fix. On the page's own load, with neither a saved position nor a hash, the scroll is left alone.

Before → after, 390 px, side by side with main's build on this host:

Case	main	this branch
Chromium /projects reload	0	1,200
Chromium folded onyums reload	0	1,500
Firefox, same two cases	0	restored
Chromium Back from another origin (/projects, /news, onyums/blog)	0	1,200 / 604 / 734

Firefox already restored those Back cases from its back-forward cache, and still does.

Guard. check:navigation now reloads each folded about page halfway down. Main's build fails it on all 16 page × width cases (three runs); this build passes 160 checks in Chromium and in Firefox.

Increment 3: the browser's own restore is a jump, not an animation (7c4d76e)

Roadmap item: new (found while tracing increment 2). Ticked.

Files: app/plugins/restore-jump.client.ts (new), ROADMAP.md

What was wrong. Chromium applies the site's scroll-behavior: smooth to its own restore. A reload of / at 1,200 px scrolled from the top over ~550 ms, in 34 scroll events. Firefox jumps.

The fix. On a reload or Back/Forward, the page holds scroll-behavior: auto until scrolling has been still for 300 ms (3 s at most).

Result: 34 scroll events → 1 on / and /projects in Chromium. In Firefox the restore often lands before the plugin listens, so smooth scrolling comes back at the 3 s fallback; checked at 3.5 s. A fresh visit and a page without script are untouched.

Verification

Final tree (e6bb4e6):

• Typecheck clean, build green.
• 276 tests in 30 files.
• og:check, font:check, sizes:check, contrast and audit:runtime all pass.

Real server, final build:

• /healthz 200, / 200, /projects 200, all 8 /projects/<slug>/about and /blog pages 200.
• /projects/<slug> 301.
• /no-such-page and /projects/no-such-project 404, and the onion admin probes 404.
• /onion-frame 503 (no local gateway, same as main).
• Overall 25×200, 8×301, 8×404, 1×503, identical to last night.

Checks, with fixture content:

• check: 22 pages, 79 URLs.
• a11y: 23 pages.
• a11y:browser and a11y:firefox: 23 pages × 3 widths, clean.
• check:navigation in Firefox: 160/160.
• check:navigation in Chromium: green on increments 1 and 2. On increment 3's build, see the open bug below.

Screenshots (headless Chromium, desktop 1280 and phone 390, of home, Skidbladnir and Nisaba) are in the run's scratch dir. I looked at them: the flat single background is intact, the masthead glass is unchanged, and nothing overflows.

Bugs found, not fixed

1. A cold load of about#<heading> can land 2 px short of the masthead. Nanna, phone width, #api-key-invalid: the heading sat 2 px under the masthead edge, outside the 0–200 band.
   • It failed in 1 of 6 Chromium check:navigation runs on this build. Another run stalled on the same page until its 15-minute timeout; the host was at load 9 with other agents' browsers running. The other 4 passed.
   • It is a fresh navigate load, where all three changes return early. But main's build had no such miss in 3 runs, so I can't show it predates tonight.
   • Alone, 25 cold loads of that URL landed at 16 or 12 px, never out of band.
   • CI can go red on it. It is a new [ ] with next steps.
2. One unit-test run reported 272 tests instead of 276. Five reruns all reported 276. Not explained.
3. Housekeeping: an orphaned headless Firefox of mine (ba-bidi profile) was left alive from an earlier pass; I killed it.

Research

• WHATWG HTML: the scroll restoration mode lives on the session history entry. That fits the finding that the mode the entry leaves with counts. https://html.spec.whatwg.org/multipage/browsing-the-web.html#scroll-restoration-mode
• Nuxt's reload-to-top upstream: Scroll is not restored after refresh nuxt/nuxt#36346 was closed on 2026-10-11 as a duplicate of an i18n issue. This site has no i18n and reproduces it on Nuxt 4.6.1. Added as an owner [ ], since reporting it upstream speaks for the org. Scroll is not restored after refresh nuxt/nuxt#36346 · @nuxtjs/i18n break scroll restoration nuxt-modules/i18n#4157
• GitHub Actions: schedule runs can be delayed under load and dropped if load is high enough. The onion probe ran twice in its first ~20 h. https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#schedule
• marked 18.1.1 (2026-10-12) changes README output: blockquote lazy lines, HTML blocks interrupting paragraphs, backslashes in code spans, tab stops. Its walkTokens quadratic fix does not apply here. Held a night with a byte-diff plan. https://github.com/markedjs/marked/releases/tag/v18.1.1 · walkTokens takes quadratic time because it copies the results array for every token markedjs/marked#4120
• No new signal on Nuxt (4.6.1 still latest), Tailwind (4.3.3), or TypeScript 7.1 (not out; 7.0.2 is latest).

Done vs open

Done:

• Increments 1–3.
• Onion probe's first scheduled runs read and ticked: 82.6 s on a second try after a 120 s connect timeout, and 11.1 s on the first try.
• Snapshot refreshed (Skidbladnir v1.4.3).

New [ ]:

• The cold-load miss.
• Read a few days of onion probe runs.
• marked 18.1.1.
• Upstream Nuxt report (owner).

Still owner-gated or upstream: unchanged from #22.

STOP REASON: 4 h cutoff (21:10 → 01:09 CDT). Three increments landed. The fourth slice, the cold-load miss, was measured but not fixed, and is written up as the next item.

Recommended next step

1. Cold-load miss: run the case inside the check's own sequence with its frame trace, on both builds, and find what the stalled run waited on.
2. Take marked 18.1.1 with a byte diff of every README and post.
3. Owner: decide whether to report the Nuxt reload-to-top upstream.

Shipped

• CI: green (build 26 m 27 s, image builds, onion gateway). Merged as d1f41c8, with a tree identical to the verified branch.
• Release: prerelease nightly-2026-10-12.
• Deploy: the prior image was tagged basicautomation-site:previous (023c0fd13d51) first. The new :local (636d5e5dab10) is built from merged main and reported healthy in ~10 s.
• Live gate:
  • https://basicautomation.io/ 200, with the <title> "basic automation — software for the productive".
  • /projects/skidbladnir/about 200, /projects 200.
  • /healthz 200: status ok, data live, onion launched.
• Live behaviour: the reload probe against production now gives /projects 1200→1200, folded onyums 1500→1500 and open onyums 4200→4200. Before the deploy, the same probe on the live site gave 0, 0 and 4200.
• No rollback was needed.

🤖 Generated with Claude Code