@xingwangzhe/stalux 1.45.0 → 1.46.0

package/package.json

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

package/src/components/stalux/categories/categoriesList.astro

@@ -7,9 +7,9 @@ import { getCategoryCountList } from "@utils/collections-stats";
 const categoryList = await getCategoryCountList(Astro.logger);
 ---
 
-<ul class="stalux-categories" data-stalux-motion-content>
+<ul class="stalux-categories" data-stalux-motion-content data-stalux-reveal>
     {categoryList.map((category) => (
-        <li>
+        <li data-stalux-reveal-item>
             <CategoriesCard category={category} />
         </li>
     ))}

package/src/components/stalux/links/linkList.astro

@@ -10,9 +10,9 @@ const linksConfig = getLinksData(configEntries);
 const links = linksConfig?.sites ?? [];
 ---
 
-<ul class="stalux-links" data-stalux-motion-content>
+<ul class="stalux-links" data-stalux-motion-content data-stalux-reveal>
     {links.map((link) => (
-        <li class="stalux-link-list-item">
+        <li class="stalux-link-list-item" data-stalux-reveal-item>
             <LinkCard link={link} />
         </li>
     ))}

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

@@ -40,6 +40,7 @@ const description = post.data.desc || "";
                         fetchpriority={priority ? "high" : "auto"}
                         width="640"
                         height="360"
+                        data-stalux-cover
                     />
                 </div>
             </a>

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

