@xingwangzhe/stalux 1.35.11 → 1.35.13

package/src/internal/page-output-cache.ts

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { promises as fs } from "node:fs";
+import { createReadStream, promises as fs } from "node:fs";
 import path from "node:path";
 
 export interface CachedPageOutput {
@@ -24,9 +24,27 @@ export async function createPageOutputCache(
     }
     const namespace = path.join(directory, hash.digest("hex"));
     await fs.mkdir(namespace, { recursive: true });
-    const assetDigests = new Map<string, string>();
-    for (const asset of assets) assetDigests.set(asset, digest(await fs.readFile(asset)));
-    const key = (entry: string, html: string) => digest(`${entry}\0${html}`);
+    const knownAssets = new Set(assets);
+    const assetDigests = new Map<string, Promise<string | null>>();
+    const assetDigest = (asset: string): Promise<string | null> => {
+        if (!knownAssets.has(asset)) return Promise.resolve(null);
+        let pending = assetDigests.get(asset);
+        if (!pending) {
+            pending = (async () => {
+                try {
+                    const hash = createHash("sha256");
+                    for await (const chunk of createReadStream(asset)) hash.update(chunk);
+                    return hash.digest("hex");
+                } catch {
+                    return null;
+                }
+            })();
+            assetDigests.set(asset, pending);
+        }
+        return pending;
+    };
+    const key = (entry: string, html: string) =>
+        createHash("sha256").update(entry).update("\0").update(html).digest("hex");
     return {
         async get(entry: string, html: string): Promise<CachedPageOutput | undefined> {
             try {
@@ -37,7 +55,7 @@ export async function createPageOutputCache(
                     return undefined;
                 if (!Array.isArray(record.assets)) return undefined;
                 for (const [asset, expected] of record.assets) {
-                    if ((assetDigests.get(asset) ?? null) !== expected) return undefined;
+                    if ((await assetDigest(asset)) !== expected) return undefined;
                 }
                 if (record.font) {
                     if (
@@ -66,10 +84,9 @@ export async function createPageOutputCache(
                 JSON.stringify({
                     ...output,
                     digest: digest(output.html),
-                    assets: referencedAssets.map((asset) => [
-                        asset,
-                        assetDigests.get(asset) ?? null,
-                    ]),
+                    assets: await Promise.all(
+                        referencedAssets.map(async (asset) => [asset, await assetDigest(asset)]),
+                    ),
                 }),
             );
             await fs.rename(temporary, target);

package/src/internal/public-assets.ts

@@ -0,0 +1,59 @@
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+// ---------------------------------------------------------------------------
+// 背景 SVG 判别式同步
+// ---------------------------------------------------------------------------
+
+/**
+ * 把主题包的 public/background/*.svg 同步到用户项目 public/background/。
+ *
+ * 判别式（非无条件覆盖）：
+ * - 同名文件：内容一致则跳过（幂等）；内容不同才覆盖（主题更新了 SVG）
+ * - 用户新增的文件：保留，不删除（避免误删用户自定义背景）
+ * - 不做整目录 force 复制
+ */
+export function syncBackgroundSvgs(
+    srcDir: string,
+    publicDir: string,
+): { copied: number; skipped: number } {
+    const srcBg = path.join(srcDir, "../public/background");
+    if (!existsSync(srcBg)) return { copied: 0, skipped: 0 };
+
+    const destBg = path.join(publicDir, "background");
+    mkdirSync(destBg, { recursive: true });
+
+    let copied = 0;
+    let skipped = 0;
+    for (const name of readdirSync(srcBg)) {
+        if (!name.endsWith(".svg")) continue;
+        const srcFile = path.join(srcBg, name);
+        const destFile = path.join(destBg, name);
+        if (existsSync(destFile)) {
+            const srcBuf = readFileSync(srcFile);
+            const destBuf = readFileSync(destFile);
+            if (srcBuf.equals(destBuf)) {
+                skipped++; // 内容一致，跳过
+                continue;
+            }
+        }
+        copyFileSync(srcFile, destFile);
+        copied++;
+    }
+    return { copied, skipped };
+}
+
+/** Sync packaged math fonts and licensing notices; Astro does not merge integration public directories. */
+export function syncFontAssets(srcDir: string, publicDir: string): void {
+    const source = path.join(srcDir, "../public/fonts");
+    if (!existsSync(source)) return;
+    const destination = path.join(publicDir, "fonts");
+    mkdirSync(destination, { recursive: true });
+    for (const name of readdirSync(source)) {
+        if (!/\.(?:woff2|txt)$/u.test(name)) continue;
+        const from = path.join(source, name);
+        const to = path.join(destination, name);
+        if (existsSync(to) && readFileSync(from).equals(readFileSync(to))) continue;
+        copyFileSync(from, to);
+    }
+}

package/src/internal/runtime-cache-key.ts

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { readdirSync, readFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
 import path from "node:path";
 
 declare const __STALUX_RUNTIME_CACHE_KEY__: string;
@@ -17,10 +17,15 @@ export function hashRuntimeSources(sources: ReadonlyArray<readonly [string, stri
     return hash.digest("hex").slice(0, 16);
 }
 
-function collectFiles(directory: string, root = directory): Array<readonly [string, string]> {
+function collectFiles(
+    directory: string,
+    root = directory,
+    include = (_name: string) => true,
+): Array<readonly [string, string]> {
     return readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
         const target = path.join(directory, entry.name);
-        if (entry.isDirectory()) return collectFiles(target, root);
+        if (entry.isDirectory()) return collectFiles(target, root, include);
+        if (!include(entry.name)) return [];
         return [[path.relative(root, target), readFileSync(target, "utf8")] as const];
     });
 }
@@ -30,9 +35,15 @@ export function createRuntimeCacheKey(
     packageJson: string,
     stylesDirectory?: string,
     styleMapping?: string,
+    configDirectory?: string,
 ): string {
     return hashRuntimeSources([
         ...collectFiles(scriptsDirectory),
+        ...(configDirectory && existsSync(configDirectory)
+            ? collectFiles(configDirectory, configDirectory, (name) => /\.ya?ml$/iu.test(name)).map(
+                  ([name, contents]) => [`config/${name}`, contents] as const,
+              )
+            : []),
         ...(stylesDirectory
             ? readdirSync(stylesDirectory)
                   .filter((name) => /^generated(?:-[a-z]+)?\.css$/u.test(name))

package/src/internal/style-names.generated.ts

@@ -193,32 +193,33 @@ export const styleNames: { classes: Record<string, string>; variables: Record<st
         "stalux-toc-title": "s59",
         "stalux-typewriter": "s5a",
         "stalux-typewriter-accessible": "s5b",
-        "stalux-typewriter-text": "s5c",
-        "stalux-u-flex": "s5d",
-        "stalux-u-flex-col": "s5e",
-        "stalux-u-flex-wrap": "s5f",
-        "stalux-u-items-center": "s5g",
-        "stalux-u-justify-center": "s5h",
-        "stalux-u-min-w-0": "s5i",
-        "stalux-u-text-center": "s5j",
-        "stalux-u-w-full": "s5k",
-        "stalux-weather": "s5l",
-        "stalux-weather-footer": "s5m",
-        "stalux-weather-heading": "s5n",
-        "stalux-weather-location": "s5o",
-        "stalux-weather-main": "s5p",
-        "stalux-weather-source": "s5q",
-        "stalux-weather-status": "s5r",
-        "stalux-word-body": "s5s",
-        "stalux-word-card": "s5t",
-        "stalux-word-date": "s5u",
-        "stalux-word-footer": "s5v",
-        "stalux-word-list-item": "s5w",
-        "stalux-word-list-list": "s5x",
-        "stalux-word-source-date": "s5y",
-        "stalux-word-source-link": "s5z",
-        "stalux-word-source-meta": "s60",
-        "stalux-word-source-text": "s61"
+        "stalux-typewriter-reserve": "s5c",
+        "stalux-typewriter-text": "s5d",
+        "stalux-u-flex": "s5e",
+        "stalux-u-flex-col": "s5f",
+        "stalux-u-flex-wrap": "s5g",
+        "stalux-u-items-center": "s5h",
+        "stalux-u-justify-center": "s5i",
+        "stalux-u-min-w-0": "s5j",
+        "stalux-u-text-center": "s5k",
+        "stalux-u-w-full": "s5l",
+        "stalux-weather": "s5m",
+        "stalux-weather-footer": "s5n",
+        "stalux-weather-heading": "s5o",
+        "stalux-weather-location": "s5p",
+        "stalux-weather-main": "s5q",
+        "stalux-weather-source": "s5r",
+        "stalux-weather-status": "s5s",
+        "stalux-word-body": "s5t",
+        "stalux-word-card": "s5u",
+        "stalux-word-date": "s5v",
+        "stalux-word-footer": "s5w",
+        "stalux-word-list-item": "s5x",
+        "stalux-word-list-list": "s5y",
+        "stalux-word-source-date": "s5z",
+        "stalux-word-source-link": "s60",
+        "stalux-word-source-meta": "s61",
+        "stalux-word-source-text": "s62"
     },
     "variables": {
         "--accent-20p": "--s0",

package/src/layouts/PostLayout.astro

@@ -58,6 +58,7 @@ const walineConfig = walineSection?.serverURL
 
         <!-- Main Content -->
         <PostContent
+            postId={props.postId}
             title={props.title}
             description={props.description}
             titleTransitionName={props.postId === undefined

package/src/layouts/Stalux.astro

@@ -36,7 +36,7 @@ const aiConfig = getAiDiscoveryData(configEntries);
 const htmlLang = siteConfig.lang || "zh-CN";
 
 // 背景 SVG 以静态 URL 硬编码在 background.ts（纯客户端），
-// 集成在 config:setup 时把 SVG 复制到用户项目 public/background/。
+// 集成在 config:done 时把 SVG 复制到用户项目最终的 publicDir/background/。
 // SSR 不渲染背景图，默认露出 .bg-layer 的灰墙底色（--stalux-bg-color），
 // 客户端运行时随机选图；不经过 import.meta.glob 资源管线，
 // 保证增量构建依赖图 hash 稳定。
@@ -77,6 +77,8 @@ const routeAnimation = getRouteAnimation(routeKind);
         data-stalux-site-url={siteConfig.url}
         data-stalux-site-description={siteConfig.description}
         data-stalux-site-lang={siteConfig.lang}
+        data-stalux-markdown-export={String(promoteConfig?.export_md === true)}
+        data-stalux-webmcp-enabled={String(aiConfig?.conformance !== "disabled")}
         data-stalux-ga-id={headConfig?.googleAnalyticsId}
         data-stalux-clarity-id={headConfig?.bingClarityId}
         data-stalux-umami-id={headConfig?.umami?.id}

package/src/pages/api/post.abbrlink.json.ts

@@ -16,9 +16,6 @@ export const GET: APIRoute = async () => {
         headers: {
             "Content-Type": "application/json; charset=utf-8",
             "Cache-Control": "public, max-age=0, must-revalidate",
-            "RateLimit-Limit": "60",
-            "RateLimit-Remaining": "59",
-            "RateLimit-Reset": "60",
         },
     });
 };

package/src/pages/api/posts.json.ts

@@ -1,5 +1,6 @@
-import { getCollection } from "astro:content";
-import { analyzeFeatureFlags } from "@plugins/feature-flags";
+import { getPostContentIndex } from "@utils/content-index";
+import { sitePath } from "@utils/site-path";
+import { getPostDescriptions } from "@utils/word-count-utils";
 import type { APIRoute } from "astro";
 
 export const prerender = true;
@@ -11,30 +12,26 @@ export const prerender = true;
  * 是 stalux_get_post / stalux_random_post 等 WebMCP 工具的廉价数据源。
  */
 export const GET: APIRoute = async ({ logger }) => {
-    const posts = await getCollection("posts", ({ data }) => !data.draft);
+    const { posts } = await getPostContentIndex();
 
-    const payload = await Promise.all(
-        posts.map(async (post) => ({
-            title: post.data.title,
-            abbrlink: String(post.data.abbrlink),
-            date: post.data.date ?? undefined,
-            updated: post.data.updated ?? undefined,
-            tags: post.data.tags ?? [],
-            categories: post.data.categories ?? [],
-            desc: post.data.desc ?? "",
-            wordCount: (await analyzeFeatureFlags(post.body, logger)).wordCount,
-            url: `/posts/${post.data.abbrlink}/`,
-        })),
-    );
+    const descriptions = await getPostDescriptions(logger);
+    const payload = posts.map((post) => ({
+        title: post.data.title,
+        abbrlink: String(post.data.abbrlink),
+        date: post.data.date ?? undefined,
+        updated: post.data.updated ?? undefined,
+        tags: post.data.tags ?? [],
+        categories: post.data.categories ?? [],
+        desc: post.data.desc ?? "",
+        wordCount: descriptions.get(String(post.data.abbrlink))?.wordCount ?? 0,
+        url: sitePath(`posts/${encodeURIComponent(String(post.data.abbrlink))}/`),
+    }));
 
     return new Response(JSON.stringify(payload), {
         status: 200,
         headers: {
             "Content-Type": "application/json; charset=utf-8",
             "Cache-Control": "public, max-age=0, must-revalidate",
-            "RateLimit-Limit": "60",
-            "RateLimit-Remaining": "59",
-            "RateLimit-Reset": "60",
         },
     });
 };

package/src/pages/openapi.json.ts

@@ -7,40 +7,6 @@ const responseSchema = {
     items: { type: "object", additionalProperties: true },
 };
 
-const problemSchema = {
-    type: "object",
-    required: ["type", "title", "status", "code", "detail"],
-    properties: {
-        type: { type: "string", format: "uri", description: "Stable problem type URI." },
-        title: { type: "string" },
-        status: { type: "integer", minimum: 400, maximum: 599 },
-        code: { type: "string", description: "Machine-readable error code." },
-        detail: { type: "string" },
-        resolution: { type: "string" },
-    },
-};
-
-const rateLimitHeaders = {
-    "RateLimit-Limit": {
-        description: "Maximum requests in the advertised window.",
-        schema: { type: "integer" },
-    },
-    "RateLimit-Remaining": {
-        description: "Remaining requests in the advertised window.",
-        schema: { type: "integer" },
-    },
-    "RateLimit-Reset": {
-        description: "Seconds until the advertised window resets.",
-        schema: { type: "integer" },
-    },
-};
-
-const problemResponse = (description: string, status: number) => ({
-    description,
-    content: { "application/problem+json": { schema: problemSchema } },
-    headers: status === 429 ? { "Retry-After": { schema: { type: "integer" } } } : undefined,
-});
-
 export const GET: APIRoute = async ({ site }) => {
     const server = site?.toString().replace(/\/$/, "") || "";
     const document = {
@@ -68,10 +34,7 @@ export const GET: APIRoute = async ({ site }) => {
                         "200": {
                             description: "Published post metadata",
                             content: { "application/json": { schema: responseSchema } },
-                            headers: rateLimitHeaders,
                         },
-                        "400": problemResponse("Invalid request.", 400),
-                        "429": problemResponse("Rate limit exceeded.", 429),
                     },
                 },
             },
@@ -85,10 +48,7 @@ export const GET: APIRoute = async ({ site }) => {
                         "200": {
                             description: "Published post identifiers",
                             content: { "application/json": { schema: responseSchema } },
-                            headers: rateLimitHeaders,
                         },
-                        "400": problemResponse("Invalid request.", 400),
-                        "429": problemResponse("Rate limit exceeded.", 429),
                     },
                 },
             },
@@ -97,7 +57,8 @@ export const GET: APIRoute = async ({ site }) => {
                     tags: ["Posts"],
                     operationId: "readPostMarkdown",
                     summary: "Read one post as Markdown",
-                    description: "Returns the normalized Markdown source for a published post.",
+                    description:
+                        "Returns normalized Markdown when promote.export_md is enabled. Otherwise this file is absent; HTTP errors and their body format are controlled by the static host.",
                     parameters: [
                         {
                             name: "abbrlink",
@@ -112,8 +73,6 @@ export const GET: APIRoute = async ({ site }) => {
                             description: "Markdown post content",
                             content: { "text/markdown": { schema: { type: "string" } } },
                         },
-                        "404": problemResponse("Post not found.", 404),
-                        "429": problemResponse("Rate limit exceeded.", 429),
                     },
                 },
             },
@@ -124,7 +83,7 @@ export const GET: APIRoute = async ({ site }) => {
             deprecation:
                 "Breaking changes are announced in the documentation and a Deprecation/Sunset response header may be added before removal.",
             rateLimits:
-                "Static exports publish RateLimit-* documentation headers but cannot enforce a dynamic quota or emit Retry-After without a server runtime.",
+                "These files are static. Stalux does not enforce per-client quotas or generate dynamic rate-limit/error responses; any hosting limits belong to the deployment provider.",
         },
     };
 

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

@@ -1,49 +1,13 @@
 import { type CollectionEntry, getCollection } from "astro:content";
+import { getRuntimeCacheKey } from "@internal/runtime-cache-key";
 import { type ConfigMap, isMarkdownExportEnabled, loadConfig } from "@utils/ai-discovery";
 import { buildCCLink, buildCCName } from "@utils/cc";
 import { createTranslator } from "@utils/i18n";
+import { reconstructMarkdown } from "@utils/post-markdown";
 import type { APIRoute, GetStaticPaths } from "astro";
 
 export const prerender = true;
 
-function reconstructMarkdown(post: CollectionEntry<"posts">): string {
-    const d = post.data;
-    const lines: string[] = ["---"];
-
-    lines.push(`title: ${yamlScalar(d.title)}`);
-    if (d.tags?.length)
-        lines.push(`tags:\n${d.tags.map((t) => `    - ${yamlScalar(t)}`).join("\n")}`);
-    if (d.categories?.length)
-        lines.push(`categories:\n${d.categories.map((c) => `    - ${yamlScalar(c)}`).join("\n")}`);
-    lines.push(`date: ${yamlScalar(d.date)}`);
-    if (d.updated) lines.push(`updated: ${yamlScalar(d.updated)}`);
-    lines.push(`desc: ${yamlScalar(d.desc)}`);
-    lines.push(`abbrlink: ${yamlScalar(String(d.abbrlink))}`);
-    if (d.draft) lines.push(`draft: true`);
-    if (d.cc && d.cc !== "CC-BY-NC-SA-4.0") lines.push(`cc: ${yamlScalar(d.cc)}`);
-    if (d.cover) lines.push(`cover: ${yamlScalar(d.cover)}`);
-
-    lines.push("---", "");
-    const body = typeof post.body === "string" ? post.body : "";
-    return lines.join("\n") + body + (body.endsWith("\n") ? "" : "\n");
-}
-
-function yamlScalar(value: string): string {
-    if (
-        value === "" ||
-        /[:#{}[\],&*?|>!%@`]/.test(value) ||
-        value.includes("\n") ||
-        value.startsWith(" ") ||
-        value.endsWith(" ") ||
-        value === "true" ||
-        value === "false" ||
-        value === "null"
-    ) {
-        return JSON.stringify(value);
-    }
-    return value;
-}
-
 /** 生成 Markdown 格式的版权脚注 */
 function generateCCFooter(post: CollectionEntry<"posts">, config: ConfigMap): string {
     const siteConfig = config.get("site") ?? {};
@@ -75,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,
+        cacheKey: `${post.data.updated ?? post.data.date}|${getRuntimeCacheKey()}`,
         props: { post },
     }));
 }) satisfies GetStaticPaths;
@@ -88,7 +52,7 @@ export const GET: APIRoute = async ({ props }) => {
 
     // 内容集合已经提供解析后的 frontmatter 和正文，导出一份内容等价的 Markdown。
     // 不读取 post.filePath，避免把页面端点绑定到 Node 文件系统。
-    let markdown = reconstructMarkdown(post);
+    let markdown = reconstructMarkdown(post.data, post.body);
 
     // 追加版权脚注（不修改内容源文件）
     const footer = generateCCFooter(post, config);

package/src/plugins/feature-flags.ts

@@ -290,7 +290,14 @@ export function analyzeFeatureFlags(
     }
     logDetail(logger, "markdown-analysis", "cache miss; analyzing feature flags");
 
-    const resultPromise = analyzeFeatureFlagsUncached(content);
+    if (import.meta.env.DEV && analysisCache.size >= 128) {
+        const oldest = analysisCache.keys().next().value;
+        if (oldest !== undefined) analysisCache.delete(oldest);
+    }
+    const resultPromise = analyzeFeatureFlagsUncached(content).catch((error: unknown) => {
+        if (analysisCache.get(content) === resultPromise) analysisCache.delete(content);
+        throw error;
+    });
     analysisCache.set(content, resultPromise);
     return resultPromise;
 }

package/src/scripts/navigation-font.ts

@@ -0,0 +1,28 @@
+/** Warm the destination font while the old page is still visible. Never delay navigation indefinitely. */
+export async function prepareNavigationFont(
+    nextDocument: Document,
+    signal: AbortSignal,
+    timeoutMs = 1000,
+): Promise<void> {
+    const href = nextDocument
+        .querySelector<HTMLLinkElement>("link[data-stalux-page-font-preload]")
+        ?.getAttribute("href");
+    if (!href || signal.aborted || typeof FontFace === "undefined") return;
+    const url = new URL(href, window.location.href);
+    if (url.origin !== window.location.origin) return;
+    // Loading a detached face fills the font cache without replacing the old page's font.
+    const face = new FontFace("LXGW WenKai-Page Subset", `url(${JSON.stringify(url.href)})`, {
+        style: "normal",
+        weight: "100 900",
+    });
+    await new Promise<void>((resolve) => {
+        const finish = () => {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", finish);
+            resolve();
+        };
+        const timer = setTimeout(finish, timeoutMs);
+        signal.addEventListener("abort", finish, { once: true });
+        void face.load().then(finish, finish);
+    });
+}

package/src/scripts/navigation.ts

@@ -10,7 +10,7 @@ interface SearchDialog extends HTMLElement {
     close?: () => void;
 }
 
-async function openSearchDialog(): Promise<void> {
+async function openSearchDialog(signal: AbortSignal): Promise<void> {
     logger.debug("loading search UI");
     await Promise.all([
         import("@pagefind/component-ui"),
@@ -18,6 +18,7 @@ async function openSearchDialog(): Promise<void> {
             document.querySelector<HTMLLinkElement>("link[data-stalux-search-style]"),
         ),
     ]);
+    if (signal.aborted) return;
     const dialog = document.querySelector<SearchDialog>("pagefind-modal#search");
     await upgradeAndOpenSearchDialog(
         {
@@ -25,6 +26,7 @@ async function openSearchDialog(): Promise<void> {
             upgrade: (element) => customElements.upgrade(element),
         },
         dialog,
+        signal,
     );
 }
 
@@ -105,7 +107,7 @@ registerPageLifecycle("navigation", () => {
             event.preventDefault();
             closeNav();
             try {
-                await openSearchDialog();
+                await openSearchDialog(controller.signal);
                 logger.debug("search dialog opened");
             } catch (error) {
                 logger.error("search dialog failed to open; next click can retry", error);

package/src/scripts/page-runtime.ts

@@ -55,6 +55,7 @@ export function registerPageLifecycle(
     logger.debug("lifecycle registered");
 
     let active = true;
+    let pageGeneration = 0;
     const registration: RuntimeRegistration = {
         unregister: () => undefined,
     };
@@ -72,6 +73,7 @@ export function registerPageLifecycle(
     };
     const mountPage = () => {
         if (!active) return;
+        pageGeneration++;
         disposePage();
         const started = performance.now();
         logger.debug("mount started");
@@ -86,7 +88,10 @@ export function registerPageLifecycle(
         }
     };
     const handlePageLoad = () => mountPage();
-    const handleBeforeSwap = () => disposePage();
+    const handleBeforeSwap = () => {
+        pageGeneration++;
+        disposePage();
+    };
 
     target.addEventListener("astro:page-load", handlePageLoad);
     target.addEventListener("astro:before-swap", handleBeforeSwap);
@@ -94,15 +99,24 @@ export function registerPageLifecycle(
     registration.unregister = () => {
         if (!active) return;
         active = false;
-        disposePage();
-        target.removeEventListener("astro:page-load", handlePageLoad);
-        target.removeEventListener("astro:before-swap", handleBeforeSwap);
-        registry.delete(key);
+        try {
+            disposePage();
+        } finally {
+            target.removeEventListener("astro:page-load", handlePageLoad);
+            target.removeEventListener("astro:before-swap", handleBeforeSwap);
+            registry.delete(key);
+        }
     };
     registry.set(key, registration);
 
     // Late-loaded modules can miss Astro's initial page-load event.
-    if (target.readyState === "complete") queueTask(mountPage);
+    if (target.readyState === "complete") {
+        const scheduledGeneration = pageGeneration;
+        queueTask(() => {
+            // A real page-load or swap supersedes this late-module fallback.
+            if (pageGeneration === scheduledGeneration) mountPage();
+        });
+    }
 
     return registration.unregister;
 }