@escape-game-over/atlas 0.1.30 → 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.30",
+    "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>

package/src/astro/carousel.ts

@@ -62,6 +62,17 @@ export interface CarouselOptions {
      * renders, and calling would make a project write the first position twice.
      */
     readonly onChange: (index: number) => void;
+    /**
+     * Called with `autoplayMs` whenever a countdown to the next automatic
+     * advance begins, and with `null` when autoplay stops.
+     *
+     * For a progress bar. A countdown begins on attach, after every tick and
+     * after every manual move, and each one starts from zero — so the bar
+     * restarts on every number and stops on `null`, and never has to know why.
+     * A hold (hover, focus, a hidden tab, `pause`) and a detach report `null`
+     * once, not once per reason.
+     */
+    readonly onCountdown?: (ms: number | null) => void;
 }
 
 export interface Carousel {
@@ -107,6 +118,7 @@ export function carousel(options: CarouselOptions): Carousel {
         swipeThreshold = 10,
         lockMs = 500,
         onChange,
+        onCountdown,
     } = options;
 
     /**
@@ -143,9 +155,19 @@ export function carousel(options: CarouselOptions): Carousel {
      */
     const holds = new Set<string>();
 
+    /** Whether a countdown is running, so `null` is reported once per stop. */
+    let counting = false;
+
+    const stopAutoplay = (): void => {
+        clearInterval(autoplayTimer);
+        if (!counting) return;
+        counting = false;
+        onCountdown?.(null);
+    };
+
     const hold = (reason: string): void => {
         holds.add(reason);
-        clearInterval(autoplayTimer);
+        stopAutoplay();
     };
 
     const release = (reason: string): void => {
@@ -171,16 +193,28 @@ export function carousel(options: CarouselOptions): Carousel {
     };
 
     const restartAutoplay = (): void => {
-        clearInterval(autoplayTimer);
         // Nothing to rotate through, nobody watching, or no autoplay asked
         // for — in each case, nothing to schedule.
-        if (autoplayMs === undefined || !canMove || !attached) return;
-        if (holds.size > 0) return;
+        if (
+            autoplayMs === undefined ||
+            !canMove ||
+            !attached ||
+            holds.size > 0
+        ) {
+            stopAutoplay();
+            return;
+        }
+        clearInterval(autoplayTimer);
         autoplayTimer = setInterval(() => {
             // No `restartAutoplay` here: the interval already paces itself, and
             // resetting it from inside its own tick would only churn timers.
             if (claim()) move(index + 1);
+            // Reported even when the lock refused the move: the next tick is
+            // still `autoplayMs` away either way.
+            onCountdown?.(autoplayMs);
         }, autoplayMs);
+        counting = true;
+        onCountdown?.(autoplayMs);
     };
 
     /** The only place `index` changes. `at` may be out of range or negative. */
@@ -326,7 +360,7 @@ export function carousel(options: CarouselOptions): Carousel {
             return () => {
                 listeners.abort();
                 attached = false;
-                clearInterval(autoplayTimer);
+                stopAutoplay();
 
                 // The automatic holds belong to this attachment: an element
                 // detached while hovered would otherwise keep "hover" forever,