@xingwangzhe/stalux 1.44.0 → 1.45.1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@xingwangzhe/stalux",
-    "version": "1.44.0",
+    "version": "1.45.1",
     "description": "A powerful, modern Astro blog theme — use as template or install as plugin",
     "keywords": [
         "astro",

package/src/components/stalux/archives/archivesList.astro

@@ -77,9 +77,12 @@ const archiveYears = [...archivesByYearMonth.entries()]
                                     { length: Math.ceil(monthPosts.length / 12) },
                                     (_, index) => monthPosts.slice(index * 12, (index + 1) * 12),
                                 ).map((group) => (
-                                    <ul class="stalux-archive-post-list">
+                                    <ul class="stalux-archive-post-list" data-stalux-reveal>
                                         {group.map((post) => (
-                                            <li class="stalux-archive-post-item">
+                                            <li
+                                                class="stalux-archive-post-item"
+                                                data-stalux-reveal-item
+                                            >
                                                 <time
                                                     class="stalux-archive-post-date"
                                                     datetime={toMachineDateTime(
@@ -127,7 +130,10 @@ const archiveYears = [...archivesByYearMonth.entries()]
 
 <script>
 import { mountArchiveDescriptions } from "../../../scripts/archive-descriptions";
+import { mountListReveal } from "../../../scripts/list-reveal";
 import { registerPageLifecycle } from "../../../scripts/page-runtime";
 
 registerPageLifecycle("archive-descriptions", mountArchiveDescriptions);
+// The archive cascade ships only with the archive markup it animates.
+registerPageLifecycle("list-reveal", mountListReveal);
 </script>

package/src/components/stalux/posts/PostTaxonomy.astro

@@ -46,12 +46,13 @@ const cfg = {
 <nav class="stalux-post-taxonomy-container" aria-label={title ?? cfg.heading}>
     <h3 class="stalux-post-taxonomy-title">{title ?? cfg.heading}</h3>
     {items.length > 0 ? (
-        <div class={cfg.listClass}>
+        <div class={cfg.listClass} data-stalux-reveal>
             {items.map((item) => (
                 <a
                     href={`${cfg.prefix}${item}/`}
                     class={`${cfg.itemClass} a-none`}
                     data-astro-prefetch
+                    data-stalux-reveal-item
                 >
                     {item}
                 </a>

package/src/components/stalux/posts/postLeft.astro

@@ -5,7 +5,7 @@ import PostAuthor from "@components/stalux/posts/postAuthor.astro";
 import RandomPost from "@components/stalux/posts/randomPost.astro";
 ---
 
-<aside class="stalux-sidebar">
+<aside class="stalux-sidebar" data-swup-persist="post-sidebar-left">
     <div class="stalux-sidebar-container" data-stalux-module="sidebar">
         <PostAuthor />
     </div>

package/src/components/stalux/posts/postRight.astro

@@ -15,7 +15,11 @@ const { headings = [], tags = [], categories = [] } = Astro.props;
 ---
 
 <aside class="stalux-sidebar-right" data-stalux-scroll-pane>
-    <div class="stalux-sidebar-container" data-stalux-module="sidebar">
+    <div
+        class="stalux-sidebar-container"
+        data-stalux-module="sidebar"
+        data-swup-persist="post-sidebar-clock"
+    >
         <PostDate />
         <Weather />
     </div>

package/src/components/stalux/posts/postToc.astro

@@ -32,9 +32,9 @@ const tocItems = headings
 <nav data-toc-active-class="stalux-toc-active" aria-label={t("taxonomy.toc")}>
     <h3 class="stalux-toc-title">{title}</h3>
     {tocItems.length > 0 ? (
-        <ul class="stalux-toc-list">
+        <ul class="stalux-toc-list" data-stalux-reveal>
             {tocItems.map((heading) => (
-                <li>
+                <li data-stalux-reveal-item>
                     <a
                         class={`stalux-toc-item ${({ 1: "stalux-toc-depth-1", 2: "stalux-toc-depth-2", 3: "stalux-toc-depth-3", 4: "stalux-toc-depth-4", 5: "stalux-toc-depth-5", 6: "stalux-toc-depth-6" } as Record<number, string>)[heading.depth] || ""} a-none`}
                         href={`#${heading.slug}`}

package/src/layouts/PostLayout.astro

@@ -92,3 +92,11 @@ const walineConfig = walineSection?.serverURL
         <PostRight headings={headings} tags={tags} categories={categories} />
     </div>
 </div>
+
+<script>
+import { mountListReveal } from "../scripts/list-reveal";
+import { registerPageLifecycle } from "../scripts/page-runtime";
+
+// Article sidebars cascade their lists; the script ships with article pages only.
+registerPageLifecycle("list-reveal", mountListReveal);
+</script>

package/src/scripts/list-reveal.ts

@@ -0,0 +1,81 @@
+const CONTAINER = "[data-stalux-reveal]";
+const ITEM = ":scope > [data-stalux-reveal-item]";
+// A cascade is only ever a bounded group cue: never one observer per row, and
+// never a queue long enough to keep the reader waiting for the last item.
+const MAX_CONTAINERS = 48;
+const MAX_ITEMS = 16;
+const STAGGER_MS = 22;
+const MAX_DELAY_MS = 176;
+const DURATION_MS = 240;
+
+/**
+ * Lists cascade in once, when their group becomes visible.
+ *
+ * Text is authored fully visible; the effect only dims a group that is about to
+ * be read. Rows outside the group cap, restored history entries, reduced
+ * motion, persisted shells and hidden documents are left untouched.
+ */
+export function mountListReveal(): (() => void) | undefined {
+    if (typeof IntersectionObserver !== "function") return;
+    const preference = window.matchMedia("(prefers-reduced-motion: reduce)");
+    if (preference.matches || document.hidden) return;
+    // Returning to a history entry restores what the reader already saw.
+    if (document.documentElement.dataset.staluxVtPreset === "restore") return;
+    const containers = [...document.querySelectorAll<HTMLElement>(CONTAINER)]
+        .filter((element) => !element.closest("[data-swup-persist]"))
+        .slice(0, MAX_CONTAINERS);
+    if (!containers.length) return;
+
+    const active = new Set<Animation>();
+    const cancel = () => {
+        for (const animation of active) animation.cancel();
+        active.clear();
+    };
+    const reveal = (container: HTMLElement) => {
+        if (document.hidden || preference.matches) return;
+        const items = [...container.querySelectorAll<HTMLElement>(ITEM)].slice(0, MAX_ITEMS);
+        for (const [index, item] of items.entries()) {
+            if (typeof item.animate !== "function") continue;
+            try {
+                const animation = item.animate(
+                    {
+                        opacity: [0.6, 1],
+                        transform: ["translateY(8px)", "translateY(0)"],
+                    },
+                    {
+                        duration: DURATION_MS,
+                        delay: Math.min(index * STAGGER_MS, MAX_DELAY_MS),
+                        easing: "cubic-bezier(0.2, 0.7, 0.2, 1)",
+                        // Dimmed during the stagger delay instead of popping in.
+                        fill: "backwards",
+                    },
+                );
+                active.add(animation);
+                const release = () => {
+                    active.delete(animation);
+                    animation.cancel();
+                };
+                void animation.finished.then(release, release);
+            } catch {
+                /* An unsupported effect leaves the authored visible list. */
+            }
+        }
+    };
+    const observer = new IntersectionObserver(
+        (entries) => {
+            for (const entry of entries) {
+                if (!entry.isIntersecting) continue;
+                observer.unobserve(entry.target);
+                reveal(entry.target as HTMLElement);
+            }
+        },
+        { threshold: 0.05 },
+    );
+    for (const container of containers) observer.observe(container);
+    preference.addEventListener("change", cancel);
+    return () => {
+        observer.disconnect();
+        preference.removeEventListener("change", cancel);
+        cancel();
+    };
+}

package/src/scripts/module-motion.ts

@@ -32,6 +32,9 @@ export function mountModuleMotion(): (() => void) | undefined {
                     motionPreference.matches ||
                     document.documentElement.classList.contains("is-changing") ||
                     document.documentElement.dataset.staluxVtPreset ||
+                    // A persisted node kept its identity across the visit; it was
+                    // never rebuilt, so re-entering it would be a second cue.
+                    element.closest("[data-swup-persist]") ||
                     element.closest("[data-stalux-motion-region]") ||
                     entry.boundingClientRect.height > Math.min(420, window.innerHeight * 0.6) ||
                     typeof element.animate !== "function"

package/src/scripts/random-posts.ts

@@ -50,6 +50,9 @@ export function mountRandomPosts(): (() => void) | undefined {
     };
     const reveal = () => {
         if (reducedMotion.matches || document.hidden || typeof list.animate !== "function") return;
+        // A persisted sidebar keeps its node across visits; fading it again would
+        // read as the fixed shell blinking, which is exactly what it must not do.
+        if (container.closest("[data-swup-persist]")) return;
         try {
             // Real titles can wrap the sidebar beyond the same bounded-region
             // budget used for route effects. Keep that result immediately readable.

package/src/scripts/route-motion.ts

@@ -12,10 +12,12 @@ export interface RouteMotionEvent {
 
 export interface RouteMotionOptions {
     skip?: boolean;
-    /** Use a bounded introductory region around the marked heading. */
+    /** Animate the route's own content stage instead of a bounded heading area. */
     content?: boolean;
     preset?: RouteMotionPreset;
     browserMotion?: boolean;
+    /** Releases the outgoing fill effect inside the entry cue's sync block. */
+    releaseOutgoing?: () => void;
 }
 
 export interface RouteMotion {
@@ -48,13 +50,102 @@ const headingMotions: Record<Exclude<RouteMotionPreset, "none">, HeadingMotion>
     error: { opacity: 0.9, duration: 80 },
 };
 
+const MAIN = "main[data-stalux-route]";
+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]";
+// 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. */
+    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.
+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 },
+    // Entering a different article without a reading-direction trigger.
+    article: { opacity: 0, distance: 40, axis: "y", duration: 300 },
+    // 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 },
+    // Leaving an article for the archive or a taxonomy index.
+    up: { opacity: 0, distance: -44, axis: "y", duration: 300 },
+    // Moving between two taxonomy detail pages.
+    taxonomy: { opacity: 0, distance: 36, axis: "y", duration: 280 },
+    // About / links / words: single-panel pages.
+    panel: { opacity: 0, distance: 44, axis: "y", duration: 300 },
+    glide: { opacity: 0, distance: 40, axis: "y", duration: 280 },
+    // 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 },
+};
+
+const laidOut = (element: HTMLElement): boolean => {
+    const rect = element.getBoundingClientRect();
+    return rect.width > 0 && rect.height > 0;
+};
+
+/**
+ * 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.
+ */
+export function getRouteStage(): HTMLElement | null {
+    const main = document.querySelector<HTMLElement>(MAIN);
+    if (!main?.isConnected) return null;
+    const candidates: HTMLElement[] = [];
+    const article = main.querySelector<HTMLElement>(ARTICLE);
+    if (article) candidates.push(article);
+    for (const element of main.querySelectorAll<HTMLElement>(CONTENT)) candidates.push(element);
+
+    let stage: HTMLElement | null = null;
+    let area = 0;
+    for (const element of candidates) {
+        // A stage inside a persisted subtree is the shell itself.
+        if (!element.isConnected || element.closest(PERSIST)) continue;
+        const rect = element.getBoundingClientRect();
+        if (rect.width <= 0 || rect.height <= 0) continue;
+        const current = rect.width * rect.height;
+        if (current > area) {
+            area = current;
+            stage = element;
+        }
+    }
+    if (stage) return stage;
+    if (main.querySelector(PERSIST)) return null;
+    return laidOut(main) ? main : null;
+}
+
+/** Offset applied to the outgoing document, continuing the entry direction. */
+export function getStageExit(preset: RouteMotionPreset): StageMotion | null {
+    if (preset === "none") return null;
+    const motion = stageMotions[preset];
+    // Entering from below means leaving upward, so both halves read as one
+    // continuous flow instead of an enter/leave bounce.
+    return { ...motion, distance: -Math.round(motion.distance * 0.72) };
+}
+
 const motions = new WeakMap<object, RouteMotion>();
 const settle = (promise?: PromiseLike<unknown>): Promise<void> =>
     Promise.resolve(promise).then(
         () => undefined,
         () => undefined,
     );
-
 function completion() {
     let resolve = () => {};
     const promise = new Promise<void>((done) => {
@@ -149,41 +240,80 @@ export function prepareRouteMotion(event: RouteMotionEvent): RouteMotion {
         start(heading, options) {
             if (started) return;
             started = true;
+            // Every exit path must release the outgoing fill, or the swapped
+            // document stays transparent behind a cancelled cue.
+            const release = options?.releaseOutgoing;
             try {
                 const preset = options?.preset ?? "glide";
                 const mobile = window.matchMedia?.("(max-width: 768px)").matches;
-                const target = getRouteMotionTarget(heading);
                 if (
-                    !target ||
-                    preset === "none" ||
-                    (options?.content && preset === "restore") ||
                     options?.skip ||
                     options?.browserMotion ||
+                    preset === "none" ||
+                    (options?.content && preset === "restore") ||
+                    // History never replays an entry on a phone: the reader is
+                    // returning to a position, not arriving somewhere new.
+                    (mobile && preset === "restore") ||
                     document.hidden ||
-                    window.matchMedia?.("(prefers-reduced-motion: reduce)").matches ||
-                    typeof target.animate !== "function" ||
-                    (mobile && preset === "restore")
+                    window.matchMedia?.("(prefers-reduced-motion: reduce)").matches
                 ) {
+                    release?.();
+                    animationDone.resolve();
+                    return;
+                }
+                const stage = options?.content ? getRouteStage() : null;
+                const target = stage ?? getRouteMotionTarget(heading);
+                if (!target || typeof target.animate !== "function") {
+                    release?.();
                     animationDone.resolve();
                     return;
                 }
-                const spec = options?.content ? regionMotions[preset] : headingMotions[preset];
-                const keyframes: PropertyIndexedKeyframes = { opacity: [spec.opacity, 1] };
-                // Phones use a pure fade. Explicit previous/next alone imply a
-                // lateral reading direction; history never replays the entry.
-                if (!mobile && (spec.x || spec.y)) {
-                    keyframes.transform = [
-                        `translate3d(${spec.x ?? 0}px, ${spec.y ?? 0}px, 0)`,
-                        "translate3d(0px, 0px, 0)",
-                    ];
+                // Cancelling the outgoing fill and starting the entry cue must
+                // share one synchronous block. Split across frames, the reader
+                // sees the new document at full opacity for a frame first.
+                release?.();
+                if (stage) {
+                    const spec = stageMotions[preset];
+                    // Phones get a shorter throw; the same offset reads as a much
+                    // larger move on a narrow viewport.
+                    const distance = mobile ? Math.round(spec.distance * 0.6) : spec.distance;
+                    const from =
+                        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",
+                        },
+                    );
+                } else {
+                    const spec = options?.content ? regionMotions[preset] : headingMotions[preset];
+                    const keyframes: PropertyIndexedKeyframes = { opacity: [spec.opacity, 1] };
+                    // Phones use a pure fade. Explicit previous/next alone imply a
+                    // lateral reading direction; history never replays the entry.
+                    if (!mobile && (spec.x || spec.y)) {
+                        keyframes.transform = [
+                            `translate3d(${spec.x ?? 0}px, ${spec.y ?? 0}px, 0)`,
+                            "translate3d(0px, 0px, 0)",
+                        ];
+                    }
+                    animation = target.animate(keyframes, {
+                        duration: mobile ? (options?.content ? 120 : 80) : spec.duration,
+                        easing: "cubic-bezier(0.2, 0.7, 0.2, 1)",
+                        fill: "both",
+                    });
                 }
-                animation = target.animate(keyframes, {
-                    duration: mobile ? (options?.content ? 120 : 80) : spec.duration,
-                    easing: "cubic-bezier(0.2, 0.7, 0.2, 1)",
-                    fill: "both",
-                });
                 void animation.finished.then(clearAnimation, clearAnimation);
             } catch {
+                release?.();
                 clearAnimation();
             } finally {
                 installed.resolve();

package/src/scripts/route-out.ts

@@ -1,37 +1,62 @@
-import { getRouteMotionTarget } from "./route-motion";
+import type { RouteMotionPreset } from "../utils/route-motion-policy";
+import { getRouteStage, getStageExit } from "./route-motion";
 
-/** Fade the old content only after destination assets are ready. */
+/**
+ * Fade and shift the current content stage out, continuing the entry direction
+ * so the two halves read as one movement instead of a flash.
+ *
+ * The returned release keeps the fill effect until the entry cue takes over.
+ * Cancelling here would expose the freshly swapped document at full opacity for
+ * a frame before it animates in — the exact flash this replaces.
+ */
 export async function animateRouteOut(
-    element: HTMLElement | null,
+    preset: RouteMotionPreset,
     signal: AbortSignal,
 ): Promise<() => void> {
+    const spec = getStageExit(preset);
+    const stage = spec ? getRouteStage() : null;
     if (
-        !element ||
+        !spec ||
+        !stage ||
         signal.aborted ||
         document.hidden ||
+        typeof stage.animate !== "function" ||
         window.matchMedia("(prefers-reduced-motion: reduce)").matches
     )
         return () => {};
-    const target = getRouteMotionTarget(element);
-    if (!target || typeof target.animate !== "function") return () => {};
-    let animation: Animation | undefined;
-    const cancel = () => animation?.cancel();
     const mobile = window.matchMedia("(max-width: 768px)").matches;
+    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)`;
+    let animation: Animation | undefined;
+    const cancel = () => {
+        const active = animation;
+        animation = undefined;
+        try {
+            active?.cancel();
+        } catch {
+            /* An already detached effect cannot be released further. */
+        }
+    };
     try {
-        animation = target.animate(
-            mobile
-                ? { opacity: [1, 0.82] }
-                : { opacity: [1, 0.82], transform: ["translateY(0)", "translateY(-4px)"] },
-            { duration: 80, easing: "cubic-bezier(0.4, 0, 1, 1)", fill: "forwards" },
+        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",
+            },
         );
         signal.addEventListener("abort", cancel, { once: true });
         await animation.finished;
-        // Keep the bounded outgoing cue until swap; the body stays readable.
-        // Swup detaches this node; no persistent shell is animated.
+        // The stage node survives the swap, so this filled effect is what holds
+        // the incoming document hidden until its own cue starts.
     } catch {
         /* Cancellation and unsupported animation must not block a visit. */
-    } finally {
-        if (signal.aborted) cancel();
     }
     return () => {
         signal.removeEventListener("abort", cancel);

package/src/scripts/smooth-scroll.ts

@@ -4,6 +4,93 @@ export function cancelPageScroll(): void {
     stopActive?.();
 }
 
+export interface PageGlide {
+    /** Settles when the page reaches the top, is interrupted, or is canceled. */
+    promise: Promise<void>;
+    /** Stop immediately at the current position without further frames. */
+    cancel: () => void;
+}
+
+/** 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;
+
+/**
+ * Walk the current document back to the top before the container is replaced.
+ * Swup's own between-page reset is instant; animating it after the swap would
+ * make the new article start wherever the old page happened to be scrolled.
+ * Doing it on the outgoing document keeps the incoming page at its real top.
+ */
+export function glideToTop(): PageGlide {
+    const element = document.scrollingElement ?? document.documentElement;
+    const startTop = Math.max(0, element.scrollTop || window.scrollY || 0);
+    const startLeft = Math.max(0, element.scrollLeft || window.scrollX || 0);
+    let resolve = () => {};
+    const promise = new Promise<void>((done) => {
+        resolve = done;
+    });
+    if (
+        startTop < 1 ||
+        typeof requestAnimationFrame !== "function" ||
+        window.matchMedia?.("(prefers-reduced-motion: reduce)").matches ||
+        document.hidden
+    ) {
+        resolve();
+        return { promise, cancel: resolve };
+    }
+
+    // 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);
+    let frame: number | undefined;
+    let settled = false;
+    const release = () => {
+        window.removeEventListener("wheel", finish);
+        window.removeEventListener("touchstart", finish);
+        window.removeEventListener("keydown", finish);
+        clearTimeout(safety);
+        if (stopActive === finish) stopActive = undefined;
+    };
+    const finish = () => {
+        if (settled) return;
+        settled = true;
+        if (frame !== undefined) cancelAnimationFrame(frame);
+        release();
+        resolve();
+    };
+    // A wheel/touch/key press means the reader reclaimed the scroll; stop at
+    // the frame already rendered instead of fighting the gesture.
+    const safety = setTimeout(finish, GLIDE_SAFETY_MS);
+    stopActive = finish;
+    window.addEventListener("wheel", finish, { passive: true, once: true });
+    window.addEventListener("touchstart", finish, { passive: true, once: true });
+    window.addEventListener("keydown", finish, { once: true });
+
+    const begin = performance.now();
+    let frames = 0;
+    const step = (now: number) => {
+        if (settled) return;
+        // Frame ceiling: a host that invokes rAF synchronously must not turn
+        // this loop into unbounded recursion. Real browsers reach the safety
+        // timeout first; twenty frames cover the 320ms budget at 60Hz.
+        if (++frames > 240) {
+            finish();
+            return;
+        }
+        const progress = Math.min(1, Math.max(0, (now - begin) / duration));
+        // Quadratic ease-out: reads as a scroll rather than a snap, and still
+        // spends most of its time near the top where the article begins.
+        const remaining = (1 - progress) ** 2;
+        element.scrollTop = Math.round(startTop * remaining);
+        element.scrollLeft = Math.round(startLeft * remaining);
+        if (progress < 1) frame = requestAnimationFrame(step);
+        else finish();
+    };
+    frame = requestAnimationFrame(step);
+    return { promise, cancel: finish };
+}
+
 /** Native scrolling with bounded completion and explicit listener cleanup. */
 export function scrollPage(
     element: Element,

package/src/scripts/swup-router.ts

@@ -12,7 +12,7 @@ import "./navigation-client";
 import { prepareNavigationScripts } from "./navigation-scripts";
 import { prepareRouteMotion, type RouteMotion } from "./route-motion";
 import { animateRouteOut } from "./route-out";
-import { cancelPageScroll, scrollPage } from "./smooth-scroll";
+import { cancelPageScroll, glideToTop, type PageGlide, scrollPage } from "./smooth-scroll";
 
 interface NavigationContext {
     controller: AbortController;
@@ -27,6 +27,7 @@ interface NavigationContext {
     executeScripts?: (signal?: AbortSignal) => Promise<void>;
     scriptsReady?: Promise<void>;
     obsoleteStyles: Element[];
+    glide?: PageGlide;
     releaseOutgoing?: () => void;
 }
 
@@ -59,6 +60,16 @@ function clearMotionState(): void {
         delete document.documentElement.dataset[key];
 }
 
+/** The exit fill is released by whichever path finishes first; never twice. */
+function once(effect: () => void): () => void {
+    let done = false;
+    return () => {
+        if (done) return;
+        done = true;
+        effect();
+    };
+}
+
 /** Astro renders pages; Swup alone owns their client navigation and animation. */
 export function installSwupRouter(): Swup {
     if (window.swup) return window.swup;
@@ -132,6 +143,7 @@ export function installSwupRouter(): Swup {
                                     content: true,
                                     browserMotion: context.browserMotion,
                                     skip: context.controller.signal.aborted,
+                                    releaseOutgoing: context.releaseOutgoing,
                                 },
                             );
                             await context.motion.finished;
@@ -251,12 +263,14 @@ export function installSwupRouter(): Swup {
         const next = visit.to.document;
         if (!context || !next || !replace) throw new Error("Missing Swup document");
         if (context.controller.signal.aborted) return;
-        // Keep the old page readable until HTML, styles and fonts are ready.
+        // Two cues overlap on the outgoing document: the content stage leaving,
+        // and the page walking back to the top. Persisted sidebars, the header
+        // and the frame are never part of either one.
         if (context.navigationType !== "traverse" && context.preset !== "none") {
-            context.releaseOutgoing = await animateRouteOut(
-                document.querySelector<HTMLElement>("[data-stalux-motion-focus]"),
-                context.controller.signal,
-            );
+            const outgoing = animateRouteOut(context.preset, context.controller.signal);
+            if (!context.to.hash) context.glide = glideToTop();
+            await context.glide?.promise;
+            context.releaseOutgoing = once(await outgoing);
             if (context.controller.signal.aborted || visit !== swup.visit) {
                 context.releaseOutgoing();
                 return;
@@ -270,7 +284,10 @@ export function installSwupRouter(): Swup {
         context.motion = prepareRouteMotion(dispatchNavigation("astro:before-swap", context, next));
         if (context.controller.signal.aborted) return;
         await replace(visit, args);
-        context.releaseOutgoing?.();
+        // The stage node survives the swap, so the filled exit effect still holds
+        // the incoming document at zero opacity. It is released inside
+        // motion.start, in the same synchronous block as the entry cue: releasing
+        // it here would paint the new document fully visible for one frame.
         if (context.controller.signal.aborted) return;
         for (const element of context.obsoleteStyles) element.remove();
         const incomingStyles = [...next.head.querySelectorAll("style,link[rel=stylesheet]")];
@@ -333,6 +350,7 @@ export function installSwupRouter(): Swup {
             content: true,
             skip: !visit.animation.animate || context.controller.signal.aborted,
             browserMotion: context.browserMotion,
+            releaseOutgoing: context.releaseOutgoing,
         });
     }
 
@@ -342,13 +360,17 @@ export function installSwupRouter(): Swup {
         await context.scriptsReady;
         if (context.controller.signal.aborted) return;
         dispatchNavigation("astro:page-load", context);
-        if (!visit.animation.animate) context.motion?.start(null, { skip: true });
+        if (!visit.animation.animate)
+            context.motion?.start(null, { skip: true, releaseOutgoing: context.releaseOutgoing });
     });
     swup.hooks.replace("link:self", () => undefined);
 
     const cancel = (visit: Visit) => {
         const context = contexts.get(visit);
         context?.controller.abort();
+        context?.glide?.cancel();
+        // An aborted visit keeps no exit fill: without this the stage would stay
+        // transparent until the next successful navigation.
         context?.releaseOutgoing?.();
         context?.motion?.cancel();
         if (context === activeContext) {
@@ -361,6 +383,7 @@ export function installSwupRouter(): Swup {
     swup.hooks.on("visit:fail", cancel);
     swup.hooks.on("visit:end", (visit) => {
         const context = contexts.get(visit);
+        context?.glide?.cancel();
         context?.releaseOutgoing?.();
         context?.motion?.start(null, { skip: true });
         if (activeContext === context) {

package/src/styles/generated-words.css

@@ -1,3 +1,3 @@
 @layer theme, base, components, utilities;
-@layer components{.stalux-word-card{transition:border-color var(--transition-normal), box-shadow var(--transition-normal);box-sizing:border-box;border-radius:var(--radius-lg,12px);background:var(--surface-glass);width:100%;min-width:0;box-shadow:var(--card-box-shadow);flex-direction:column;gap:1.5rem;padding:2rem 2rem 1.25rem;display:flex;position:relative}.stalux-word-date{font-variant-numeric:tabular-nums;color:var(--white-50p)}.stalux-word-footer{border-top:1px solid var(--white-10p);color:var(--white-70p);flex-wrap:wrap;justify-content:space-between;align-items:center;gap:.75rem;margin-top:auto;padding-top:1rem;font-size:.85rem;display:flex}.stalux-word-source-link{text-decoration-color:var(--accent-50p);text-underline-offset:.15em;transition:color var(--transition-fast);color:var(--accent-90p);text-decoration-line:underline}.stalux-word-body{min-width:0;color:var(--white-90p);font-size:1.1rem;line-height:1.9;position:relative}.stalux-word-list-list{flex-direction:column;align-items:center;gap:1.5rem;margin:2rem auto;padding:0;list-style-type:none;display:flex}.stalux-word-list-item{width:100%;max-width:900px;display:flex}.stalux-word-source-meta{flex-wrap:wrap;justify-content:flex-end;align-items:center;gap:.5rem;display:flex}.stalux-word-source-date{color:var(--white-70p)}.stalux-word-source-text{color:var(--white-90p)}.stalux-word-card{border-left:2px solid var(--accent-50p);background:linear-gradient(135deg, rgb(var(--stalux-accent-rgb) / .06), transparent 55%), #121418eb;overflow-wrap:anywhere;scroll-margin-top:6rem}.stalux-word-mark{color:var(--accent-60p);opacity:.45;pointer-events:none;position:absolute;top:1.5rem;right:1.5rem}.stalux-word-body{padding-right:2.5rem}.stalux-word-footer{backdrop-filter:none;text-align:left;background:0 0;padding:.75rem 0 0}.stalux-word-source-meta{text-align:right}.stalux-word-source-link{align-items:center;min-height:44px;display:inline-flex}.stalux-word-permalink{min-height:44px;color:var(--white-70p);font-variant-numeric:tabular-nums;align-items:center;display:inline-flex}.stalux-word-permalink:focus-visible,.stalux-word-source-link:focus-visible{outline:2px solid var(--stalux-accent-color);outline-offset:4px;border-radius:4px}.stalux-word-source-meta{min-width:0;margin-left:auto}.stalux-word-body>:first-child{margin-top:0}.stalux-word-body>:last-child{margin-bottom:0}.stalux-word-body .expressive-code{max-width:100%;overflow-x:auto}.stalux-word-card:target,.stalux-word-card[data-glow]{border-color:var(--accent-90p)}.stalux-word-body h1,.stalux-word-body h2,.stalux-word-body h3,.stalux-word-body h4,.stalux-word-body h5,.stalux-word-body h6{margin:.5rem 0;font-size:1.1em}.stalux-word-body p{margin:.5rem 0}.stalux-word-body blockquote{border-left:3px solid var(--accent-60p);background:var(--white-05p);margin:.5rem 0;padding:.6rem 1rem}.stalux-word-body pre{white-space:pre-wrap;overflow-wrap:anywhere;overflow-x:visible}.stalux-word-body code{overflow-wrap:anywhere}@media (hover:hover) and (pointer:fine){.stalux-word-card:hover{border-color:var(--accent-80p);box-shadow:var(--card-box-shadow-hover)}.stalux-word-source-link:hover{color:var(--accent-90p)}}@media (width<=768px){.stalux-word-card{padding:1.25rem}.stalux-word-list-list{gap:1rem;margin:1.5rem auto}.stalux-word-list-item{max-width:100%}}}@layer utilities,theme,base;
+@layer components{.stalux-word-card{transition:border-color var(--transition-normal), box-shadow var(--transition-normal);box-sizing:border-box;border-radius:var(--radius-lg,12px);background:var(--surface-glass);width:100%;min-width:0;box-shadow:var(--card-box-shadow);flex-direction:column;gap:1.5rem;padding:2rem 2rem 1.25rem;display:flex;position:relative}.stalux-word-date{font-variant-numeric:tabular-nums;color:var(--white-50p)}.stalux-word-footer{border-top:1px solid var(--white-10p);color:var(--white-70p);flex-wrap:wrap;justify-content:space-between;align-items:center;gap:.75rem;margin-top:auto;padding-top:1rem;font-size:.85rem;display:flex}.stalux-word-source-link{text-decoration-color:var(--accent-50p);text-underline-offset:.15em;transition:color var(--transition-fast);color:var(--accent-90p);text-decoration-line:underline}.stalux-word-body{min-width:0;color:var(--white-90p);font-size:1.1rem;line-height:1.9;position:relative}.stalux-word-list-list{flex-direction:column;align-items:center;gap:1.5rem;width:100%;max-width:900px;margin:2rem auto;padding:0;list-style-type:none;display:flex}.stalux-word-list-item{width:100%;min-width:0;display:flex}.stalux-word-source-meta{flex-wrap:wrap;justify-content:flex-end;align-items:center;gap:.5rem;display:flex}.stalux-word-source-date{color:var(--white-70p)}.stalux-word-source-text{color:var(--white-90p)}.stalux-word-card{border-left:2px solid var(--accent-50p);background:rgb(var(--stalux-accent-rgb) / .045);backdrop-filter:blur(3px);overflow-wrap:anywhere;scroll-margin-top:6rem}.stalux-word-mark{color:var(--accent-60p);opacity:.45;pointer-events:none;position:absolute;top:1.5rem;right:1.5rem}.stalux-word-body{padding-right:2.5rem}.stalux-word-footer{backdrop-filter:none;text-align:left;background:0 0;padding:.75rem 0 0}.stalux-word-source-meta{text-align:right}.stalux-word-source-link{align-items:center;min-height:44px;display:inline-flex}.stalux-word-permalink{min-height:44px;color:var(--white-70p);font-variant-numeric:tabular-nums;align-items:center;display:inline-flex}.stalux-word-permalink:focus-visible,.stalux-word-source-link:focus-visible{outline:2px solid var(--stalux-accent-color);outline-offset:4px;border-radius:4px}.stalux-word-source-meta{min-width:0;margin-left:auto}.stalux-word-body>:first-child{margin-top:0}.stalux-word-body>:last-child{margin-bottom:0}.stalux-word-body .expressive-code{max-width:100%;overflow-x:auto}.stalux-word-card:target,.stalux-word-card[data-glow]{border-color:var(--accent-90p)}.stalux-word-body h1,.stalux-word-body h2,.stalux-word-body h3,.stalux-word-body h4,.stalux-word-body h5,.stalux-word-body h6{margin:.5rem 0;font-size:1.1em}.stalux-word-body p{margin:.5rem 0}.stalux-word-body blockquote{border-left:3px solid var(--accent-60p);background:var(--white-05p);margin:.5rem 0;padding:.6rem 1rem}.stalux-word-body pre{white-space:pre-wrap;overflow-wrap:anywhere;overflow-x:visible}.stalux-word-body code{overflow-wrap:anywhere}@media (hover:hover) and (pointer:fine){.stalux-word-card:hover{border-color:var(--accent-80p);box-shadow:var(--card-box-shadow-hover)}.stalux-word-source-link:hover{color:var(--accent-90p)}}@media (width<=768px){.stalux-word-card{padding:1.25rem}.stalux-word-list-list{gap:1rem;margin:1.5rem auto}.stalux-word-list-item{max-width:100%}}}@layer utilities,theme,base;
 /*$vite$:1*/