@xingwangzhe/stalux 1.54.0 → 1.55.1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@xingwangzhe/stalux",
-    "version": "1.54.0",
+    "version": "1.55.1",
     "description": "A powerful, modern Astro blog theme — use as template or install as plugin",
     "keywords": [
         "astro",
@@ -103,13 +103,12 @@
     },
     "dependencies": {
         "@astrojs/compiler": "^4.0.0",
-        "@astrojs/markdown-satteri": "^0.4.6",
+        "@astrojs/markdown-satteri": "^0.4.8",
         "@astrojs/rss": "^4.0.19",
         "@astrojs/sitemap": "^3.7.4",
         "@expressive-code/plugin-line-numbers": "^0.44.3",
-        "@lucide/astro": "^1.66.0",
-        "@mcp-b/webmcp-polyfill": "^6.0.3",
-        "@microsoft/clarity": "1.0.2",
+        "@lucide/astro": "^1.71.0",
+        "@microsoft/clarity": "^1.0.2",
         "@pagefind/component-ui": "^1.6.0",
         "@swup/a11y-plugin": "^5.2.1",
         "@swup/body-class-plugin": "^3.3.0",
@@ -122,7 +121,8 @@
         "@swup/route-name-plugin": "^4.1.0",
         "@swup/scripts-plugin": "^2.1.0",
         "@swup/scroll-plugin": "^4.0.0",
-        "@takumi-rs/core": "2.19.0",
+        "@takumi-rs/core": "^2.20.0",
+        "@w3c/webmcp-polyfill": "^0.1.0",
         "@waline/client": "^3.16.2",
         "@xingwangzhe/cjk-font-split-native": "^0.4.10",
         "@xingwangzhe/satteri-mermaid": "^0.8.2",
@@ -132,39 +132,40 @@
         "astro-seo": "^1.2.0",
         "badge-maker": "^6.0.0",
         "css-tree": "^3.2.1",
-        "image-size": "^2.0.4",
+        "escape-string-regexp": "^5.0.0",
+        "html-escaper": "^3.0.3",
+        "image-size": "^2.1.0",
         "magic-string": "^1.4.5",
         "pagefind": "^1.6.0",
-        "parse5": "^8.1.0",
+        "parse5": "^8.1.1",
         "photoswipe": "^5.4.4",
-        "satteri": "0.11.6",
-        "simple-icons": "^16.36.0",
-        "swup": "4.10.0",
+        "satteri": "^0.11.7",
+        "simple-icons": "^16.37.0",
+        "swup": "^4.10.0",
         "temml": "^0.14.0",
+        "webmcp-types": "^0.1.10",
         "yaml": "^2.9.1"
     },
     "devDependencies": {
         "@astrojs/check": "^0.9.12",
-        "@biomejs/biome": "^2.6.5",
+        "@biomejs/biome": "^2.6.6",
         "@swup/debug-plugin": "^4.1.0",
-        "@types/bun": "1.4.4",
+        "@types/bun": "^1.4.4",
         "@types/css-tree": "^3.2.0",
+        "@types/html-escaper": "^3.0.4",
         "@unocss/astro": "^66.12.0",
         "@vitest/coverage-v8": "^5.1.0",
-        "astro": "^7.4.7",
+        "astro": "^7.4.10",
         "happy-dom": "^21.0.4",
-        "knip": "^6.44.1",
-        "sharp": "0.35.5",
+        "knip": "^6.45.0",
+        "sharp": "^0.35.5",
         "sonda": "^0.14.0",
         "typescript": "npm:@typescript/typescript6@6.0.2",
         "unocss": "^66.12.0",
-        "vite": "^8.3.6",
+        "vite": "^8.3.8",
         "vitest": "^5.1.0"
     },
     "peerDependencies": {
-        "astro": "^7.4.7"
-    },
-    "overrides": {
-        "satteri": "0.11.6"
+        "astro": "^7.4.10"
     }
 }

package/src/env.d.ts

@@ -1,4 +1,5 @@
 /// <reference types="astro/client" />
+/// <reference types="webmcp-types" />
 
 declare module "*.css";
 declare module "@pagefind/component-ui/css";

package/src/index.ts

@@ -61,7 +61,6 @@ import {
 } from "./internal/satteri-config";
 import { searchStylePlugin } from "./internal/search-style";
 import { createViteAliases } from "./internal/vite-aliases";
-import { webMcpMutationsPlugin } from "./internal/webmcp-mutations";
 import { featureFlagsHast, featureFlagsMdast } from "./plugins/feature-flags";
 import { imageCaptions } from "./plugins/image-captions";
 import { imageDimensions } from "./plugins/image-dimensions";
