@escape-game-over/atlas 0.1.31 → 0.1.32

package/docs/client-scripts.md

@@ -49,6 +49,17 @@ analytics need no permission, and remembers, expires and applies the answer. The
 markup marks its buttons `data-consent="grant"` and `data-consent="deny"`,
 and the control that brings it back `data-consent-reopen hidden`.
 
+`Document` ships one more: scroll restoration, on unless `restoreScroll={false}`.
+WebKit restores a page's position only at `load`, after every image, so a page
+it reloads on back paints its top and then snaps down — and Firefox on iOS
+reloads on nearly every back. An inline script at the end of `<body>` saves the
+position on the history entry once scrolling settles, and puts it back before
+the first paint. On the entry, not in storage keyed by URL, so a link to the same
+page still opens at the top. Never on `pagehide`: WebKit fires it after moving to
+the previous entry, and the write wipes the position about to be restored. A
+site on Astro's `ClientRouter` turns it off; the router keeps its own position
+in the same history state.
+
 **Browser code has one import path: `@escape-game-over/atlas/client`**, which
 re-exports every module above. None of it touches the DOM at import, so an
 element's contract can be imported in frontmatter from the same path.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.31",
+    "version": "0.1.32",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,

package/src/astro/Document.astro

@@ -5,6 +5,11 @@
  * `head-start` comes before every tag Atlas writes — a consent manager that must
  * load ahead of the analytics goes there; `head` comes after.
  *
+ * It also restores the scroll position on back and reload; see
+ * `docs/client-scripts.md`. A site on Astro's `ClientRouter` passes
+ * `restoreScroll={false}`: the router keeps its own position in the same
+ * history state.
+ *
  * ```astro
  * <Document meta={meta} html={{ class: "scroll-smooth" }} body={{ class: "…" }}>
  *     <Fragment slot="head"><link rel="preload" … /></Fragment>
@@ -15,15 +20,18 @@
 import type { HTMLAttributes } from "astro/types";
 import type { PageMeta } from "../site/index.ts";
 import MetaTags from "./MetaTags.astro";
+import ScrollRestore from "./ScrollRestore.astro";
 
 interface Props {
     readonly meta: PageMeta;
     /** `lang` and `dir` are the page's locale's, from `meta`. */
     readonly html?: Omit<HTMLAttributes<"html">, "lang" | "dir">;
     readonly body?: HTMLAttributes<"body">;
+    /** Defaults to `true`; `false` for a site on `ClientRouter`. */
+    readonly restoreScroll?: boolean;
 }
 
-const { meta, html, body } = Astro.props;
+const { meta, html, body, restoreScroll = true } = Astro.props;
 ---
 
 <!doctype html>
@@ -40,5 +48,6 @@ const { meta, html, body } = Astro.props;
     <body {...body}>
         <MetaTags tags={meta.bodyTags} />
         <slot />
+        {restoreScroll && <ScrollRestore />}
     </body>
 </html>

package/src/astro/ScrollRestore.astro

@@ -0,0 +1,57 @@
+---
+/**
+ * Puts a page back where the reader left it, before the first paint.
+ *
+ * WebKit restores scroll only at `load`, after every image, so a page it
+ * reloads on back shows its top and then snaps down — and Firefox on iOS
+ * reloads on nearly every back. The position is kept on the history entry, as
+ * the browser keeps its own, so a link to the same page still opens at the top.
+ *
+ * Rendered by `Document` after the page, where the layout already exists.
+ * Inline, because a bundled module runs too late: after the first paint.
+ */
+---
+
+<script is:inline>
+{
+    history.scrollRestoration = "manual";
+
+    const save = () => {
+        try {
+            history.replaceState({ ...history.state, scrollY }, "");
+        } catch {
+            // Safari throttles replaceState; the last saved position stands.
+        }
+    };
+
+    // Once scrolling settles, not per frame: Safari caps replaceState calls.
+    let settle = 0;
+    addEventListener(
+        "scroll",
+        () => {
+            clearTimeout(settle);
+            settle = setTimeout(save, 300);
+        },
+        { passive: true }
+    );
+    // No save on `pagehide`. WebKit fires it after moving to the previous entry,
+    // and Firefox on iOS restores a page at the top and reloads it at once, so
+    // either way the save would wipe the position about to be restored.
+
+    // `instant`, or a site with `scroll-behavior: smooth` glides down from the
+    // top — the jump this exists to remove, in slow motion.
+    const restore = (state) => {
+        if (typeof state?.scrollY === "number") {
+            scrollTo({ top: state.scrollY, behavior: "instant" });
+        }
+    };
+
+    restore(history.state);
+
+    // Filters push entries on the same page; `manual` turned off restoring
+    // those too. A frame later, so the filtered list has re-rendered first.
+    addEventListener("popstate", (event) => {
+        requestAnimationFrame(() => restore(event.state));
+    });
+}
+</script>