@xingwangzhe/stalux 1.46.2 → 1.46.5

package/src/scripts/route-motion.ts

@@ -37,17 +37,17 @@ interface HeadingMotion {
 // Legacy heading cues remain available to integrations. The router requests
 // one content animation; it never stacks a second animation on the heading.
 const headingMotions: Record<Exclude<RouteMotionPreset, "none">, HeadingMotion> = {
-    glide: { opacity: 0.86, duration: 100 },
-    article: { opacity: 0.86, duration: 100 },
-    enter: { opacity: 0.86, duration: 140, y: 6 },
-    up: { opacity: 0.9, duration: 120, y: -4 },
-    taxonomy: { opacity: 0.85, duration: 120 },
-    previous: { opacity: 0.9, duration: 140, x: -8 },
-    next: { opacity: 0.9, duration: 140, x: 8 },
-    panel: { opacity: 0.9, duration: 120, y: 4 },
-    home: { opacity: 0.9, duration: 120, y: 4 },
-    restore: { opacity: 0.96, duration: 80 },
-    error: { opacity: 0.9, duration: 80 },
+    glide: { opacity: 0.86, duration: 50 },
+    article: { opacity: 0.86, duration: 50 },
+    enter: { opacity: 0.86, duration: 70, y: 6 },
+    up: { opacity: 0.9, duration: 60, y: -4 },
+    taxonomy: { opacity: 0.85, duration: 60 },
+    previous: { opacity: 0.9, duration: 70, x: -8 },
+    next: { opacity: 0.9, duration: 70, x: 8 },
+    panel: { opacity: 0.9, duration: 60, y: 4 },
+    home: { opacity: 0.9, duration: 60, y: 4 },
+    restore: { opacity: 0.96, duration: 40 },
+    error: { opacity: 0.9, duration: 40 },
 };
 
 const MAIN = "main[data-stalux-route]";
@@ -55,41 +55,50 @@ const ARTICLE = "article.stalux-article";
 // Authored per page type by the theme, not inferred from layout: the article
 // body, archive list, tag cloud, post list, word list, link list, home block.
 const CONTENT = "[data-stalux-motion-content]";
+// The one node a page nominates as its cue stage. Preferred over measuring,
+// because measuring an article column forces a full layout of a document that
+// is tens of thousands of pixels tall, before it has ever been painted.
+const STAGE = "[data-stalux-motion-stage]";
 // A persist node marks the three-column article shell. Those sidebars keep
 // their identity across visits and must never travel with a route cue.
 const PERSIST = "[data-swup-persist]";
 
 interface StageMotion {
     opacity: number;
-    /** Enter offset in px. Positive y enters from below, positive x from the right. */
+    /**
+     * Enter offset in px. Positive y enters from below, positive x from the right.
+     * Zero means a pure cross-fade: the column is replaced in place.
+     */
     distance: number;
     axis: "x" | "y";
     duration: number;
 }
 
 // One entry per route kind, because the components are not interchangeable: an
-// article opens from below, the next article slides in from the side that the
-// reader is heading toward, and going back up to an index pulls away upward.
+// article opens from below and going back up to an index pulls away upward.
+//
+// Article-to-article is the exception: the reader keeps the same shell (sidebars,
+// header) and only the column changes, so the column fades in place instead of
+// travelling. Sliding a 28,000px column sideways made the whole page look like it
+// jerked, and the shell already tells the reader where they are.
 const stageMotions: Record<Exclude<RouteMotionPreset, "none">, StageMotion> = {
-    // Article-to-article keeps a lateral direction: previous/next already says
-    // which way the reading order goes, so the cue repeats that, not a fade.
-    previous: { opacity: 0, distance: -36, axis: "x", duration: 300 },
-    next: { opacity: 0, distance: 36, axis: "x", duration: 300 },
+    previous: { opacity: 0, distance: 0, axis: "x", duration: 150 },
+    next: { opacity: 0, distance: 0, axis: "x", duration: 150 },
     // Entering a different article without a reading-direction trigger.
-    article: { opacity: 0, distance: 40, axis: "y", duration: 300 },
+    article: { opacity: 0, distance: 0, axis: "y", duration: 150 },
     // Reaching an article from any list or the home block.
-    enter: { opacity: 0, distance: 56, axis: "y", duration: 340 },
-    home: { opacity: 0, distance: 48, axis: "y", duration: 320 },
+    enter: { opacity: 0, distance: 56, axis: "y", duration: 170 },
+    home: { opacity: 0, distance: 48, axis: "y", duration: 160 },
     // Leaving an article for the archive or a taxonomy index.
-    up: { opacity: 0, distance: -44, axis: "y", duration: 300 },
+    up: { opacity: 0, distance: -44, axis: "y", duration: 150 },
     // Moving between two taxonomy detail pages.
-    taxonomy: { opacity: 0, distance: 36, axis: "y", duration: 280 },
+    taxonomy: { opacity: 0, distance: 36, axis: "y", duration: 140 },
     // About / links / words: single-panel pages.
-    panel: { opacity: 0, distance: 44, axis: "y", duration: 300 },
-    glide: { opacity: 0, distance: 40, axis: "y", duration: 280 },
+    panel: { opacity: 0, distance: 44, axis: "y", duration: 150 },
+    glide: { opacity: 0, distance: 40, axis: "y", duration: 140 },
     // History traversal restores what the reader already saw.
-    restore: { opacity: 0, distance: -36, axis: "y", duration: 280 },
-    error: { opacity: 0, distance: 28, axis: "y", duration: 260 },
+    restore: { opacity: 0, distance: -36, axis: "y", duration: 140 },
+    error: { opacity: 0, distance: 28, axis: "y", duration: 130 },
 };
 
 const laidOut = (element: HTMLElement): boolean => {
@@ -100,14 +109,17 @@ const laidOut = (element: HTMLElement): boolean => {
 /**
  * The single node a route cue may animate for the current document.
  *
- * Picks the largest authored content stage, so an article moves its own column
- * and an archive moves its list, while sidebars (persisted shells), the header
- * and the footer stay untouched. Falls back to `main` only for pages without a
- * persisted shell inside it.
+ * A page can nominate its stage; only when it does not is the largest authored
+ * content stage measured. Measuring is the fallback, not the rule: on an article
+ * the column is tens of thousands of pixels tall and measuring it forces a full
+ * layout of the incoming document at the exact moment the entry cue needs to
+ * start. Sidebars (persisted shells), the header and the footer never qualify.
  */
 export function getRouteStage(): HTMLElement | null {
     const main = document.querySelector<HTMLElement>(MAIN);
     if (!main?.isConnected) return null;
+    const authored = main.querySelector<HTMLElement>(STAGE);
+    if (authored?.isConnected && !authored.closest(PERSIST)) return authored;
     const candidates: HTMLElement[] = [];
     const article = main.querySelector<HTMLElement>(ARTICLE);
     if (article) candidates.push(article);
@@ -156,7 +168,7 @@ function completion() {
 
 /** A route transition never captures a long article, list, or off-screen heading. */
 export function getRouteMotionTarget(focus: HTMLElement | null): HTMLElement | null {
-    if (!focus?.isConnected || !focus.hasAttribute("data-stalux-motion-focus")) return null;
+    if (!(focus?.isConnected && focus.hasAttribute("data-stalux-motion-focus"))) return null;
     const visible = (element: HTMLElement, maxHeight: number) => {
         const rect = element.getBoundingClientRect();
         return (
@@ -177,17 +189,17 @@ export function getRouteMotionTarget(focus: HTMLElement | null): HTMLElement | n
 }
 
 const regionMotions: Record<Exclude<RouteMotionPreset, "none">, HeadingMotion> = {
-    glide: { opacity: 0.72, duration: 160 },
-    article: { opacity: 0.72, duration: 180, y: 4 },
-    enter: { opacity: 0.72, duration: 180, y: 6 },
-    up: { opacity: 0.8, duration: 160, y: -4 },
-    taxonomy: { opacity: 0.72, duration: 160, x: 6 },
-    previous: { opacity: 0.76, duration: 180, x: -8 },
-    next: { opacity: 0.76, duration: 180, x: 8 },
-    panel: { opacity: 0.76, duration: 160, y: 4 },
-    home: { opacity: 0.76, duration: 180, y: 4 },
+    glide: { opacity: 0.72, duration: 80 },
+    article: { opacity: 0.72, duration: 90, y: 4 },
+    enter: { opacity: 0.72, duration: 90, y: 6 },
+    up: { opacity: 0.8, duration: 80, y: -4 },
+    taxonomy: { opacity: 0.72, duration: 80, x: 6 },
+    previous: { opacity: 0.76, duration: 90, x: -8 },
+    next: { opacity: 0.76, duration: 90, x: 8 },
+    panel: { opacity: 0.76, duration: 80, y: 4 },
+    home: { opacity: 0.76, duration: 90, y: 4 },
     restore: { opacity: 1, duration: 0 },
-    error: { opacity: 0.85, duration: 100 },
+    error: { opacity: 0.85, duration: 50 },
 };
 
 /** Share Swup's actual content animation with background and analytics consumers. */
@@ -281,19 +293,18 @@ export function prepareRouteMotion(event: RouteMotionEvent): RouteMotion {
                         spec.axis === "x"
                             ? `translate3d(${distance}px, 0, 0)`
                             : `translate3d(0, ${distance}px, 0)`;
-                    animation = stage.animate(
-                        {
-                            opacity: [spec.opacity, 1],
-                            transform: [from, "translate3d(0, 0, 0)"],
-                        },
-                        {
-                            duration: mobile ? Math.round(spec.duration * 0.9) : spec.duration,
-                            // Strong ease-out: quick arrival, soft settle. The
-                            // built-in ease-out is too weak to read at this size.
-                            easing: "cubic-bezier(0.23, 1, 0.32, 1)",
-                            fill: "both",
-                        },
-                    );
+                    // A zero distance is a cross-fade in place. Authoring a
+                    // translate3d(0,0,0) would put a 28,000px column on its own
+                    // compositor layer for nothing.
+                    const keyframes: PropertyIndexedKeyframes = { opacity: [spec.opacity, 1] };
+                    if (distance !== 0) keyframes.transform = [from, "translate3d(0, 0, 0)"];
+                    animation = stage.animate(keyframes, {
+                        duration: mobile ? Math.round(spec.duration * 0.9) : spec.duration,
+                        // Strong ease-out: quick arrival, soft settle. The
+                        // built-in ease-out is too weak to read at this size.
+                        easing: "cubic-bezier(0.23, 1, 0.32, 1)",
+                        fill: "both",
+                    });
                 } else {
                     const spec = options?.content ? regionMotions[preset] : headingMotions[preset];
                     const keyframes: PropertyIndexedKeyframes = { opacity: [spec.opacity, 1] };
@@ -306,7 +317,7 @@ export function prepareRouteMotion(event: RouteMotionEvent): RouteMotion {
                         ];
                     }
                     animation = target.animate(keyframes, {
-                        duration: mobile ? (options?.content ? 120 : 80) : spec.duration,
+                        duration: mobile ? (options?.content ? 60 : 40) : spec.duration,
                         easing: "cubic-bezier(0.2, 0.7, 0.2, 1)",
                         fill: "both",
                     });

package/src/scripts/route-out.ts

@@ -16,8 +16,7 @@ export async function animateRouteOut(
     const spec = getStageExit(preset);
     const stage = spec ? getRouteStage() : null;
     if (
-        !spec ||
-        !stage ||
+        !(spec && stage) ||
         signal.aborted ||
         document.hidden ||
         typeof stage.animate !== "function" ||
@@ -28,6 +27,10 @@ export async function animateRouteOut(
     const distance = mobile ? Math.round(spec.distance * 0.6) : spec.distance;
     const to =
         spec.axis === "x" ? `translate3d(${distance}px, 0, 0)` : `translate3d(0, ${distance}px, 0)`;
+    // Article-to-article has no distance: the column fades out in place, matching
+    // the entry fade, so the shell stays put and only the content disappears.
+    const keyframes: PropertyIndexedKeyframes = { opacity: [1, 0] };
+    if (distance !== 0) keyframes.transform = ["translate3d(0, 0, 0)", to];
     let animation: Animation | undefined;
     const cancel = () => {
         const active = animation;
@@ -39,18 +42,13 @@ export async function animateRouteOut(
         }
     };
     try {
-        animation = stage.animate(
-            { opacity: [1, 0], transform: ["translate3d(0, 0, 0)", to] },
-            {
-                duration: mobile
-                    ? Math.round(spec.duration * 0.62)
-                    : Math.round(spec.duration * 0.58),
-                // Strong ease-in: the outgoing document accelerates away. An exit
-                // is the one place ease-in is correct; entrances use ease-out.
-                easing: "cubic-bezier(0.4, 0, 1, 1)",
-                fill: "forwards",
-            },
-        );
+        animation = stage.animate(keyframes, {
+            duration: mobile ? Math.round(spec.duration * 0.62) : Math.round(spec.duration * 0.58),
+            // Strong ease-in: the outgoing document accelerates away. An exit
+            // is the one place ease-in is correct; entrances use ease-out.
+            easing: "cubic-bezier(0.4, 0, 1, 1)",
+            fill: "forwards",
+        });
         signal.addEventListener("abort", cancel, { once: true });
         await animation.finished;
         // The stage node survives the swap, so this filled effect is what holds

package/src/scripts/runtime-counter.ts

@@ -4,7 +4,7 @@ import { observeVisibleClock } from "./visible-clock";
 registerPageLifecycle("runtime-counter", () => {
     const container = document.querySelector<HTMLElement>("[data-stalux-buildtime]");
     const counter = document.getElementById("runtime-counter");
-    if (!container || !counter) return;
+    if (!(container && counter)) return;
     const start = new Date(container.dataset.staluxBuildtime ?? "");
     const format =
         container.dataset.staluxRuntimeFormat ?? "{days}d {hours}h {minutes}m {seconds}s";

package/src/scripts/shell-hydration.ts

@@ -0,0 +1,60 @@
+/**
+ * Keep a shell's frame, refresh only the parts that describe the page.
+ *
+ * A `data-swup-persist` node is kept whole by Swup: that is what makes the
+ * sidebars, the header and the footer survive a visit. For a container whose
+ * *frame* is stable but whose *contents* belong to the page (the article's TOC,
+ * tag list and category list), keeping the node whole would show the previous
+ * article's headings. Marking it `data-stalux-shell-slot` says: keep this node,
+ * take the children from the page we are navigating to.
+ *
+ * Doing it here, synchronously after the swap and before `astro:after-swap`, means
+ * every page module that mounts later sees the refreshed lists and nothing has to
+ * be measured or re-rendered a second time.
+ */
+const SLOT = "[data-stalux-shell-slot]";
+
+/** Persist nodes that existed before this swap; only their slots need refilling. */
+const retained = new WeakSet<Element>();
+
+/** Call before the content is replaced, while the old document is still live. */
+export function markRetainedShells(): void {
+    for (const element of document.querySelectorAll("[data-swup-persist]")) retained.add(element);
+}
+
+export function hydrateShells(next: Document | undefined): number {
+    if (!next || typeof next.querySelector !== "function") return 0;
+    let hydrated = 0;
+    for (const live of document.querySelectorAll<HTMLElement>(SLOT)) {
+        const slot = live.getAttribute?.("data-stalux-shell-slot");
+        if (!slot) continue;
+        // A slot that arrived with the incoming document already holds the right
+        // children; replacing them again would dirty layout for nothing.
+        const shell = live.closest("[data-swup-persist]");
+        if (!(shell && retained.has(shell))) continue;
+        const incoming = next.querySelector<HTMLElement>(`[data-stalux-shell-slot="${slot}"]`);
+        if (!incoming) continue;
+        // Two articles often share the same tags or the same category. Writing
+        // identical children back would dirty layout for a subtree that is
+        // already correct.
+        if (live.innerHTML === incoming.innerHTML) continue;
+        // The incoming nodes belong to another document; importNode adopts them.
+        const fresh = document.importNode(incoming, true);
+        live.replaceChildren(...fresh.childNodes);
+        // These lists are new content even though their frame is old, so the
+        // unroll cue still applies to them.
+        for (const group of live.querySelectorAll<HTMLElement>("[data-stalux-reveal]"))
+            group.setAttribute("data-stalux-shell-fresh", "");
+        hydrated++;
+    }
+    // A shell that is itself new (first visit to an article, or any move between
+    // page types) brings fresh lists with it: they are content, not a kept frame.
+    for (const group of document.querySelectorAll<HTMLElement>(
+        "[data-swup-persist] [data-stalux-reveal]",
+    )) {
+        const shell = group.closest("[data-swup-persist]");
+        if (shell && !retained.has(shell) && !group.hasAttribute("data-stalux-shell-fresh"))
+            group.setAttribute("data-stalux-shell-fresh", "");
+    }
+    return hydrated;
+}

package/src/scripts/smooth-scroll.ts

@@ -12,9 +12,9 @@ export interface PageGlide {
 }
 
 /** Bound the pre-swap return-to-top so a 6000px article does not add a second. */
-const GLIDE_MIN_MS = 160;
-const GLIDE_MAX_MS = 360;
-const GLIDE_SAFETY_MS = 760;
+const GLIDE_MIN_MS = 80;
+const GLIDE_MAX_MS = 180;
+const GLIDE_SAFETY_MS = 380;
 
 /**
  * Walk the current document back to the top before the container is replaced.
@@ -42,7 +42,7 @@ export function glideToTop(): PageGlide {
 
     // Longer documents take proportionally longer, but the ceiling keeps the
     // whole cue inside the same budget as the content fade.
-    const duration = Math.min(GLIDE_MAX_MS, GLIDE_MIN_MS + startTop / 10);
+    const duration = Math.min(GLIDE_MAX_MS, GLIDE_MIN_MS + startTop / 20);
     let frame: number | undefined;
     let settled = false;
     const release = () => {

package/src/scripts/swup-internals.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Type restoration for swup members we depend on but the package omits.
+ *
+ * `Visit.abort()` exists in swup 4.10.0's source (`src/modules/Visit.ts`) and is
+ * marked `/** @internal *\/`, so it is stripped from the published
+ * `dist/types/modules/Visit.d.ts`. The router genuinely needs it: superseding a
+ * visit mid-navigation means marking the old one aborted, and no public API does
+ * that.
+ *
+ * Declaring it here is the honest alternative to casting at the call site: the
+ * compiler now checks the name and the signature everywhere, and there is exactly
+ * one place to revisit when swup changes. Callers still guard with
+ * `typeof visit.abort === "function"` so a future removal degrades to a no-op
+ * instead of throwing in the middle of a navigation.
+ *
+ * Recheck on every swup upgrade:
+ *   grep -n "@internal" node_modules/swup/src/modules/Visit.ts
+ *   grep -n "abort" node_modules/swup/dist/types/modules/Visit.d.ts
+ */
+
+export {};
+
+declare module "swup" {
+    interface Visit {
+        /**
+         * Mark this visit aborted. Internal in 4.10.0; see the note above.
+         * Not a public API: do not call it outside the router adapter.
+         */
+        abort(): void;
+    }
+}

package/src/scripts/swup-router.ts

@@ -12,6 +12,7 @@ import "./navigation-client";
 import { prepareNavigationScripts } from "./navigation-scripts";
 import { prepareRouteMotion, type RouteMotion } from "./route-motion";
 import { animateRouteOut } from "./route-out";
+import { hydrateShells, markRetainedShells } from "./shell-hydration";
 import { cancelPageScroll, glideToTop, type PageGlide, scrollPage } from "./smooth-scroll";
 
 interface NavigationContext {
@@ -35,9 +36,11 @@ type Position = { top: number; left: number; focus?: string };
 const MAIN = "main[data-stalux-route]";
 
 function abortObsoleteVisit(visit: Visit): void {
-    // Swup 4.10 ships abort() but strips @internal members from its .d.ts.
-    // Pin core to that audited version; recheck this adapter when upgrading it.
-    (visit as Visit & { abort: () => void }).abort();
+    // `abort()` is @internal in swup 4.10.0 and stripped from the published
+    // types; swup-internals.d.ts restores the declaration, so this is checked
+    // like any other member. The guard keeps a future removal from throwing in
+    // the middle of a navigation: every caller returns right after this anyway.
+    if (typeof visit.abort === "function") visit.abort();
 }
 
 function dispatchNavigation(name: string, context: NavigationContext, nextDocument?: Document) {
@@ -88,9 +91,9 @@ export function installSwupRouter(): Swup {
     window.addEventListener(
         "popstate",
         (event) => {
-            browserMotion =
-                (event as PopStateEvent & { hasUAVisualTransition?: boolean })
-                    .hasUAVisualTransition === true;
+            // hasUAVisualTransition is part of the DOM lib's PopStateEvent, so
+            // this reads the event directly; the listener is typed for popstate.
+            browserMotion = event.hasUAVisualTransition === true;
         },
         { capture: true },
     );
@@ -181,8 +184,10 @@ export function installSwupRouter(): Swup {
             left: window.scrollX,
             focus,
         });
-        if (historyPositions.size > 64)
-            historyPositions.delete(historyPositions.keys().next().value as number);
+        if (historyPositions.size > 64) {
+            const oldest = historyPositions.keys().next();
+            if (!oldest.done) historyPositions.delete(oldest.value);
+        }
         const from = new URL(visit.from.url + (visit.from.hash ?? ""), window.location.origin);
         const to = new URL(visit.to.url + (visit.to.hash ?? ""), window.location.origin);
         const navigationType = visit.history.popstate ? "traverse" : visit.history.action;
@@ -261,7 +266,7 @@ export function installSwupRouter(): Swup {
         // missing document on an aborted visit is not a failed navigation.
         if (context?.controller.signal.aborted || visit.done || visit !== swup.visit) return;
         const next = visit.to.document;
-        if (!context || !next || !replace) throw new Error("Missing Swup document");
+        if (!(context && next && replace)) throw new Error("Missing Swup document");
         if (context.controller.signal.aborted) return;
         // Two cues overlap on the outgoing document: the content stage leaving,
         // and the page walking back to the top. Persisted sidebars, the header
@@ -283,6 +288,9 @@ export function installSwupRouter(): Swup {
         html.dataset.staluxVtPreset = context.preset;
         context.motion = prepareRouteMotion(dispatchNavigation("astro:before-swap", context, next));
         if (context.controller.signal.aborted) return;
+        // Remember which shells exist now: after the swap only those slots need
+        // refilling, because only those nodes came from the previous document.
+        markRetainedShells();
         await replace(visit, args);
         // The stage node survives the swap, so the filled exit effect still holds
         // the incoming document at zero opacity. It is released inside
@@ -306,6 +314,10 @@ export function installSwupRouter(): Swup {
         }
         html.dataset.staluxRoute = getRouteKind(context.to.pathname);
         visibleHistoryIndex = Number(window.history.state?.index ?? visibleHistoryIndex);
+        // Kept shells whose contents belong to the page (the article sidebars'
+        // lists) take their children from the incoming document now, before any
+        // page module mounts, so nothing needs to re-render or re-measure later.
+        hydrateShells(next);
         dispatchNavigation("astro:after-swap", context, next);
         // The entry cue has to own the first painted frame of the new document.
         // content:scroll is an await and a rAF away, and running the incoming
@@ -419,8 +431,11 @@ export function installSwupRouter(): Swup {
         }
     });
     swup.hooks.on("cache:set", () => {
-        while (swup.cache.size > 32)
-            swup.cache.delete(swup.cache.all.keys().next().value as string);
+        while (swup.cache.size > 32) {
+            const oldest = swup.cache.all.keys().next();
+            if (oldest.done) break;
+            swup.cache.delete(oldest.value);
+        }
     });
     // Parsed DOM, not window.load: slow third-party resources cannot hold the
     // first page's interactions hostage. Page-runtime dedupes the early mount.

package/src/scripts/waline.ts

@@ -10,7 +10,7 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 registerPageLifecycle("waline", () => {
     const container = document.querySelector<HTMLElement>("#waline-container");
     const commentElement = document.querySelector<HTMLElement>("#waline-comment");
-    if (!container || !commentElement) return;
+    if (!(container && commentElement)) return;
 
     let decoded: unknown;
     try {