@@ -176,7 +175,7 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
                     },
                     vite: {
                         optimizeDeps: {
-                            exclude: ["@mcp-b/webmcp-polyfill"],
+                            exclude: ["@w3c/webmcp-polyfill"],
                             // Discover lazy page features before the first visit:
                             // Vite re-optimization would otherwise reload the
                             // entire document midway through a Swup navigation.
@@ -224,7 +223,6 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
                             },
                             swupDebugPlugin(command === "dev"),
                             searchStylePlugin(command === "dev", config.base),
-                            webMcpMutationsPlugin(),
                             ...(command === "build"
                                 ? [markdownPropagationPlugin(), compactStylesPlugin(srcDir)]
                                 : []),

package/src/internal/swup-debug-plugin.ts

@@ -1,4 +1,6 @@
+import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
+import { dirname, resolve } from "node:path";
 import type { Plugin } from "vite";
 
 /** Keep a source-only devDependency optional in published consumer projects. */
@@ -7,7 +9,18 @@ export function swupDebugPlugin(development: boolean): Plugin {
     let entry: string | undefined;
     if (development) {
         try {
-            entry = createRequire(import.meta.url).resolve("@swup/debug-plugin");
+            // require.resolve honours the "require" condition and returns the CJS
+            // build. Re-exporting that from a virtual ESM module makes the browser
+            // fail with "does not provide an export named 'default'". Pick the
+            // package's ESM entry from its manifest instead.
+            const cjs = createRequire(import.meta.url).resolve("@swup/debug-plugin");
+            const manifest = resolve(dirname(cjs), "../package.json");
+            const pkg = JSON.parse(readFileSync(manifest, "utf8")) as {
+                exports?: { "."?: { import?: string } };
+                module?: string;
+            };
+            const esm = pkg.exports?.["."]?.import ?? pkg.module;
+            if (esm) entry = resolve(dirname(manifest), esm);
         } catch {
             // Consumers can install @swup/debug-plugin as their own devDependency.
         }

package/src/plugins/satteri-temml.ts

@@ -9,20 +9,12 @@
  */
 import type { AstroIntegrationLogger } from "astro";
 
+import { escape as escapeHtml } from "html-escaper";
 import { defineMdastPlugin, type MdastNode, type MdastVisitorContext } from "satteri";
 import temmlLib, { type Options as TemmlOptions } from "temml";
 
 const emptyOptions = {};
 
-function escapeHtml(value: string): string {
-    return value
-        .replaceAll("&", "&")
-        .replaceAll("<", "&lt;")
-        .replaceAll(">", "&gt;")
-        .replaceAll('"', "&quot;")
-        .replaceAll("'", "&#39;");
-}
-
 type MathNode = Extract<MdastNode, { type: "math" | "inlineMath" }>;
 
 function renderTemmlError(value: string, error: unknown, options: TemmlOptions): string {

package/src/scripts/background.ts

@@ -73,9 +73,19 @@ export function installSessionBackground(): void {
             },
         );
     };
+    /**
+     * 装饰背景不参与 LCP，也不该和首屏脚本/字体抢带宽。
+     * DOM 就绪后先让关键资源占用连接，再在空闲时请求；
+     * `timeout` 兜底防止页面持续繁忙时背景永远缺席。
+     */
+    const schedule = () => {
+        const idle = globalThis.requestIdleCallback;
+        if (typeof idle === "function") idle(start, { timeout: 1000 });
+        else setTimeout(start, 200);
+    };
     if (document.readyState === "loading")
-        document.addEventListener("DOMContentLoaded", start, { once: true });
-    else start();
+        document.addEventListener("DOMContentLoaded", schedule, { once: true });
+    else schedule();
 }
 
 installSessionBackground();

package/src/scripts/search-engine.ts

@@ -1,3 +1,5 @@
+import escapeStringRegexp from "escape-string-regexp";
+import { escape as escapeHtml } from "html-escaper";
 import {
     CJK,
     type CjkDocument,
@@ -37,19 +39,12 @@ export interface NativeSearch {
     mergeIndex: (url: string, options?: Record<string, unknown>) => Promise<void>;
 }
 const logger = createClientLogger("search/cjk");
-const escapeHtml = (text: string) =>
-    text.replace(
-        /[&<>"']/gu,
-        (char) =>
-            ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[char] ?? char,
-    );
-
 function excerpt(content: string, terms: string[]) {
     const position = Math.max(0, normalizeSearch(content).indexOf(terms[0] ?? ""));
     const start = Math.max(0, position - 45);
     const plain = `${start ? "…" : ""}${content.slice(start, start + 180)}${content.length > start + 180 ? "…" : ""}`;
     const pattern = terms
-        .map((term) => term.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&"))
+        .map((term) => escapeStringRegexp(term))
         .sort((a, b) => b.length - a.length)
         .join("|");
     const regex = new RegExp(pattern, "giu");

package/src/scripts/swup-router.ts

@@ -36,6 +36,7 @@ interface NavigationContext {
     incomingDocument?: Document;
     removeOutgoing?: () => void;
     obsoleteStyles: Element[];
+    pruneObsoleteStyles?: () => void;
     glide?: PageGlide;
     releaseOutgoing?: () => void;
 }
@@ -405,7 +406,17 @@ export function installSwupRouter(): Swup {
         // 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();
+        // ParallelPlugin keeps the outgoing container visible while it fades out
+        // and only removes it at visit:end / content:remove. Its page-scoped CSS
+        // must outlive that DOM: pruning here paints the outgoing (and already
+        // overlapping) content unstyled for the whole overlap. `awaitAssets`
+        // only covers the incoming stylesheets, not the outgoing ones.
+        const pruneObsoleteStyles = once(() => {
+            for (const element of context.obsoleteStyles) element.remove();
+        });
+        context.pruneObsoleteStyles = pruneObsoleteStyles;
+        if (context.outgoingReady) void context.outgoingReady.then(pruneObsoleteStyles);
+        else pruneObsoleteStyles();
         const incomingStyles = [...next.head.querySelectorAll("style,link[rel=stylesheet]")];
         authoredStyles = [...document.head.querySelectorAll("style,link[rel=stylesheet]")].filter(
             (el) => incomingStyles.some((other) => el.isEqualNode(other)),
@@ -513,6 +524,9 @@ export function installSwupRouter(): Swup {
         const context = contexts.get(visit);
         context?.controller.abort();
         context?.removeOutgoing?.();
+        // An aborted visit never reaches visit:end, so its outgoing CSS has to
+        // be released here or it would linger in head forever.
+        context?.pruneObsoleteStyles?.();
         context?.glide?.cancel();
         // An aborted visit keeps no exit fill: without this the stage would stay
         // transparent until the next successful navigation.
@@ -528,6 +542,9 @@ export function installSwupRouter(): Swup {
     swup.hooks.on("visit:fail", cancel);
     swup.hooks.on("visit:end", (visit) => {
         const context = contexts.get(visit);
+        // Safety net for paths where the exit animation never settles. The prune
+        // is idempotent, so a completed outgoingReady does not remove twice.
+        context?.pruneObsoleteStyles?.();
         context?.glide?.cancel();
         context?.releaseOutgoing?.();
         context?.motion?.start(null, { skip: true });

package/src/scripts/webmcp.ts

@@ -10,7 +10,7 @@
  * 工具描述跟随站点语言（site.yml 的 lang）：中文站显示中文说明，
  * 英文站显示英文说明，保证 AI 代理与评审（如 webmcp.com）能读懂。
  *
- * 浏览器无原生 modelContext 时，由布局注入的 @mcp-b/webmcp-polyfill
+ * 浏览器无原生 modelContext 时，由官方 @w3c/webmcp-polyfill
  * 提供兜底实现；两者都没有则静默跳过注册，不影响普通访问者。
  *
  * Spec: https://github.com/webmachinelearning/webmcp
@@ -18,7 +18,8 @@
 // 浏览器无原生 document.modelContext 时由 polyfill 兜底安装；
 // 有原生实现或已存在 WebMCP-aware 扩展时，polyfill 检测到后自动 no-op。
 // ESM entry exports installWebMCP; importing it alone does not install the API.
-import { installWebMCP } from "@mcp-b/webmcp-polyfill";
+import { installWebMCP } from "@w3c/webmcp-polyfill";
+import type { WebMCP } from "webmcp-types";
 import { createPostLookup } from "../utils/post-lookup";
 import { sitePath } from "../utils/site-path";
 import { createClientLogger } from "./logger";
@@ -38,27 +39,8 @@ declare global {
     }
 }
 
-/** 规范（index.bs）中 ModelContextTool 字典的最小类型子集 */
-interface WebMCPTool {
-    name: string;
-    title?: string;
-    description: string;
-    inputSchema?: object;
-    annotations?: {
-        readOnlyHint?: boolean;
-        untrustedContentHint?: boolean;
-    };
-    execute: (
-        input: Record<string, unknown>,
-        options?: { signal?: AbortSignal },
-    ) => Promise<unknown>;
-}
-
-interface ModelContext {
-    registerTool: (tool: WebMCPTool, options?: { signal?: AbortSignal }) => Promise<undefined>;
-}
-
-type DocumentWithModelContext = { modelContext?: ModelContext };
+/** 工具定义直接使用官方 webmcp-types 的 ModelContextTool，不自写最小接口。 */
+type WebMCPTool = WebMCP.ModelContextTool;
 
 // ---------------------------------------------------------------------------
 // 语言选择（跟随站点 site.yml 的 lang）
@@ -763,7 +745,10 @@ function buildTools(): WebMCPTool[] {
         const execute = tool.execute;
         return {
             ...tool,
-            execute: async (input: Record<string, unknown>, options?: { signal?: AbortSignal }) => {
+            execute: async (
+                input: Record<string, unknown>,
+                options?: WebMCP.ToolExecuteCallbackOptions,
+            ) => {
                 if (!input || typeof input !== "object" || Array.isArray(input))
                     return err("BAD_INPUT", pick("参数必须是对象", "Input must be an object"));
                 const properties =
@@ -773,7 +758,10 @@ function buildTools(): WebMCPTool[] {
                     return err("BAD_INPUT", pick("包含未知参数", "Unknown input property"));
                 if (options?.signal?.aborted) throw options.signal.reason;
                 try {
-                    const result = await execute(input, options);
+                    const result = await execute(
+                        input,
+                        options ?? { signal: new AbortController().signal },
+                    );
                     options?.signal?.throwIfAborted();
                     return result;
                 } catch (error) {
@@ -799,8 +787,7 @@ function buildTools(): WebMCPTool[] {
 async function registerTools(
     signal: AbortSignal,
 ): Promise<{ registered: string[]; reason?: string }> {
-    const doc = document as DocumentWithModelContext;
-    const ctx = doc.modelContext;
+    const ctx = document.modelContext;
     if (!ctx || typeof ctx.registerTool !== "function") {
         logger.debug("modelContext unavailable; registration skipped");
         return { registered: [], reason: "unsupported" };

package/src/internal/webmcp-mutations.ts

@@ -1,43 +0,0 @@
-import { readFileSync } from "node:fs";
-import type { Plugin } from "vite";
-import { affectsDeclarativeTools } from "../scripts/webmcp-mutations";
-
-const observer = "const observer = new MutationObserver(sync);";
-
-/** Upstream 5.1.0 rescans every element even for unrelated clock/background mutations. */
-export function optimizeWebMcpMutations(code: string, version: string): string | undefined {
-    if (
-        version !== "5.1.0" ||
-        !code.includes("function installDeclarativeForms(document, context)") ||
-        code.split(observer).length !== 2
-    )
-        return;
-    return code.replace(
-        observer,
-        `const relevant = ${affectsDeclarativeTools.toString()};\nconst observer = new MutationObserver((records) => { if (relevant(records)) sync(); });`,
-    );
-}
-
-export function webMcpMutationsPlugin(): Plugin {
-    const entry = Bun.resolveSync(
-        "@mcp-b/webmcp-polyfill",
-        Bun.fileURLToPath(new URL(".", import.meta.url)),
-    );
-    const version = (
-        JSON.parse(
-            readFileSync(
-                Bun.fileURLToPath(new URL("../package.json", Bun.pathToFileURL(entry))),
-                "utf8",
-            ),
-        ) as { version: string }
-    ).version;
-    return {
-        name: "stalux:webmcp-mutations",
-        enforce: "pre",
-        transform(code, id) {
-            if (!id.replaceAll("\\", "/").endsWith("/@mcp-b/webmcp-polyfill/dist/index.js")) return;
-            const optimized = optimizeWebMcpMutations(code, version);
-            if (optimized) return { code: optimized, map: null };
-        },
-    };
-}

package/src/scripts/webmcp-mutations.ts

@@ -1,27 +0,0 @@
-/** A clock tick or background fade cannot change declarative tool definitions. */
-export function affectsDeclarativeTools(records: MutationRecord[]): boolean {
-    const selector = "form[toolname],[form],label,slot";
-    const containsTools = (node: Node): boolean => {
-        if (!(node instanceof Element)) return false;
-        if (Element.prototype.matches.call(node, selector)) return true;
-        if (Element.prototype.querySelector.call(node, selector)) return true;
-        // An already-created open shadow tree can be inserted along with its host.
-        for (const element of [node, ...Element.prototype.querySelectorAll.call(node, "*")]) {
-            if (Reflect.get(Element.prototype, "shadowRoot", element)) return true;
-        }
-        return false;
-    };
-    return records.some((record) => {
-        if (
-            record.type === "attributes" &&
-            (record.attributeName === "form" || record.attributeName === "toolname")
-        )
-            return true;
-        const element =
-            record.target instanceof Element ? record.target : record.target.parentElement;
-        if (element && Element.prototype.closest.call(element, selector)) return true;
-        if (record.type === "childList")
-            return [...record.addedNodes, ...record.removedNodes].some(containsTools);
-        return false;
-    });
-}