@xingwangzhe/stalux 1.35.15 → 1.36.0

package/src/plugins/image-captions.ts

@@ -0,0 +1,117 @@
+import { parseFragment } from "parse5";
+import { defineHastPlugin, type HastNode } from "satteri";
+
+declare module "satteri" {
+    interface DataMap {
+        staluxCaptionExclusions?: Set<number>;
+    }
+}
+
+type Element = Extract<HastNode, { type: "element" }>;
+
+function onlyElement(node: Element): Element | undefined {
+    const children = node.children.filter(
+        (child) => child.type !== "text" || child.value.trim().length > 0,
+    );
+    return children.length === 1 && children[0]?.type === "element" ? children[0] : undefined;
+}
+
+// Raw HTML wrappers remain sibling raw nodes in Markdown HAST. Parse a small
+// structural shell to recognize paragraphs inside those wrappers as well.
+function rawExclusions(root: Readonly<HastNode>): Set<number> {
+    const excluded = new Set<number>();
+    function scan(node: Readonly<HastNode>) {
+        if (!("children" in node)) return;
+        const children = node.children;
+        if (children.some((child) => child.type === "raw")) {
+            const shell = children
+                .map((child, index) =>
+                    child.type === "raw"
+                        ? child.value
+                        : `<span data-caption-index="${index}"></span>`,
+                )
+                .join("\n");
+            const fragment = parseFragment(shell);
+            function visit(
+                current: typeof fragment | (typeof fragment.childNodes)[number],
+                protectedParent = false,
+            ) {
+                const protectedNode =
+                    protectedParent ||
+                    ("tagName" in current &&
+                        ["figure", "figcaption", "pre", "code", "template"].includes(
+                            current.tagName,
+                        ));
+                if (protectedNode && "attrs" in current) {
+                    const index = current.attrs.find((attr) => attr.name === "data-caption-index");
+                    const child = index ? children[Number(index.value)] : undefined;
+                    const offset = child?.position?.start.offset;
+                    if (offset !== undefined) excluded.add(offset);
+                }
+                if ("childNodes" in current)
+                    for (const child of current.childNodes) visit(child, protectedNode);
+                if ("content" in current) visit(current.content, protectedNode);
+            }
+            visit(fragment);
+        }
+        for (const child of children) scan(child);
+    }
+    scan(root);
+    return excluded;
+}
+
+/** Runs after PhotoSwipe so its link and all image properties remain intact. */
+export const imageCaptions = defineHastPlugin({
+    name: "stalux-image-captions",
+    options: { position: true },
+    before(root, ctx) {
+        ctx.data.staluxCaptionExclusions = rawExclusions(root);
+    },
+    after(_root, ctx) {
+        delete ctx.data.staluxCaptionExclusions;
+    },
+    element: {
+        filter: ["p"],
+        visit(node, ctx) {
+            const offset = node.position?.start.offset;
+            if (offset !== undefined && ctx.data.staluxCaptionExclusions?.has(offset)) return;
+            for (
+                let parent: Readonly<HastNode> | undefined = ctx.parent(node);
+                parent;
+                parent = ctx.parent(parent)
+            ) {
+                if (
+                    parent.type === "element" &&
+                    ["figure", "figcaption", "pre", "code", "template"].includes(parent.tagName)
+                ) {
+                    return;
+                }
+            }
+
+            const content = onlyElement(node);
+            if (!content) return;
+            const image = content.tagName === "a" ? onlyElement(content) : content;
+            if (image?.tagName !== "img") return;
+            const caption = String(image.properties.alt ?? "").trim();
+            if (!caption) return;
+
+            ctx.replaceNode(node, {
+                type: "element",
+                tagName: "figure",
+                properties: {
+                    ...node.properties,
+                    "data-stalux-image": "",
+                },
+                children: [
+                    content,
+                    {
+                        type: "element",
+                        tagName: "figcaption",
+                        properties: {},
+                        children: [{ type: "text", value: caption }],
+                    },
+                ],
+            });
+        },
+    },
+});

package/src/scripts/analytics-runtime.ts