@@ -12,9 +12,9 @@ const posts = props.posts ?? (await getCollection("posts", ({ data }) => !data.d
 ---
 
 <div data-stalux="postlist" class="stalux-post-list-container" data-stalux-motion-content>
-    <ul class="post-list">
+    <ul class="post-list" data-stalux-reveal>
         {posts.map((post, index) => (
-            <li>
+            <li data-stalux-reveal-item>
                 <PostCard post={post} priority={index === 0} />
             </li>
         ))}

package/src/components/stalux/tags/tagsCloud.astro

@@ -25,7 +25,7 @@ const tagLinks = tagList.map((t) => ({
 <div class="stalux-cloud-cards" id="tags-cards" data-stalux-tag-cards data-stalux-motion-content>
     {tagList.length > 0 ? (
         tagGroups.map((group) => (
-            <div class="stalux-cloud-tag-group">
+            <div class="stalux-cloud-tag-group" data-stalux-reveal>
                 {group.map(({ name, count }) => (
                     <a
                         href={`/tags/${name}/`}
@@ -33,6 +33,7 @@ const tagLinks = tagList.map((t) => ({
                         data-stalux-card
                         data-stalux-tag-card
                         data-stalux-control="tag-card"
+                        data-stalux-reveal-item
                         data-count={count}
                         data-astro-prefetch
                     >

package/src/components/stalux/words/wordList.astro

@@ -19,10 +19,10 @@ const sorted = [...entries].sort((a, b) => {
 });
 ---
 
-<ul class="stalux-word-list-list" data-stalux-motion-content>
+<ul class="stalux-word-list-list" data-stalux-motion-content data-stalux-reveal>
     {sorted.map((entry) => {
         return (
-            <li class="stalux-word-list-item">
+            <li class="stalux-word-list-item" data-stalux-reveal-item>
                 <WordCard entry={entry} timezone={timezone} />
             </li>
         );

package/src/index.ts

@@ -49,6 +49,7 @@ import { createInjectedRoutes } from "./internal/injected-routes";
 import { markdownPropagationPlugin } from "./internal/markdown-propagation";
 import { containMermaidSvgs } from "./internal/offscreen-layout";
 import { createPageOutputCache } from "./internal/page-output-cache";
+import { loadCoverEncoder, restoreCoverFiles, upgradeCoverImages } from "./internal/post-cover";
 import { isPluginProject } from "./internal/project-mode";
 import { syncBackgroundSvgs, syncFontAssets } from "./internal/public-assets";
 import { createRuntimeCacheKey } from "./internal/runtime-cache-key";
@@ -121,6 +122,9 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
     };
 
     const socialCardPaths = { publicDir: "", cacheDir: "", base: "/", fontPath: "" };
+    // Content-addressed card covers, kept outside the build output so a page that
+    // is served from the page-output cache still finds its file on disk.
+    let coverCacheDir = "";
 
     let pageFontData: { fontBuffer: Buffer; outputDir: string; cacheDir: string } | undefined;
 
@@ -378,6 +382,7 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
                     base: config.base,
                     fontPath: path.join(srcDir, "assets/fonts/LXGWWenKai-Regular.ttf"),
                 });
+                coverCacheDir = fileURLToPath(new URL("stalux-post-covers/", config.cacheDir));
                 const assetsLogger = logger.fork("stalux/assets");
                 if (pageFontData) {
                     pageFontData.outputDir = path.join(
@@ -411,6 +416,10 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
                 const htmlFiles = await fs.readdir(outDir, { recursive: true });
                 const sourceDir = fileURLToPath(new URL(".", import.meta.url));
                 const resolveModule = createRequire(import.meta.url).resolve;
+                const requireModule = createRequire(import.meta.url);
+                const coverEncoder = coverCacheDir
+                    ? loadCoverEncoder(requireModule, logger)
+                    : undefined;
                 const parserEntry = resolveModule("parse5");
                 const imageSizeEntry = resolveModule("image-size");
                 const nativeEntry = resolveModule("@xingwangzhe/cjk-font-split-native");
@@ -510,6 +519,22 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
                         loadingPolicy: true,
                         dependencies,
                     });
+                    // Card covers become content-addressed WebP. The encoded files
+                    // are restored into the output at the end of every build, so a
+                    // page served from the page-output cache still resolves them.
+                    if (coverEncoder) {
+                        try {
+                            await upgradeCoverImages(images, {
+                                outDir,
+                                cacheDir: coverCacheDir,
+                                sharp: coverEncoder,
+                                dependencies,
+                                logger,
+                            });
+                        } catch (error) {
+                            logger.warn(`封面转 WebP 失败：${describeError(error)}`);
+                        }
+                    }
                     if (pageFontData) {
                         const linkedStylesheetText = readLinkedStylesheetText(
                             "",
@@ -579,6 +604,13 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
                 logger.info(
                     `HTML postprocessing ${(performance.now() - started).toFixed(1)}ms; cache ${cacheHits}/${htmlFiles.filter((entry) => entry.endsWith(".html")).length}`,
                 );
+                // Covers are emitted here rather than only while a page is
+                // post-processed: a cached page skips that pass entirely but its
+                // HTML already points at these files, so they must always exist.
+                if (coverCacheDir) {
+                    const restored = restoreCoverFiles({ outDir, cacheDir: coverCacheDir });
+                    if (restored > 0) logger.debug(`restored ${restored} card covers`);
+                }
 
                 // 后处理：Pagefind 搜索索引。启用时任何失败都必须让构建失败，
                 // 避免发布一个页面正常但搜索已损坏的产物。

package/src/internal/post-cover.ts

@@ -0,0 +1,147 @@
+import { createHash } from "node:crypto";
+import {
+    copyFileSync,
+    existsSync,
+    mkdirSync,
+    readdirSync,
+    readFileSync,
+    writeFileSync,
+} from "node:fs";
+import path from "node:path";
+import type { HtmlImage } from "./html-images";
+
+/** Public directory holding the generated covers, relative to the build output. */
+export const COVER_DIR = "stalux-covers";
+
+// Post cards render at 640x360 and are shown on 2x screens, so 1280 is the
+// widest useful source. Bigger originals only cost bytes.
+const MAX_WIDTH = 1280;
+const QUALITY = 82;
+// Bump when any encoder input above changes, so cached files are not reused.
+const RECIPE = "v1";
+
+/** Formats worth re-encoding. Vector and icon sources stay untouched. */
+const CONVERTIBLE = /\.(?:png|jpe?g|avif|tiff?|bmp)$/iu;
+
+interface SharpPipeline {
+    resize(options: Record<string, unknown>): SharpPipeline;
+    webp(options: Record<string, unknown>): SharpPipeline;
+    toBuffer(): Promise<Buffer>;
+}
+type SharpFactory = (input: Buffer) => SharpPipeline;
+
+/**
+ * `sharp` ships as a dependency of Astro itself and as a dev dependency of the
+ * theme, so it is present in practice — but it must never become a hard
+ * requirement, because a project using another image service would otherwise
+ * fail to build at all. Loaded through `require` because the Vite module runner
+ * is already closed by the time `astro:build:done` runs.
+ */
+export function loadCoverEncoder(
+    require: (id: string) => unknown,
+    logger?: { warn: (message: string) => void },
+): SharpFactory | undefined {
+    try {
+        const loaded = require("sharp") as { default?: unknown };
+        const factory = (loaded?.default ?? loaded) as unknown;
+        return typeof factory === "function" ? (factory as SharpFactory) : undefined;
+    } catch {
+        logger?.warn("封面转 WebP 已跳过：未找到 sharp，卡片继续使用原图");
+        return undefined;
+    }
+}
+
+export interface CoverContext {
+    outDir: string;
+    cacheDir: string;
+    sharp: SharpFactory;
+    /** Source files this page depends on, so editing a cover invalidates it. */
+    dependencies?: Set<string>;
+    logger?: { warn: (message: string) => void };
+}
+
+const digest = (parts: readonly (string | Buffer)[]): string => {
+    const hash = createHash("sha256");
+    for (const part of parts) hash.update(part).update("\0");
+    return hash.digest("hex");
+};
+
+/**
+ * Rewrites a marked card cover to a generated WebP.
+ *
+ * The name is content-addressed, so an unchanged cover keeps the same URL across
+ * builds and stays cacheable at the CDN, while an edited one gets a new name
+ * instead of a stale hit. The encoded file is kept in a cache directory outside
+ * the build output; `restoreCoverFiles` copies those back in at the end of every
+ * build, which is what keeps them present when a page was served from the
+ * page-output cache and this per-page pass never ran for it.
+ */
+export async function upgradeCoverImages(
+    images: readonly HtmlImage[],
+    context: CoverContext,
+): Promise<number> {
+    const root = path.resolve(context.outDir);
+    const cacheDir = path.join(context.cacheDir, RECIPE);
+    let converted = 0;
+    for (const image of images) {
+        if (!image.attributes.has("data-stalux-cover")) continue;
+        const src = image.attributes.get("src");
+        if (!src?.startsWith("/")) continue;
+        let pathname: string;
+        try {
+            pathname = decodeURIComponent(new URL(src, "https://stalux.invalid").pathname);
+        } catch {
+            continue;
+        }
+        if (!CONVERTIBLE.test(pathname)) continue;
+        const source = path.resolve(root, `.${pathname}`);
+        if (!source.startsWith(`${root}${path.sep}`)) continue;
+        if (!existsSync(source)) continue;
+        context.dependencies?.add(source);
+
+        let bytes: Buffer;
+        try {
+            bytes = readFileSync(source);
+        } catch {
+            continue;
+        }
+        const hash = digest([RECIPE, "webp", String(MAX_WIDTH), String(QUALITY), bytes]);
+        const filename = `${hash.slice(0, 16)}.webp`;
+        const cached = path.join(cacheDir, filename);
+        if (!existsSync(cached)) {
+            try {
+                const encoded = await context
+                    .sharp(bytes)
+                    .resize({ width: MAX_WIDTH, withoutEnlargement: true })
+                    .webp({ quality: QUALITY, effort: 5 })
+                    .toBuffer();
+                mkdirSync(cacheDir, { recursive: true });
+                writeFileSync(cached, encoded);
+            } catch (error) {
+                // One malformed source must not fail the page it appears on.
+                context.logger?.warn(`封面转 WebP 失败（${pathname}）：${String(error)}`);
+                continue;
+            }
+        }
+        const attribute = image.node.attrs.find((entry) => entry.name === "src");
+        if (!attribute) continue;
+        attribute.value = `/${COVER_DIR}/${filename}`;
+        converted++;
+    }
+    return converted;
+}
+
+/** Copy every cached cover into the build output so cached pages still resolve. */
+export function restoreCoverFiles(context: { outDir: string; cacheDir: string }): number {
+    const cacheDir = path.join(context.cacheDir, RECIPE);
+    if (!existsSync(cacheDir)) return 0;
+    const target = path.join(context.outDir, COVER_DIR);
+    mkdirSync(target, { recursive: true });
+    let copied = 0;
+    for (const name of readdirSync(cacheDir)) {
+        if (!name.endsWith(".webp")) continue;
+        copyFileSync(path.join(cacheDir, name), path.join(target, name));
+        copied++;
+    }
+    return copied;
+}

package/src/internal/social-card-renderer.ts

@@ -23,6 +23,23 @@ function getRenderer(fontPath: string): Promise<Renderer> {
     return rendererPromise;
 }
 
+/**
+ * Font identity for the render cache.
+ *
+ * The key used to carry the font's size and mtime, so re-installing the theme,
+ * restoring a checkout, or copying the package to a build machine changed every
+ * card's key at once and re-rendered all of them (about 8s each). Hashing the
+ * bytes keeps the key stable for identical font content and still changes when
+ * the font really is different.
+ */
+let fontDigestPromise: Promise<string> | undefined;
+function getFontDigest(fontPath: string): Promise<string> {
+    fontDigestPromise ??= readFile(fontPath).then((bytes) =>
+        createHash("sha256").update(bytes).digest("hex"),
+    );
+    return fontDigestPromise;
+}
+
 /** Resolve only assets inside the final public directory, including encoded Chinese paths. */
 export function localCoverPath(cover: string, paths: SocialCardPaths): string | undefined {
     if (!cover.startsWith("/") || cover.startsWith("//")) return undefined;
@@ -248,9 +265,11 @@ export async function renderSocialCard(
             warn(`分享封面不可用，已回退标题卡片：${data.title}`);
         }
     }
-    const font = await stat(paths.fontPath);
+    // Content-only key: identical card data + identical font + identical cover
+    // always reuses the cached render, whatever the filesystem timestamps say.
+    const fontDigest = await getFontDigest(paths.fontPath);
     const key = createHash("sha256")
-        .update(JSON.stringify(["v2", format, data, font.size, font.mtimeMs]))
+        .update(JSON.stringify(["v3", format, data, fontDigest]))
         .update(cover ?? "")
         .digest("hex");
     const cacheFile = path.join(paths.cacheDir, `${key}.${format}`);

package/src/layouts/Stalux.astro

@@ -76,6 +76,13 @@ const routeKind = getRouteKind(Astro.url.pathname);
     import "../scripts/background.ts";
     import "../scripts/module-motion.ts";
     import "../scripts/view-transitions.ts";
+    // Every page type has at least one list, so the unroll cue is registered
+    // once in the shared layout instead of per page. Page-runtime dedupes it
+    // against the article and archive components that also request it.
+    import { mountListReveal } from "../scripts/list-reveal";
+    import { registerPageLifecycle } from "../scripts/page-runtime";
+
+    registerPageLifecycle("list-reveal", mountListReveal);
     </script>
     {aiConfig?.conformance !== "disabled" && <script>import "../scripts/webmcp.ts";</script>}
     <body

package/src/pages/og/[image].[format].ts

@@ -19,12 +19,15 @@ export async function getStaticPaths() {
         )
         .flatMap((post) => {
             const card = createSocialCardData(post.data, site, author);
-            return (["webp", "png"] as const).map((format) => ({
+            // PNG only. og:image must stay PNG because several platforms refuse
+            // WebP and AVIF in share previews, and a second format per post
+            // doubled the render work (about 8s each) for no visible gain.
+            return (["png"] as const).map((format) => ({
                 params: {
                     image: socialCardPath(card)
                         .split("/")
                         .at(-1)
-                        ?.replace(/\.webp$/u, ""),
+                        ?.replace(/\.png$/u, ""),
                     format,
                 },
                 props: { card, format },

package/src/scripts/list-reveal.ts

@@ -4,16 +4,32 @@ const ITEM = ":scope > [data-stalux-reveal-item]";
 // 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;
+const STAGGER_MS = 45;
+const MAX_DELAY_MS = 400;
+const DURATION_MS = 380;
+// When a route cue is already moving the page body, the sheet waits for it to
+// mostly settle before unrolling. Starting both at once makes the rows wipe
+// open while the whole page is still semi-transparent, which reads as a smudge.
+const ROUTE_LEAD_IN_MS = 150;
+// Strong ease-out: the row arrives fast and settles softly. The built-in
+// ease-out is too weak to read at this size.
+const EASING = "cubic-bezier(0.23, 1, 0.32, 1)";
+// The clip is inset by a negative margin so a card's box-shadow is not sheared
+// off by the wipe. A hard `inset(0)` would clip the shadow to the border box and
+// make it pop back in when the effect is released.
+const BLEED = "-10px";
+const UNROLL_START = `inset(${BLEED} ${BLEED} 100% ${BLEED})`;
+const UNROLL_END = `inset(${BLEED} ${BLEED} ${BLEED} ${BLEED})`;
 
 /**
- * Lists cascade in once, when their group becomes visible.
+ * Rows unroll into place like paper: each one wipes open from its top edge
+ * downward while settling a few pixels, and the next row starts before the
+ * previous one finishes so the group reads as one continuous sheet unrolling.
  *
- * 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.
+ * Text is authored fully visible. The effect only ever runs on a group that is
+ * about to be read, is skipped for restored history, reduced motion, hidden
+ * documents and persisted shells, and every clip is released afterwards so no
+ * clipped state can outlive the animation.
  */
 export function mountListReveal(): (() => void) | undefined {
     if (typeof IntersectionObserver !== "function") return;
@@ -25,6 +41,8 @@ export function mountListReveal(): (() => void) | undefined {
         .filter((element) => !element.closest("[data-swup-persist]"))
         .slice(0, MAX_CONTAINERS);
     if (!containers.length) return;
+    // A route cue leaves its preset on the document element while it runs.
+    const leadIn = document.documentElement.dataset.staluxVtPreset ? ROUTE_LEAD_IN_MS : 0;
 
     const active = new Set<Animation>();
     const cancel = () => {
@@ -38,21 +56,30 @@ export function mountListReveal(): (() => void) | undefined {
             if (typeof item.animate !== "function") continue;
             try {
                 const animation = item.animate(
-                    {
-                        opacity: [0.6, 1],
-                        transform: ["translateY(8px)", "translateY(0)"],
-                    },
+                    [
+                        {
+                            clipPath: UNROLL_START,
+                            opacity: 0.4,
+                            transform: "translate3d(0, -10px, 0)",
+                        },
+                        {
+                            clipPath: UNROLL_END,
+                            opacity: 1,
+                            transform: "translate3d(0, 0, 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.
+                        delay: leadIn + Math.min(index * STAGGER_MS, MAX_DELAY_MS),
+                        easing: EASING,
+                        // Hidden during the stagger delay instead of popping in.
                         fill: "backwards",
                     },
                 );
                 active.add(animation);
                 const release = () => {
                     active.delete(animation);
+                    // Drops the clip so nothing stays cut off after the wipe.
                     animation.cancel();
                 };
                 void animation.finished.then(release, release);

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/swup-router.ts

@@ -60,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;
@@ -133,6 +143,7 @@ export function installSwupRouter(): Swup {
                                     content: true,
                                     browserMotion: context.browserMotion,
                                     skip: context.controller.signal.aborted,
+                                    releaseOutgoing: context.releaseOutgoing,
                                 },
                             );
                             await context.motion.finished;
@@ -252,17 +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;
-        // Two cues overlap on the outgoing document: a bounded fade on the
-        // changing content region, and the whole page walking back to the top.
-        // The frame, sidebars and header are never part of either one.
+        // 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") {
-            const outgoing = 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 = await outgoing;
+            context.releaseOutgoing = once(await outgoing);
             if (context.controller.signal.aborted || visit !== swup.visit) {
                 context.releaseOutgoing();
                 return;
@@ -276,8 +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);
-        // The old region is detached; drop any fill effect left on it.
-        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]")];
@@ -340,6 +350,7 @@ export function installSwupRouter(): Swup {
             content: true,
             skip: !visit.animation.animate || context.controller.signal.aborted,
             browserMotion: context.browserMotion,
+            releaseOutgoing: context.releaseOutgoing,
         });
     }
 
@@ -349,7 +360,8 @@ 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);
 
@@ -357,6 +369,9 @@ export function installSwupRouter(): Swup {
         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) {
             clearMotionState();
@@ -369,6 +384,7 @@ export function installSwupRouter(): Swup {
     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) {
             clearMotionState();

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);backdrop-filter:blur(3px);overflow-wrap:anywhere;background:0 0;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*/

package/src/utils/social-image.ts

@@ -41,7 +41,7 @@ export function socialCardPath(data: SocialCardData, base = "/"): string {
         .update(JSON.stringify(["stalux-takumi-v2", data]))
         .digest("hex")
         .slice(0, 20);
-    return `${base.replace(/\/$/u, "")}/og/${hash}.webp`;
+    return `${base.replace(/\/$/u, "")}/og/${hash}.png`;
 }
 
 export function resolvePostSocialImage(
@@ -50,11 +50,14 @@ export function resolvePostSocialImage(
     base = "/",
 ): SocialImage {
     if (explicit?.trim() && isSocialImageUrl(explicit.trim())) return { url: explicit.trim() };
+    // PNG for the sharing image, always. Several platforms (and every legacy
+    // crawler) refuse WebP or AVIF in og:image, so this is the one place the
+    // modern format costs reach instead of saving bytes. In-page images are
+    // served as WebP instead, where the browser decides.
     return {
         url: socialCardPath(data, base),
         width: 1200,
         height: 630,
-        type: "image/webp",
-        fallbackUrl: socialCardPath(data, base).replace(/\.webp$/u, ".png"),
+        type: "image/png",
     };
 }