@xingwangzhe/stalux 1.41.5 → 1.43.0

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

@@ -0,0 +1,47 @@
+import { getCollection } from "astro:content";
+import paths from "virtual:stalux-social-card-paths";
+import type { APIRoute } from "astro";
+import { createSocialCardData } from "../../internal/social-card-data";
+import { renderSocialCard } from "../../internal/social-card-renderer";
+import { getAuthorData, getSiteData } from "../../utils/config-utils";
+import { getPostContentIndex } from "../../utils/content-index";
+import { isSocialImageUrl, type SocialCardData, socialCardPath } from "../../utils/social-image";
+
+export async function getStaticPaths() {
+    const entries = await getCollection("config");
+    const site = getSiteData(entries);
+    const author = getAuthorData(entries);
+    const { posts } = await getPostContentIndex();
+    return posts
+        .filter(
+            (post) =>
+                !post.data["og:image"]?.trim() || !isSocialImageUrl(post.data["og:image"].trim()),
+        )
+        .flatMap((post) => {
+            const card = createSocialCardData(post.data, site, author);
+            return (["webp", "png"] as const).map((format) => ({
+                params: {
+                    image: socialCardPath(card)
+                        .split("/")
+                        .at(-1)
+                        ?.replace(/\.webp$/u, ""),
+                    format,
+                },
+                props: { card, format },
+                // Covers may change independently of Markdown. Always recheck them; the renderer
+                // has its own content cache and writes outputs even after Astro cleans dist.
+            }));
+        });
+}
+
+export const GET: APIRoute = async ({ props, logger }) => {
+    const bytes = await renderSocialCard(
+        props.card as SocialCardData,
+        paths,
+        (message) => logger.warn(message),
+        props.format as "webp" | "png",
+    );
+    return new Response(new Uint8Array(bytes), {
+        headers: { "Content-Type": `image/${props.format}` },
+    });
+};

package/src/pages/posts/[post].astro

@@ -1,11 +1,13 @@
 ---
 import { type CollectionEntry, getCollection, render } from "astro:content";
 import { getRuntimeCacheKey } from "@internal/runtime-cache-key";
+import { createSocialCardData } from "@internal/social-card-data";
 import PostLayout from "@layouts/PostLayout.astro";
 import Stalux from "@layouts/Stalux.astro";
 import { analyzeFeatureFlags } from "@plugins/feature-flags";
 import { getAuthorData, getSiteData } from "@utils/config-utils";
 import { getPostContentIndex } from "@utils/content-index";
