@escape-game-over/atlas 0.1.61 → 0.1.62

package/docs/client-scripts.md

@@ -63,9 +63,7 @@ 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.
+the previous entry, and the write wipes the position about to be restored.
 
 **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
@@ -102,16 +100,9 @@ undo and then the function again — so it has to be able to run twice. State th
 must survive a move goes in a `WeakMap` keyed by `root`, which is what the
 carousel example does with its index.
 
-**The trap this exists for is view transitions.** A bundled `<script src>` is an
-ES module, cached by URL, so it executes once per session — not once per
-navigation. Bind at module scope with `ClientRouter` on and the incoming page
-gets a live list and dead controls: the markup was swapped, the handlers still
-point at what was there before. Driving `attach` from `astro:page-load` and
-calling its return on teardown is the fix, and it is why none of these modules
-does anything at import time.
-
-Note that the abort half alone does not help. It makes the breakage look
-handled. Without a re-`attach` there is simply nothing wired.
+Astro's `ClientRouter`, which swaps pages without reloading them, is refused at
+build time by `siteRoutes()`: every module here, and every analytics vendor,
+assumes one full page load per navigation.
 
 ## `filters`
 

package/package.json

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

package/src/astro/Document.astro

@@ -6,9 +6,7 @@
  * 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.
+ * `docs/client-scripts.md`. `restoreScroll={false}` leaves it to the browser.
  *
  * A site with a lead form passes `rememberCampaign`, so the `utm_*` tags a
  * visit landed with survive to the page the form is on; see `attribution.ts`.
@@ -44,10 +42,10 @@ interface Props {
     /** `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;
     /** Off unless stated: a site with no lead form has nothing to keep them for. */
     readonly rememberCampaign?: boolean;
+    /** Defaults to `true`; `false` leaves scroll restoration to the browser. */
+    readonly restoreScroll?: boolean;
     /** Defaults to `true`. */
     readonly rememberLocale?: boolean;
 }
@@ -57,8 +55,8 @@ const {
     fonts = {},
     html,
     body,
-    restoreScroll = true,
     rememberCampaign = false,
+    restoreScroll = true,
     rememberLocale = true,
 } = Astro.props;
 

package/src/astro/dev-log.ts

@@ -41,9 +41,9 @@ function panel(): HTMLElement {
     const existing = document.getElementById(PANEL_ID);
     if (existing) return existing;
 
-    // Either nothing has failed yet, or the document this lived in was swapped
-    // out from under it — a client router replacing `<body>`. Either way every
-    // line in `seen` is detached, and counting into one would report nothing.
+    // Either nothing has failed yet, or the panel was removed from the page.
+    // Either way every line in `seen` is detached, and counting into one would
+    // report nothing.
     seen.clear();
 
     const created = document.createElement("div");

package/src/astro/element.ts

@@ -48,8 +48,8 @@ export interface ElementTag<Tag extends string = string> {
  * template imports the same file.
  *
  * - **An element can enter the page more than once.** Moving it runs the undo
- *   and `connect` again; Astro's `ClientRouter` does so on every navigation.
- *   State that must survive belongs in a `WeakMap` keyed by `root`.
+ *   and `connect` again. State that must survive belongs in a `WeakMap` keyed
+ *   by `root`.
  * - **The page's script must stay a bundled module** (a plain `<script>`), so
  *   the element has its children when it upgrades.
  * - **Failures show in dev.** A `connect` that throws leaves that one element

package/src/astro/filters.ts

@@ -336,8 +336,8 @@ export function filters<const F extends FieldMap, T>(
         const query = parts.join("&");
         // The bare path when nothing is left, rather than a trailing `?`.
         const url = query === "" ? window.location.pathname : `?${query}`;
-        // `null` on a pushed step, so Astro's `ClientRouter` leaves its popstate
-        // to this module; a replaced entry keeps whatever state it already had.
+        // `null` on a pushed step; a replaced entry keeps whatever state it
+        // already had, such as the position `ScrollRestore` saved there.
         if (history === "push") window.history.pushState(null, "", url);
         else window.history.replaceState(window.history.state, "", url);
     }

package/src/astro/no-client-router.ts

@@ -0,0 +1,35 @@
+import type { Plugin } from "vite";
+
+/** What a site imports to turn Astro's `ClientRouter` on. */
+const CLIENT_ROUTER = new Set([
+    "astro:transitions",
+    "astro/components/ClientRouter.astro",
+]);
+
+/**
+ * Fails the build when a site imports `ClientRouter`.
+ *
+ * Atlas assumes a full page load per navigation: analytics count a page view
+ * per load, vendor scripts and widgets start once per page, and nothing tears
+ * them down. Under the router none of that holds, and nothing errors — the
+ * numbers and the widgets just go quietly wrong. The animation it gives is
+ * available without it: `@view-transition { navigation: auto; }` in CSS.
+ *
+ * Only the site's own imports are checked. Astro and other packages may name
+ * the module for their own reasons.
+ */
+export function noClientRouter(): Plugin {
+    return {
+        name: "atlas:no-client-router",
+        enforce: "pre",
+        resolveId(id, importer) {
+            if (!CLIENT_ROUTER.has(id)) return null;
+            if (importer === undefined || importer.includes("/node_modules/")) {
+                return null;
+            }
+            throw new Error(
+                `${importer} imports ${id}. Astro's ClientRouter is not supported: Atlas's analytics, consent and widgets expect a full page load per navigation. For the animation, use cross-document view transitions — \`@view-transition { navigation: auto; }\` in CSS.`
+            );
+        },
+    };
+}

package/src/astro/site-routes.ts

@@ -11,6 +11,7 @@ import type { Sitemap } from "../sitemap.ts";
 import type { HttpsUrl } from "../url.ts";
 import { warn } from "../warn.ts";
 import { buildCacheDir } from "./build-cache.ts";
+import { noClientRouter } from "./no-client-router.ts";
 
 /**
  * What this integration needs of a site, and no more.
@@ -282,7 +283,12 @@ export function siteRoutes(options: SiteRoutesOptions): AstroIntegration {
                     },
                     cacheDir: buildCacheDir(),
                 };
-                updateConfig(config);
+                // The plugin is kept out of `config`, which is logged below: a
+                // plugin prints as noise.
+                updateConfig({
+                    ...config,
+                    vite: { plugins: [noClientRouter()] },
+                });
                 // Said out loud: a setting changed from under you is worth a
                 // line, and reading `astro.config.ts` would otherwise leave you
                 // to wonder why the output is not shaped the way its defaults