@@ -1,124 +1,139 @@
-/**
- * Keep analytics trackers in Partytown. This small main-thread bridge owns the
- * Astro navigation lifecycle and tells the worker about each completed page.
- */
+/** Async native SDKs keep live DOM events out of worker proxies during Astro swaps. */
+
+import { createClientLogger } from "./logger";
+
+const logger = createClientLogger("analytics");
+
 declare global {
     interface Window {
         __staluxAnalyticsRuntime?: {
             installed?: boolean;
+            native?: boolean;
+            revision?: number;
+            scripts?: Map<string, Promise<void>>;
             googleId?: string;
             googleInitialized?: boolean;
             clarityId?: string;
-            umamiKey?: string;
             previousPage?: string;
         };
     }
 }
 
+type AnalyticsHost = Window & {
+    dataLayer?: unknown[];
+    gtag?: (...args: unknown[]) => void;
+    clarity?: ((...args: unknown[]) => void) & { q: unknown[] };
+    umami?: { track: (payload: Record<string, unknown>) => unknown };
+};
+const host = window as AnalyticsHost;
 window.__staluxAnalyticsRuntime ??= {};
 const state = window.__staluxAnalyticsRuntime;
+state.scripts ??= new Map();
 
-function appendWorkerInline(code: string): void {
+/** Never await analytics in a router callback; failed loads can retry on a later page. */
+function loadTrackerScript(src: string, attributes: Record<string, string> = {}): Promise<void> {
+    const existing = state.scripts?.get(src);
+    if (existing) return existing;
     const script = document.createElement("script");
-    script.type = "text/partytown";
-    script.textContent = code;
-    document.head.appendChild(script);
-    window.dispatchEvent(new CustomEvent("ptupdate"));
-}
-
-function appendWorkerScript(src: string, attributes: Record<string, string> = {}): void {
-    const script = document.createElement("script");
-    script.type = "text/partytown";
+    script.async = true;
+    script.fetchPriority = "low";
     script.src = src;
     for (const [name, value] of Object.entries(attributes)) script.setAttribute(name, value);
-    document.head.appendChild(script);
-    window.dispatchEvent(new CustomEvent("ptupdate"));
+    const loaded = new Promise<void>((resolve, reject) => {
+        const finish = (error?: Error) => {
+            clearTimeout(timer);
+            script.onload = null;
+            script.onerror = null;
+            if (error) {
+                script.remove();
+                reject(error);
+            } else resolve();
+        };
+        const timer = setTimeout(() => finish(new Error("Analytics SDK load timed out")), 15_000);
+        script.onload = () => finish();
+        script.onerror = () => finish(new Error("Analytics SDK load failed"));
+        document.head.appendChild(script);
+    });
+    state.scripts?.set(src, loaded);
+    void loaded.catch(() => {
+        if (state.scripts?.get(src) === loaded) state.scripts.delete(src);
+    });
+    return loaded;
 }
 
 function initializeTrackers(): void {
     const config = document.body?.dataset;
     if (!config) return;
-
     if (config.staluxGaId) {
+        if (state.googleId !== config.staluxGaId) state.googleInitialized = false;
         state.googleId = config.staluxGaId;
+        host.dataLayer ??= [];
+        host.gtag ??= function (..._args: unknown[]) {
+            // biome-ignore lint/complexity/noArguments: Match the official gtag queue format.
+            host.dataLayer?.push(arguments);
+        };
+        if (!state.googleInitialized) {
+            state.googleInitialized = true;
+            host.gtag("js", new Date());
+            host.gtag("config", state.googleId, { send_page_view: false });
+        }
+        void loadTrackerScript(
+            `https://www.googletagmanager.com/gtag/js?id=${encodeURIComponent(state.googleId)}`,
+            { "data-stalux-google": "true" },
+        ).catch(() => logger.debug("Google SDK unavailable; queued events retained"));
     }
-
     if (config.staluxClarityId && state.clarityId !== config.staluxClarityId) {
-        state.clarityId = config.staluxClarityId;
-        appendWorkerInline(`
-            window.clarity = window.clarity || function () {
-                (window.clarity.q = window.clarity.q || []).push(arguments);
-            };
-            window.clarity.q = window.clarity.q || [];
-        `);
-        appendWorkerScript(`https://www.clarity.ms/tag/${encodeURIComponent(state.clarityId)}`, {
+        host.clarity ??= Object.assign(
+            function (..._args: unknown[]) {
+                // biome-ignore lint/complexity/noArguments: Match the official Clarity queue format.
+                host.clarity?.q.push(arguments);
+            },
+            { q: [] as unknown[] },
+        );
+        const id = config.staluxClarityId;
+        state.clarityId = id;
+        void loadTrackerScript(`https://www.clarity.ms/tag/${encodeURIComponent(id)}`, {
             "data-stalux-clarity": "true",
-        });
-    }
-
-    if (
-        config.staluxUmamiId &&
-        config.staluxUmamiUrl &&
-        state.umamiKey !== `${config.staluxUmamiId}\n${config.staluxUmamiUrl}`
-    ) {
-        state.umamiKey = `${config.staluxUmamiId}\n${config.staluxUmamiUrl}`;
-        appendWorkerScript(config.staluxUmamiUrl, {
-            "data-stalux-umami": "true",
-            "data-website-id": config.staluxUmamiId,
-            "data-auto-pageview": "false",
+        }).catch(() => {
+            if (state.clarityId === id) state.clarityId = undefined;
+            logger.debug("Clarity SDK unavailable; a later navigation can retry");
         });
     }
 }
 
 function trackGooglePage(): void {
     if (!state.googleId) return;
-    const page = {
+    host.gtag?.("event", "page_view", {
         page_location: window.location.href,
         page_path: window.location.pathname + window.location.search,
         page_title: document.title,
-    };
-    const initialize = !state.googleInitialized;
-    state.googleInitialized = true;
-    appendWorkerInline(`
-        // Partytown 0.14 serializes HTMLCollection as its worker NodeList.
-        // GA user-data detection checks instanceof HTMLCollection before sending page_view.
-        window.HTMLCollection = window.HTMLCollection || window.NodeList;
-        window.dataLayer = window.dataLayer || [];
-        window.gtag = function () { window.dataLayer.push(arguments); };
-        ${initialize ? `window.gtag("js", new Date());window.gtag("config", ${JSON.stringify(state.googleId)}, { send_page_view: false });` : ""}
-        window.gtag("event", "page_view", ${JSON.stringify(page)});
-    `);
-    if (initialize)
-        appendWorkerScript(
-            `https://www.googletagmanager.com/gtag/js?id=${encodeURIComponent(state.googleId)}`,
-            { "data-stalux-google": "true" },
-        );
+    });
 }
 
 function trackUmamiPage(): void {
-    const id = document.body?.dataset.staluxUmamiId;
-    if (!id || !state.umamiKey) return;
-    const payload = JSON.stringify({
-        website: id,
+    const config = document.body?.dataset;
+    if (!config?.staluxUmamiId || !config.staluxUmamiUrl) return;
+    // Snapshot now: a slow SDK must not attribute every queued visit to the last URL.
+    const payload = {
+        website: config.staluxUmamiId,
         url: window.location.href,
         title: document.title,
         hostname: window.location.hostname,
         screen: `${window.screen.width}x${window.screen.height}`,
         language: navigator.language,
         referrer: state.previousPage ?? document.referrer,
-    });
-    appendWorkerInline(`
-        (function send(attempt) {
-            if (window.umami?.track) window.umami.track(${payload});
-            else if (attempt < 50) setTimeout(() => send(attempt + 1), 100);
-        })(0);
-    `);
+    };
+    void loadTrackerScript(config.staluxUmamiUrl, {
+        "data-stalux-umami": "true",
+        "data-website-id": config.staluxUmamiId,
+        // Keep SDK click/performance features; only pageviews belong to Astro's lifecycle.
+        "data-auto-pageview": "false",
+    })
+        .then(() => host.umami?.track(payload))
+        .catch(() => logger.debug("Umami SDK unavailable; navigation remains usable"));
 }
 
 function trackVercountPage(): void {
-    // Visible counters need the current window's URL, cookie and DOM nodes.
-    // Avoid worker startup and synchronous DOM bridges; bind fresh nodes once
-    // per completed Astro navigation using the small upstream async script.
     document.querySelector("script[data-stalux-vercount]")?.remove();
     const script = document.createElement("script");
     script.async = true;
@@ -127,36 +142,14 @@ function trackVercountPage(): void {
     document.head.appendChild(script);
 }
 
-if (!state.installed) {
+if (state.installed && (!state.native || state.revision !== 2)) {
+    // An open tab can cross a deployment boundary. Its old anonymous worker
+    // listeners cannot be detached safely; reload once to install the new runtime.
+    window.location.reload();
+} else if (!state.installed) {
+    state.native = true;
+    state.revision = 2;
     state.installed = true;
-    let sandbox: HTMLIFrameElement | undefined;
-    // Moving an iframe with append() reloads its browsing context. Park it outside
-    // the replaced body with moveBefore(), which preserves the running worker.
-    // Capture runs before @astrojs/partytown's iframe recreation handler.
-    document.addEventListener(
-        "astro:before-swap",
-        () => {
-            const frame = document.body.querySelector<HTMLIFrameElement>(
-                'iframe[src*="~partytown/"]',
-            );
-            if (frame && typeof document.documentElement.moveBefore === "function") {
-                sandbox = frame;
-                document.documentElement.moveBefore(frame, null);
-            } else if (!window.crossOriginIsolated) {
-                // Atomics mode has no sandbox iframe and keeps its worker alive.
-                state.googleInitialized = false;
-                state.clarityId = undefined;
-                state.umamiKey = undefined;
-            }
-        },
-        true,
-    );
-    document.addEventListener("astro:after-swap", () => {
-        if (sandbox) {
-            document.body.moveBefore(sandbox, null);
-            sandbox = undefined;
-        }
-    });
     document.addEventListener("astro:page-load", () => {
         initializeTrackers();
         trackGooglePage();
@@ -165,5 +158,3 @@ if (!state.installed) {
         state.previousPage = window.location.href;
     });
 }
-
-export {};

package/src/scripts/archive-descriptions.ts

@@ -12,13 +12,24 @@ export function getArchiveDescriptionPosition(
     height: number,
     viewportWidth: number,
     viewportHeight: number,
-) {
+): { left: number; top: number; maxHeight?: number } {
     const fitsRight = anchor.right + 12 + width <= viewportWidth - 16;
     const left = fitsRight ? anchor.right + 12 : anchor.left;
-    const top = fitsRight ? anchor.top : anchor.bottom + 8;
+    let top = fitsRight ? anchor.top : anchor.bottom + 8;
+    let maxHeight: number | undefined;
+    if (!fitsRight && top + height > viewportHeight - 16) {
+        const above = Math.max(0, anchor.top - 24);
+        const below = Math.max(0, viewportHeight - anchor.bottom - 24);
+        const useBelow = below >= above;
+        const available = useBelow ? below : above;
+        const visibleHeight = Math.min(height, available);
+        top = useBelow ? anchor.bottom + 8 : anchor.top - visibleHeight - 8;
+        if (visibleHeight < height) maxHeight = visibleHeight;
+    }
     return {
         left: Math.max(16, Math.min(left, viewportWidth - width - 16)),
-        top: Math.max(16, Math.min(top, viewportHeight - height - 16)),
+        top: Math.max(16, fitsRight ? Math.min(top, viewportHeight - height - 16) : top),
+        ...(maxHeight === undefined ? {} : { maxHeight }),
     };
 }
 
@@ -71,7 +82,8 @@ export function mountArchiveDescriptions() {
             tooltip.showPopover();
             popoverOpen = true;
         }
-        const { left, top } = getArchiveDescriptionPosition(
+        tooltip.style.maxHeight = "";
+        const { left, top, maxHeight } = getArchiveDescriptionPosition(
             link.getBoundingClientRect(),
             tooltip.offsetWidth,
             tooltip.offsetHeight,
@@ -80,6 +92,7 @@ export function mountArchiveDescriptions() {
         );
         tooltip.style.left = `${left}px`;
         tooltip.style.top = `${top}px`;
+        if (maxHeight !== undefined) tooltip.style.maxHeight = `${maxHeight}px`;
     };
     const linkFrom = (target: EventTarget | null) =>
         target instanceof Element
@@ -88,6 +101,9 @@ export function mountArchiveDescriptions() {
     const enter = (event: Event) => {
         if (event.type === "pointerover" && !hover.matches) return;
         const link = linkFrom(event.target);
+        // Touch/mouse focus must not put a top-layer popover under the pending click.
+        // Keyboard focus still exposes the same accessible preview.
+        if (event.type === "focusin" && !link?.matches(":focus-visible")) return;
         if (link && root.contains(link)) show(link);
     };
     const leave = (event: Event) => {
@@ -102,6 +118,9 @@ export function mountArchiveDescriptions() {
     const handleEscape = (event: KeyboardEvent) => {
         if (event.key === "Escape") hide();
     };
+    const navigate = (event: Event) => {
+        if (linkFrom(event.target)) hide();
+    };
     const scroll = (event: Event) => {
         if (event.target instanceof Node && tooltip.contains(event.target)) return;
         hide();
@@ -113,6 +132,7 @@ export function mountArchiveDescriptions() {
     root.addEventListener("pointerout", leave);
     root.addEventListener("focusin", enter);
     root.addEventListener("focusout", leave);
+    root.addEventListener("click", navigate, true);
     tooltip.addEventListener("pointerenter", clearClose);
     tooltip.addEventListener("pointerleave", hide);
     document.addEventListener("keydown", handleEscape);
@@ -127,6 +147,7 @@ export function mountArchiveDescriptions() {
         root.removeEventListener("pointerout", leave);
         root.removeEventListener("focusin", enter);
         root.removeEventListener("focusout", leave);
+        root.removeEventListener("click", navigate, true);
         tooltip.removeEventListener("pointerenter", clearClose);
         tooltip.removeEventListener("pointerleave", hide);
         document.removeEventListener("keydown", handleEscape);

package/src/scripts/background.ts

@@ -10,7 +10,7 @@
  * - SSR 只渲染灰墙底色（--stalux-bg-color），不渲染任何背景图，构建产物确定。
  * - 首次加载与 VT 软导航每次都会随机选一张背景：astro:page-load 在
  *   window load（首访）与 swap 完成后、过渡动画期间（软导航）触发，
- *   此时设置背景，过渡动画中旧图淡出、新图淡入，自然 crossfade 无跳变。
+ *   先低优先级解码目标背景，等待内容过渡完成后再淡入，不与内容快照争抢绘制。
  */
 import { createClientLogger } from "./logger";
 
@@ -57,13 +57,9 @@ function pickBackgroundIndex(previous: number): number {
     return index;
 }
 
-function crossfadeBackground(): void {
-    if (backgroundImages.length === 0) return;
-
+function crossfadeBackground(index: number): void {
     const activeLayer = getActiveLayer();
     const nextLayer: "a" | "b" = activeLayer === "a" ? "b" : "a";
-    const previousIndex = Number(document.body.dataset.staluxBgIndex ?? -1);
-    const index = pickBackgroundIndex(previousIndex);
     const next = getLayerEl(nextLayer);
     if (!next || !backgroundImages[index]) {
         logger.debug("background layer unavailable; skipped");
@@ -78,17 +74,49 @@ function crossfadeBackground(): void {
     document.body.dataset.staluxBgLayer = nextLayer;
 }
 
+let generation = 0;
+let prepared: Promise<number | undefined> | undefined;
+let transitionFinished: Promise<unknown> = Promise.resolve();
+
+function prepareBackground(): Promise<number | undefined> {
+    const previousIndex = Number(document.body.dataset.staluxBgIndex ?? -1);
+    const index = pickBackgroundIndex(previousIndex);
+    const image = new Image();
+    image.decoding = "async";
+    image.fetchPriority = "low";
+    image.src = backgroundImages[index] ?? "";
+    return image.decode().then(
+        () => index,
+        () => undefined,
+    );
+}
+
 function initializeBackground(): void {
     const active = getLayerEl(getActiveLayer());
-    if (active?.style.backgroundImage) return;
-    crossfadeBackground();
+    if (!prepared && active?.style.backgroundImage) return;
+    const current = generation;
+    const ready = prepared ?? prepareBackground();
+    prepared = undefined;
+    // Decode off the navigation path, and keep the full-screen background repaint
+    // out of the content's View Transition. A superseded navigation never commits.
+    void Promise.all([ready, transitionFinished]).then(([index]) => {
+        if (current === generation && index !== undefined) crossfadeBackground(index);
+    });
 }
 
-// before-swap 在 View Transition 的快照之后、DOM 替换之前触发；背景层使用
-// transition:persist 保留，因此可以在页面内容交换期间完成双层 crossfade。
-// 非 VT 浏览器也会触发该生命周期，fallback 同样保持平滑。
+// 背景层跨页保留；before-swap 只记录过渡完成信号，不阻塞或修改内容快照。
+// page-load 再提交已解码的背景，非 VT 浏览器也采用同一清理/去重流程。
 if (!(window as Window & { __STALUX_BG_LISTENER__?: boolean }).__STALUX_BG_LISTENER__) {
     (window as Window & { __STALUX_BG_LISTENER__?: boolean }).__STALUX_BG_LISTENER__ = true;
-    document.addEventListener("astro:before-swap", crossfadeBackground);
+    document.addEventListener("astro:before-preparation", () => {
+        generation++;
+        const connection = (navigator as Navigator & { connection?: { saveData?: boolean } })
+            .connection;
+        prepared = connection?.saveData ? undefined : prepareBackground();
+    });
+    document.addEventListener("astro:before-swap", (event) => {
+        const transition = (event as Event & { viewTransition?: ViewTransition }).viewTransition;
+        transitionFinished = transition?.finished.catch(() => undefined) ?? Promise.resolve();
+    });
     document.addEventListener("astro:page-load", initializeBackground);
 }

package/src/scripts/code-accessibility.ts

@@ -0,0 +1,31 @@
+/** Preserve EC's keyboard scroll access when an offscreen code subtree becomes rendered. */
+export function mountCodeAccessibility(target: Document = document): (() => void) | undefined {
+    const selector = "code[data-stalux-offscreen-code]";
+    const codes = [...target.querySelectorAll<HTMLElement>(selector)];
+    if (!codes.length) return;
+    const update = (code: HTMLElement) => {
+        if (!code.isConnected) return;
+        const rendered =
+            typeof code.checkVisibility === "function"
+                ? code.checkVisibility({ contentVisibilityAuto: true })
+                : true;
+        if (!rendered) return;
+        const pre = code.parentElement;
+        if (
+            pre?.tagName === "PRE" &&
+            pre.scrollWidth > pre.clientWidth &&
+            !pre.hasAttribute("tabindex")
+        ) {
+            pre.setAttribute("tabindex", "0");
+            if (!pre.hasAttribute("role")) pre.setAttribute("role", "region");
+        }
+    };
+    const reveal = (event: Event) => {
+        if ((event as Event & { skipped?: boolean }).skipped) return;
+        if (event.target instanceof HTMLElement && event.target.matches(selector))
+            update(event.target);
+    };
+    for (const code of codes) update(code);
+    target.addEventListener("contentvisibilityautostatechange", reveal, true);
+    return () => target.removeEventListener("contentvisibilityautostatechange", reveal, true);
+}

package/src/scripts/navigation-font.ts

@@ -1,20 +1,46 @@
-/** Warm the destination font while the old page is still visible. Never delay navigation indefinitely. */
+// Retain decoded faces across back/forward visits, without installing them in the old document.
+// Bound this session cache: a blog reader can visit hundreds of distinct page subsets.
+const fonts = new Map<string, { face: FontFace; ready: Promise<FontFace> }>();
+const MAX_FONTS = 16;
+
+function warmFont(href: string): Promise<FontFace> {
+    const cached = fonts.get(href);
+    if (cached) {
+        fonts.delete(href);
+        fonts.set(href, cached);
+        return cached.ready;
+    }
+    const face = new FontFace("LXGW WenKai-Page Subset", `url(${JSON.stringify(href)})`, {
+        style: "normal",
+        weight: "100 900",
+    });
+    const ready = face.load();
+    fonts.set(href, { face, ready });
+    if (fonts.size > MAX_FONTS) fonts.delete(fonts.keys().next().value as string);
+    void ready.catch(() => {
+        if (fonts.get(href)?.ready === ready) fonts.delete(href);
+    });
+    return ready;
+}
+
+/** Give a cached font a short head start; a slow font must not hold the destination page hostage. */
 export async function prepareNavigationFont(
     nextDocument: Document,
     signal: AbortSignal,
-    timeoutMs = 1000,
+    timeoutMs = 150,
 ): 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",
-    });
+    let ready: Promise<FontFace>;
+    try {
+        const url = new URL(href, window.location.href);
+        if (url.origin !== window.location.origin) return;
+        ready = warmFont(url.href);
+    } catch {
+        return;
+    }
     await new Promise<void>((resolve) => {
         const finish = () => {
             clearTimeout(timer);
@@ -23,6 +49,6 @@ export async function prepareNavigationFont(
         };
         const timer = setTimeout(finish, timeoutMs);
         signal.addEventListener("abort", finish, { once: true });
-        void face.load().then(finish, finish);
+        void ready.then(finish, finish);
     });
 }

package/src/scripts/webmcp-mutations.ts

@@ -0,0 +1,27 @@
+/** 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;
+    });
+}