+import { resolvePostSocialImage } from "@utils/social-image";
 
 interface Props {
     post: CollectionEntry<"posts">;
@@ -33,6 +35,7 @@ export async function getStaticPaths() {
             post.data.updated ?? post.data.date,
             prevPost ? (prevPost.data.updated ?? prevPost.data.date) : "",
             nextPost ? (nextPost.data.updated ?? nextPost.data.date) : "",
+            JSON.stringify(post.data),
             getRuntimeCacheKey(),
         ].join("|");
         return {
@@ -56,6 +59,11 @@ export async function getStaticPaths() {
     title={`${props.post.data.title} | ${siteConfig.title}`}
     description={autoDesc}
     cover={props.post.data.cover}
+    socialImage={resolvePostSocialImage(
+        props.post.data["og:image"],
+        createSocialCardData(props.post.data, siteConfig, authorConfig),
+        import.meta.env.BASE_URL,
+    )}
     isArticle={true}
     date={props.post.data.date}
     updated={props.post.data.updated}

package/src/pages/posts/[post].md.ts

@@ -39,7 +39,7 @@ export const getStaticPaths = (async () => {
     const posts = await getCollection("posts", ({ data }) => !data.draft);
     return posts.map((post) => ({
         params: { post: String(post.data.abbrlink) },
-        cacheKey: `${post.data.updated ?? post.data.date}|${getRuntimeCacheKey()}`,
+        cacheKey: `${post.data.updated ?? post.data.date}|${JSON.stringify(post.data)}|${getRuntimeCacheKey()}`,
         props: { post },
     }));
 }) satisfies GetStaticPaths;

package/src/schemas/collections.ts

@@ -19,6 +19,7 @@ import { defineCollection } from "astro:content";
 import { glob, type Loader } from "astro/loaders";
 import { z } from "astro/zod";
 
+import { isSocialImageUrl } from "../utils/social-image";
 import { configSchema } from "./config";
 
 /** Preserve glob's name, watch behavior and incremental store; only trace the load boundary. */
@@ -98,6 +99,14 @@ const postSchema = z.object({
     desc: z.string({ error: "desc must be a string" }).min(1, "desc is required"),
     cc: z.string().optional().default("CC-BY-NC-SA-4.0"),
     cover: z.string().optional(),
+    "og:image": z
+        .string()
+        .trim()
+        .refine(
+            (value) => value === "" || isSocialImageUrl(value),
+            "og:image must be an HTTP(S) URL or site-root image path",
+        )
+        .optional(),
 });
 
 // ---------------------------------------------------------------------------

package/src/scripts/navigation-client.ts

@@ -0,0 +1,13 @@
+import type Swup from "swup";
+
+declare global {
+    interface Window {
+        swup?: Swup;
+    }
+}
+
+/** Programmatic theme navigation uses the same controller as ordinary links. */
+export function navigate(href: string): void {
+    if (window.swup) window.swup.navigate(href);
+    else window.location.assign(href);
+}

package/src/scripts/navigation-scripts.ts

@@ -0,0 +1,191 @@
+import { createClientLogger } from "./logger";
+
+const logger = createClientLogger("navigation-scripts");
+const executions = new Map<string, Promise<void>>();
+const executedNodes = new WeakSet<HTMLScriptElement>();
+let seeded = false;
+
+interface NavigationScript {
+    attributes: { name: string; value: string }[];
+    content: string;
+    source?: string;
+    type: string;
+    key: string;
+    rerun: boolean;
+    head: boolean;
+    original: HTMLScriptElement;
+}
+
+const JAVASCRIPT_TYPES = new Set([
+    "",
+    "module",
+    "text/javascript",
+    "application/javascript",
+    "text/ecmascript",
+    "application/ecmascript",
+]);
+
+function describeScript(script: HTMLScriptElement, base: string): NavigationScript | undefined {
+    const type = (script.getAttribute("type") ?? "").trim().toLowerCase();
+    if (!JAVASCRIPT_TYPES.has(type) || script.hasAttribute("data-swup-ignore-script")) return;
+    if (script.hasAttribute("nomodule") && "noModule" in document.createElement("script")) return;
+    const rawSource = script.getAttribute("src");
+    let source: string | undefined;
+    if (rawSource !== null) {
+        try {
+            source = new URL(rawSource, base).href;
+        } catch {
+            return;
+        }
+    }
+    const content = script.textContent ?? "";
+    return {
+        attributes: [...script.attributes].map(({ name, value }) => ({ name, value })),
+        content,
+        source,
+        type,
+        key: source ? `src:${source}` : `inline:${type}:${content}`,
+        rerun: script.hasAttribute("data-astro-rerun"),
+        head: script.parentElement?.tagName === "HEAD",
+        original: script,
+    };
+}
+
+function seedCurrentScripts(): void {
+    if (seeded) return;
+    seeded = true;
+    for (const script of document.querySelectorAll<HTMLScriptElement>("script")) {
+        const descriptor = describeScript(script, document.baseURI);
+        if (descriptor) {
+            executions.set(descriptor.key, Promise.resolve());
+            executedNodes.add(script);
+        }
+    }
+}
+
+function waitForScript(script: HTMLScriptElement, timeoutMs: number): Promise<boolean> {
+    return new Promise((resolve) => {
+        let timer: ReturnType<typeof setTimeout>;
+        const finish = (loaded: boolean) => {
+            clearTimeout(timer);
+            script.removeEventListener("load", loadedHandler);
+            script.removeEventListener("error", failedHandler);
+            resolve(loaded);
+        };
+        const loadedHandler = () => finish(true);
+        const failedHandler = () => finish(false);
+        script.addEventListener("load", loadedHandler, { once: true });
+        script.addEventListener("error", failedHandler, { once: true });
+        timer = setTimeout(failedHandler, timeoutMs);
+    });
+}
+
+function abortable(promise: Promise<void>, signal?: AbortSignal): Promise<void> {
+    if (!signal) return promise;
+    if (signal.aborted) return Promise.resolve();
+    return new Promise((resolve) => {
+        const finish = () => {
+            signal.removeEventListener("abort", finish);
+            resolve();
+        };
+        signal.addEventListener("abort", finish, { once: true });
+        void promise.then(finish, finish);
+    });
+}
+
+function executeScript(descriptor: NavigationScript, timeoutMs: number): Promise<void> {
+    // HeadPlugin clones incoming head nodes before container replacement. Those
+    // scripts are inert, but are different nodes from the parsed document we
+    // captured. Replace that clone rather than appending a second head script.
+    const inertCopies = [...document.querySelectorAll<HTMLScriptElement>("script")].filter(
+        (candidate) =>
+            !executedNodes.has(candidate) &&
+            describeScript(candidate, document.baseURI)?.key === descriptor.key,
+    );
+    const existing = executions.get(descriptor.key);
+    if (existing && !descriptor.rerun) {
+        for (const copy of inertCopies) copy.remove();
+        return existing;
+    }
+
+    const script = document.createElement("script");
+    // Dynamic scripts are async by default. Preserve document order, including
+    // the module barrier used below, before copying the page's attributes.
+    script.async = false;
+    for (const { name, value } of descriptor.attributes) {
+        if (name !== "src" && name !== "data-astro-exec") script.setAttribute(name, value);
+    }
+    if (descriptor.source) script.setAttribute("src", descriptor.source);
+    script.textContent = descriptor.content;
+    script.setAttribute("data-astro-exec", "");
+    executedNodes.add(script);
+
+    let observed = script;
+    if (!descriptor.source && descriptor.type === "module") {
+        // Inline module load events are not portable. Astro uses the same
+        // ordered external module barrier to wait for deferred inline modules.
+        observed = document.createElement("script");
+        observed.type = "module";
+        observed.async = false;
+        observed.src = "data:application/javascript,";
+        observed.setAttribute("data-swup-ignore-script", "");
+        if (script.nonce) observed.nonce = script.nonce;
+    }
+    const loaded =
+        descriptor.source || descriptor.type === "module"
+            ? waitForScript(observed, timeoutMs)
+            : Promise.resolve(true);
+    const execution = loaded.then((success) => {
+        if (observed !== script) observed.remove();
+        if (!success) {
+            // Failed fetches may succeed on a subsequent visit. Do not turn a
+            // transient offline response into a session-long disabled feature.
+            if (executions.get(descriptor.key) === execution) executions.delete(descriptor.key);
+            script.remove();
+            logger.warn(`page script failed to load: ${descriptor.source ?? "inline module"}`);
+        }
+    });
+    executions.set(descriptor.key, execution);
+
+    const parent = descriptor.head ? document.head : document.body;
+    const original =
+        descriptor.original.isConnected && descriptor.original.ownerDocument === document
+            ? descriptor.original
+            : inertCopies[0];
+    if (original) {
+        original.replaceWith(script);
+    } else {
+        parent.append(script);
+    }
+    for (const copy of inertCopies) if (copy !== original) copy.remove();
+    if (observed !== script) parent.append(observed);
+    return execution;
+}
+
+/**
+ * Capture both head and body before Swup replaces the document's containers.
+ * Call the returned function after replacement, before astro:page-load. Bundled
+ * modules and ordinary inline scripts retain Astro's once-per-session behavior;
+ * data-astro-rerun opts a script into every visit. SDK scripts already present in
+ * the first document are never reinserted merely because head metadata changed.
+ */
+export function prepareNavigationScripts(
+    nextDocument: Document,
+    options: { timeoutMs?: number; baseUrl?: string } = {},
+): (signal?: AbortSignal) => Promise<void> {
+    seedCurrentScripts();
+    const base = options.baseUrl ?? nextDocument.baseURI ?? document.baseURI;
+    const scripts = [...nextDocument.querySelectorAll<HTMLScriptElement>("script")]
+        .map((script) => describeScript(script, base))
+        .filter((script): script is NavigationScript => script !== undefined);
+    let executed: Promise<void> | undefined;
+    return (signal) => {
+        executed ??= (async () => {
+            for (const script of scripts) {
+                if (signal?.aborted) return;
+                await abortable(executeScript(script, options.timeoutMs ?? 15_000), signal);
+            }
+        })();
+        return executed;
+    };
+}

package/src/scripts/route-motion.ts

@@ -1,4 +1,8 @@
+import type { RouteMotionPreset } from "../utils/route-motion-policy";
+
 export interface RouteMotionEvent {
+    // Retained for integrations using the shared gates with a native transition.
+    // Stalux's Swup router leaves this unset and owns the animation lifecycle.
     viewTransition?: {
         ready?: PromiseLike<unknown>;
         finished?: PromiseLike<unknown>;
@@ -6,13 +10,42 @@ export interface RouteMotionEvent {
     signal?: AbortSignal;
 }
 
+export interface RouteMotionOptions {
+    skip?: boolean;
+    preset?: RouteMotionPreset;
+    browserMotion?: boolean;
+}
+
 export interface RouteMotion {
     ready: Promise<void>;
     finished: Promise<void>;
-    start: (main: HTMLElement | null, options?: { skip?: boolean }) => void;
+    start: (heading: HTMLElement | null, options?: RouteMotionOptions) => void;
     cancel: () => void;
 }
 
+interface HeadingMotion {
+    opacity: number;
+    duration: number;
+    x?: number;
+    y?: number;
+}
+
+// F / E / U / T / S / L / R / X from the route design. Only the incoming
+// heading moves; article prose, lists, sidebars and the persistent shell do not.
+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 },
+};
+
 const motions = new WeakMap<object, RouteMotion>();
 const settle = (promise?: PromiseLike<unknown>): Promise<void> =>
     Promise.resolve(promise).then(
@@ -28,15 +61,30 @@ function completion() {
     return { promise, resolve };
 }
 
-/** Share the native swap and the real content animation across all route consumers. */
+/** A deep history restore must not scroll to or animate an off-screen title. */
+function isVisibleHeading(heading: HTMLElement): boolean {
+    if (!heading.isConnected || !heading.hasAttribute("data-stalux-motion-focus")) return false;
+    const rect = heading.getBoundingClientRect();
+    return (
+        rect.width > 0 &&
+        rect.height > 0 &&
+        rect.height <= Math.min(320, window.innerHeight / 2) &&
+        rect.top < window.innerHeight &&
+        rect.bottom > 0 &&
+        rect.left < window.innerWidth &&
+        rect.right > 0
+    );
+}
+
+/** Share Swup's actual heading animation with background and analytics consumers. */
 export function prepareRouteMotion(event: RouteMotionEvent): RouteMotion {
     const native = event.viewTransition;
     const key = native ?? event;
     const existing = motions.get(key);
     if (existing) return existing;
 
-    // Create these before swap: a consumer must not observe native.finished and
-    // mistake the gap before after-swap installs WAAPI for completed motion.
+    // Installation is a separate gate: before-swap consumers must not mistake
+    // the gap before Swup's incoming animation hook for a completed transition.
     const installed = completion();
     const animationDone = completion();
     const canceled = completion();
@@ -47,6 +95,8 @@ export function prepareRouteMotion(event: RouteMotionEvent): RouteMotion {
         const active = animation;
         animation = undefined;
         try {
+            // Remove fill effects and restore the authored final styles. No
+            // inline transform/opacity survives completion, failure or abort.
             active?.cancel();
         } catch {
             // Releasing an already detached effect must not hold up navigation.
@@ -73,24 +123,41 @@ export function prepareRouteMotion(event: RouteMotionEvent): RouteMotion {
     const motion: RouteMotion = {
         ready,
         finished,
-        start(main, options) {
+        start(heading, options) {
             if (started) return;
             started = true;
             try {
+                const preset = options?.preset ?? "glide";
+                const mobile = window.matchMedia?.("(max-width: 768px)").matches;
                 if (
-                    !main ||
+                    !heading ||
+                    preset === "none" ||
                     options?.skip ||
+                    options?.browserMotion ||
                     document.hidden ||
                     window.matchMedia?.("(prefers-reduced-motion: reduce)").matches ||
-                    typeof main.animate !== "function"
+                    typeof heading.animate !== "function" ||
+                    !isVisibleHeading(heading) ||
+                    (mobile && preset === "restore")
                 ) {
                     animationDone.resolve();
                     return;
                 }
-                animation = main.animate(
-                    { opacity: [0.7, 1] },
-                    { duration: 100, easing: "ease-out" },
-                );
+                const spec = headingMotions[preset];
+                const keyframes: PropertyIndexedKeyframes = { opacity: [spec.opacity, 1] };
+                // Phone routes use the specified pure fade. Unrelated article
+                // links also fade: lateral motion requires explicit prev/next.
+                if (!mobile && (spec.x || spec.y)) {
+                    keyframes.transform = [
+                        `translate3d(${spec.x ?? 0}px, ${spec.y ?? 0}px, 0)`,
+                        "translate3d(0px, 0px, 0)",
+                    ];
+                }
+                animation = heading.animate(keyframes, {
+                    duration: mobile ? 80 : spec.duration,
+                    easing: "cubic-bezier(0.2, 0.7, 0.2, 1)",
+                    fill: "both",
+                });
                 void animation.finished.then(clearAnimation, clearAnimation);
             } catch {
                 clearAnimation();