@xingwangzhe/stalux 1.35.15 → 1.36.0

package/README.md

@@ -14,6 +14,10 @@ All HTML routes include a circular back-to-top button in the footer. It appears
 
 The homepage typewriter is built into Stalux and continues to use the `items` string list in `stalux/config/typetexts.yml`, with no new configuration. Defaults are 100ms per typed grapheme, 33ms per deleted grapheme, a 1500ms hold, and a 500ms pause after deletion. It pauses outside the viewport or in background tabs and cleans up on soft navigation. Reduced motion displays whole messages without a blinking cursor. Without JavaScript, the first message remains visible; screen readers and print receive the complete list.
 
+Standalone images written as `![Image description](url)` receive a `figure` and `figcaption` through a build-time satteri HAST plugin. Captions appear as small, centered gray text below the image, preserving image alt text and the PhotoSwipe lightbox. No configuration or browser script is required. Empty descriptions, inline images, multiple images in one paragraph, and existing figures are left unchanged. Captions are plain text with automatic escaping.
+
+Code blocks default to the single `dark-plus` theme, with system color-scheme switching and theme selectors disabled. To opt into another theme or switching behavior, explicitly override `themes`, `useDarkModeMediaQuery`, and `themeCssSelector` through `expressiveCode`. This only changes generated code styles and adds no telemetry.
+
 ---
 
 ## 🚀 Quick Start
@@ -57,7 +61,7 @@ integrations: [
     stalux({
         contentDir: "stalux",
         sitemap: { filter: (page) => page.startsWith("https://example.com/posts/") },
-        expressiveCode: { themes: ["dark-plus", "github-light"] },
+        expressiveCode: { themes: ["dark-plus"], useDarkModeMediaQuery: false },
     }),
 ];
 ```
@@ -183,13 +187,11 @@ id: head
 bingClarityId: "YOUR_CLARITY_PROJECT_ID"
 ```
 
-> The Partytown migration in this branch is an unpublished candidate. Representative route measurements show lower TBT, but LCP regresses on the homepage and category page, so performance validation is incomplete. The following describes the candidate implementation.
-
-`stalux()` includes Partytown. The Google Analytics, Clarity, and Umami scripts run in a Web Worker without an additional consumer integration. Page tracking follows `astro:page-load`; browsers with `Element.moveBefore()` preserve the worker during navigation. Vercount loads asynchronously in the main window, avoiding worker startup and DOM bridge delays for visible counters. It runs once after each `astro:page-load` to bind incoming page counters and use the current URL and first-party visitor cookie.
+Google Analytics, Clarity, and Umami use low-priority native asynchronous scripts. Each SDK loads once per session, and failures do not block reading or navigation. Vercount rebinds visible counters after each `astro:page-load`. GA sends explicit pageviews. Umami disables automatic pageviews while retaining click tracking, capturing each page's URL, title, and referrer before the SDK resolves so rapid navigation cannot mix visits. An existing legacy Partytown session performs one full reload when it encounters the new runtime to prevent duplicate listeners and tracking.
 
 For Google Analytics, turn off **Page changes based on browser history events** under **Admin → Data streams → Enhanced measurement → Page views → Advanced settings**. Stalux sets `send_page_view: false` and sends the URL and title for each navigation explicitly. GA's history tracking must also be disabled in the property to prevent duplicate soft-navigation pageviews. Other enhanced measurement options can remain enabled. See [Google's pageview documentation](https://developers.google.com/analytics/devguides/collection/ga4/views).
 
-`bingClarityId` is the historical Stalux field name for a Microsoft Clarity Project ID. Get the ID from the Clarity project under **Settings → Setup → Get tracking code**. Stalux loads the tracking code through Partytown and keeps one loader in browsers that support preserving the worker. Do not install the same project again through `anyhead`, a tag manager, or another plugin.
+`bingClarityId` is the historical Stalux field name for a Microsoft Clarity Project ID. Get the ID from the Clarity project under **Settings → Setup → Get tracking code**. Stalux loads the tracking code asynchronously and preserves one loader across soft navigation. The SDK handles history navigation itself. Do not install the same project again through `anyhead`, a tag manager, or another plugin.
 
 The Project ID is a public browser identifier. Never put a Clarity Data Export API token in this YAML or in client-side code. If the site uses a strict CSP, consent banner, or CMP, configure those host-site policies and signals separately; this theme does not make legal compliance decisions for the site.
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@xingwangzhe/stalux",
-    "version": "1.35.15",
+    "version": "1.36.0",
     "description": "A powerful, modern Astro blog theme — use as template or install as plugin",
     "keywords": [
         "astro",
@@ -26,6 +26,7 @@
         "stalux": ".release/cli.mjs"
     },
     "files": [
+        "src/env.d.ts",
         "src/index.ts",
         "src/config.ts",
         "src/expressive-code.ts",
@@ -101,7 +102,6 @@
     "dependencies": {
         "@astrojs/compiler": "^4.0.0",
         "@astrojs/markdown-satteri": "^0.4.3",
-        "@astrojs/partytown": "^2.1.8",
         "@astrojs/rss": "^4.0.19",
         "@astrojs/sitemap": "^3.7.4",
         "@expressive-code/plugin-line-numbers": "^0.44.2",

package/src/components/stalux/archives/archivesList.astro

@@ -66,13 +66,7 @@ const archiveYears = [...archivesByYearMonth.entries()]
                             </div>
                         </div>
                         {archiveYear.months.map(({ month, posts: monthPosts }) => (
-                            <div
-                                class="stalux-archive-month-section"
-                                data-archive-month
-                                style={{
-                                    "--archive-estimate": `${Math.ceil(monthPosts.length / 12) * 12 * 48 + 40}px`,
-                                }}
-                            >
+                            <div class="stalux-archive-month-section" data-archive-month>
                                 <h3 class="stalux-archive-month-title">
                                     {t("archives.month", { n: month })}
                                 </h3>
@@ -80,12 +74,7 @@ const archiveYears = [...archivesByYearMonth.entries()]
                                     { length: Math.ceil(monthPosts.length / 12) },
                                     (_, index) => monthPosts.slice(index * 12, (index + 1) * 12),
                                 ).map((group) => (
-                                    <ul
-                                        class="stalux-archive-post-list"
-                                        style={{
-                                            "--archive-group-estimate": `${group.length * 48}px`,
-                                        }}
-                                    >
+                                    <ul class="stalux-archive-post-list">
                                         {group.map((post) => (
                                             <li class="stalux-archive-post-item">
                                                 <time

package/src/components/stalux/layout/head.astro

@@ -2,13 +2,13 @@
 import { Font } from "astro:assets";
 import { getCollection } from "astro:content";
 import { ClientRouter } from "astro:transitions";
+// Emit a stable asset even while the search component JavaScript stays lazy.
+// The closed search dialog does not need to block the page's first paint.
+import pagefindStyles from "virtual:stalux-search-style";
 import BingClarity from "@components/stalux/analytics/clarity.astro";
 import GoogleAnalytics from "@components/stalux/analytics/google.astro";
 import Umami from "@components/stalux/analytics/umami.astro";
 import VerCount from "@components/stalux/common/verCount.astro";
-// Emit a stable asset even while the search component JavaScript stays lazy.
-// The closed search dialog does not need to block the page's first paint.
-import pagefindStyles from "@pagefind/component-ui/css?url";
 import {
     getAuthorData,
     getHeadData,

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

@@ -118,4 +118,10 @@ const mdSourceUrl = exportMd ? `${Astro.url.pathname.replace(/\/$/, "")}.md` : "
     </section>
 </article>
 
-<script src="../../../scripts/photoswipe.ts"></script>
+<script>
+import "../../../scripts/photoswipe";
+import { mountCodeAccessibility } from "../../../scripts/code-accessibility";
+import { registerPageLifecycle } from "../../../scripts/page-runtime";
+
+registerPageLifecycle("code-accessibility", mountCodeAccessibility);
+</script>

package/src/config.ts

@@ -66,7 +66,7 @@ export interface StaluxOptions {
     sitemap?: boolean | SitemapOptions;
 
     /**
-     * 是否自动打包 Expressive Code（默认 true，带代码块行号插件）。
+     * 是否自动打包 Expressive Code（默认 true，带代码块行号插件，固定 dark-plus 暗色主题）。
      * 传 false 关闭；传对象自定义主题/样式等选项。
      */
     expressiveCode?: boolean | ExpressiveCodeOptions;

package/src/env.d.ts

@@ -0,0 +1,9 @@
+/// <reference types="astro/client" />
+
+declare module "*.css";
+declare module "@pagefind/component-ui/css";
+declare module "@waline/client/style";
+declare module "virtual:stalux-search-style" {
+    const href: string;
+    export default href;
+}

package/src/expressive-code.ts

@@ -16,6 +16,7 @@
  */
 import { pluginLineNumbers } from "@expressive-code/plugin-line-numbers";
 import expressiveCodeBase from "astro-expressive-code";
+import { codeContainmentPlugin } from "./internal/offscreen-layout";
 
 export type ExpressiveCodeOptions = NonNullable<Parameters<typeof expressiveCodeBase>[0]>;
 
@@ -24,8 +25,14 @@ export type ExpressiveCodeOptions = NonNullable<Parameters<typeof expressiveCode
  * @param options - 透传 astro-expressive-code 的选项；用户传入的 plugins 会追加在行号插件之后
  */
 export function expressiveCode(options: ExpressiveCodeOptions = {}) {
-    const plugins = [pluginLineNumbers(), ...(options.plugins ?? [])];
-    return expressiveCodeBase({ ...options, plugins });
+    const plugins = [pluginLineNumbers(), ...(options.plugins ?? []), codeContainmentPlugin()];
+    return expressiveCodeBase({
+        themes: ["dark-plus"],
+        useDarkModeMediaQuery: false,
+        themeCssSelector: false,
+        ...options,
+        plugins,
+    });
 }
 
 /** @alias Public default-import form of the named integration export. */

package/src/index.ts

@@ -1,3 +1,4 @@
+/// <reference path="./env.d.ts" />
 import { forEachBounded } from "./internal/bounded-tasks.ts";
 import { compactStylesPlugin } from "./internal/compact-styles.ts";
 import { modernCssTargets } from "./internal/modern-css.ts";
@@ -16,7 +17,6 @@ import { copyFileSync, existsSync, promises as fs, readdirSync, readFileSync } f
 import { createRequire } from "node:module";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import partytown from "@astrojs/partytown";
 import sitemap from "@astrojs/sitemap";
 import { mermaidHast, mermaidMdast } from "@xingwangzhe/satteri-mermaid";
 import { photoswipe } from "@xingwangzhe/satteri-photoswipe";
@@ -39,10 +39,13 @@ import {
 } from "./internal/font-slices";
 import { findHtmlImages } from "./internal/html-images";
 import { createHtmlMutationEmitter } from "./internal/html-output";
+import { promoteCodeStyles } from "./internal/html-styles";
 import { type ImageDimensions, updateLocalImageDimensions } from "./internal/image-dimensions";
 import { createInjectedRoutes } from "./internal/injected-routes";
 import { markdownPropagationPlugin } from "./internal/markdown-propagation";
+import { containMermaidSvgs } from "./internal/offscreen-layout";
 import { createPageOutputCache } from "./internal/page-output-cache";
+import { isPluginProject } from "./internal/project-mode";
 import { syncBackgroundSvgs, syncFontAssets } from "./internal/public-assets";
 import { createRuntimeCacheKey } from "./internal/runtime-cache-key";
 import {
@@ -50,8 +53,11 @@ import {
     collectPluginNames,
     prepareSatteriProcessor,
 } 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 { temml } from "./plugins/satteri-temml";
 import { describeError } from "./utils/diagnostics";
 
@@ -110,9 +116,6 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
         ...options,
     };
 
-    // 探测是否为插件模式（通过 npm 安装）vs 源码开发模式
-    // 安装在 node_modules 中时，页面的文件路由不可用，需要通过 injectRoute 注入
-    const isPluginMode = import.meta.url.includes("node_modules");
     let pageFontData: { fontBuffer: Buffer; outputDir: string; cacheDir: string } | undefined;
 
     const coreIntegration: AstroIntegration = {
@@ -128,6 +131,7 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
                 logger,
             }) => {
                 const started = performance.now();
+                const isPluginMode = isPluginProject(config.root, new URL("../", import.meta.url));
                 const configLogger = logger.fork("stalux/config");
                 const routesLogger = logger.fork("stalux/routes");
                 const markdownLogger = logger.fork("stalux/markdown");
@@ -139,7 +143,8 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
                     path.resolve(srcDir, "../package.json"),
                     path.join(srcDir, "styles"),
                     JSON.stringify([styleNames, modernCssTargets]) +
-                        readFileSync(path.join(srcDir, "internal/compact-styles.ts"), "utf8"),
+                        readFileSync(path.join(srcDir, "internal/compact-styles.ts"), "utf8") +
+                        readFileSync(path.join(srcDir, "internal/offscreen-layout.ts"), "utf8"),
                     path.resolve(fileURLToPath(config.root), opt.contentDir ?? "stalux", "config"),
                 );
 
@@ -152,6 +157,7 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
                             config.build.inlineStylesheets === "always" ? "always" : "never",
                     },
                     vite: {
+                        optimizeDeps: { exclude: ["@mcp-b/webmcp-polyfill"] },
                         css: { lightningcss: { targets: modernCssTargets } },
                         build: {
                             target: config.vite.build?.target ?? "esnext",
@@ -162,6 +168,8 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
                             alias: createViteAliases(srcDir),
                         },
                         plugins: [
+                            searchStylePlugin(command === "dev", config.base),
+                            webMcpMutationsPlugin(),
                             ...(command === "build"
                                 ? [markdownPropagationPlugin(), compactStylesPlugin(srcDir)]
                                 : []),
@@ -218,7 +226,7 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
                 // 消费方即使完全不配置 processor，这里也会对默认 processor 的 options 做幂等合并：
                 //   - features：默认开启 math / frontmatter / gfm / smartPunctuation（用户显式 false 则尊重）
                 //   - mdastPlugins：mermaidMdast + temml（数学公式）+ featureFlagsMdast（字数统计）
-                //   - hastPlugins：photoswipe（图片灯箱）+ mermaidHast + featureFlagsHast
+                //   - hastPlugins：photoswipe（图片灯箱）+ imageCaptions（图注）+ mermaidHast + featureFlagsHast
                 // 去重是必须的：重复注册 Mermaid 或 featureFlagsMdast 会导致渲染异常或字数统计翻倍。
                 try {
                     const processorOptions = prepareSatteriProcessor(config.markdown?.processor);
@@ -242,9 +250,10 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
                             seen,
                         );
                         appendUniquePlugin(processorOptions.hastPlugins, photoswipe(), seen);
+                        appendUniquePlugin(processorOptions.hastPlugins, imageCaptions, seen);
                         appendUniquePlugin(processorOptions.hastPlugins, featureFlagsHast, seen);
                         markdownLogger.debug(
-                            "injected satteri plugins (mermaid/temml/photoswipe/feature-flags)",
+                            "injected satteri plugins (mermaid/temml/photoswipe/image-captions/feature-flags)",
                         );
                     } else {
                         markdownLogger.warn(
@@ -371,6 +380,8 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
                             "internal/image-dimensions.ts",
                             "internal/html-images.ts",
                             "internal/html-output.ts",
+                            "internal/html-styles.ts",
+                            "internal/offscreen-layout.ts",
                             "internal/page-output-cache.ts",
                             "internal/style-names.generated.ts",
                             "plugins/feature-flags.ts",
@@ -419,6 +430,8 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
                     const dependencies = new Set<string>();
                     const document = parse(before, { sourceCodeLocationInfo: true });
                     const emitHtml = createHtmlMutationEmitter(before, document);
+                    promoteCodeStyles(document);
+                    containMermaidSvgs(document);
                     removePageFontStyles(document);
                     const images = findHtmlImages(before, document);
                     await updateLocalImageDimensions(images, outDir, {
@@ -524,13 +537,8 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
     };
 
     // 打包内置集成：Astro 的 integrations 配置支持嵌套数组并自动展平（schema 里 val.flat(Infinity)），
-    // 因此这里返回 [coreIntegration, partytown, sitemap, expressiveCode]，让消费方一行 `integrations: [stalux()]` 即可完成配置。
-    const bundled: AstroIntegration[] = [
-        coreIntegration,
-        partytown({
-            config: { forward: ["dataLayer.push", "gtag"], mainWindowAccessors: ["CSS"] },
-        }),
-    ];
+    // 因此这里返回 [coreIntegration, sitemap, expressiveCode]，让消费方一行 `integrations: [stalux()]` 即可完成配置。
+    const bundled: AstroIntegration[] = [coreIntegration];
 
     if (opt.sitemap !== false) {
         const userSitemap = opt.sitemap === true ? undefined : opt.sitemap;

package/src/internal/html-output.ts

@@ -24,7 +24,10 @@ export function createHtmlMutationEmitter(
             if (node.tagName === "head") head = node;
             const location = node.sourceCodeLocation;
             if (
-                (node.tagName === "img" || node.tagName === "style" || node.tagName === "link") &&
+                (node.tagName === "img" ||
+                    node.tagName === "style" ||
+                    node.tagName === "link" ||
+                    node.tagName === "svg") &&
                 location
             ) {
                 snapshots.push({

package/src/internal/html-styles.ts

@@ -0,0 +1,39 @@
+import { type DefaultTreeAdapterMap, defaultTreeAdapter } from "parse5";
+
+type Element = DefaultTreeAdapterMap["element"];
+
+/** Astro's router preloads head styles only; EC emits its shared CSS inside the first block. */
+export function promoteCodeStyles(document: DefaultTreeAdapterMap["document"]): number {
+    let head: Element | undefined;
+    const links: Element[] = [];
+    function visit(node: DefaultTreeAdapterMap["node"], inCode = false) {
+        if ("tagName" in node) {
+            if (node.tagName === "template" || node.tagName === "noscript") return;
+            if (node.tagName === "head") head = node;
+            inCode ||= (
+                node.attrs.find((a) => a.name === "class")?.value.split(/\s+/) ?? []
+            ).includes("expressive-code");
+            if (
+                inCode &&
+                node.tagName === "link" &&
+                node.attrs.some((a) => a.name === "rel" && a.value === "stylesheet")
+            )
+                links.push(node);
+        }
+        if ("childNodes" in node) for (const child of node.childNodes) visit(child, inCode);
+    }
+    visit(document);
+    if (!head) return 0;
+    for (const link of links) {
+        // Clone metadata without source ranges so the shared mutation emitter can
+        // remove the original bytes and insert the reference without rewriting prose.
+        const promoted = defaultTreeAdapter.createElement(
+            "link",
+            link.namespaceURI,
+            link.attrs.map((a) => ({ ...a })),
+        );
+        defaultTreeAdapter.detachNode(link);
+        defaultTreeAdapter.appendChild(head, promoted);
+    }
+    return links.length;
+}

package/src/internal/offscreen-layout.ts

@@ -0,0 +1,117 @@
+import type { ExpressiveCodePlugin } from "astro-expressive-code";
+import { parse as parseCss, walk as walkCss } from "css-tree";
+import type { DefaultTreeAdapterMap } from "parse5";
+
+interface AstNode {
+    type: string;
+    tagName?: string;
+    properties?: Record<string, unknown>;
+    children?: AstNode[];
+}
+
+function styleProperties(value: unknown): { text: string; names: Set<string> } | undefined {
+    if (value !== undefined && typeof value !== "string") return;
+    const text = value ?? "";
+    const names = new Set<string>();
+    try {
+        walkCss(parseCss(text, { context: "declarationList" }), {
+            visit: "Declaration",
+            enter(node) {
+                names.add(node.property.toLowerCase());
+            },
+        });
+    } catch {
+        return;
+    }
+    return { text, names };
+}
+
+const classes = (node: AstNode) => {
+    const value = node.properties?.className;
+    return Array.isArray(value) ? value.map(String) : String(value ?? "").split(/\s+/u);
+};
+
+/** Non-wrapping EC rows are exactly one inherited line-height each, including empty rows. */
+export function containCodeBlocks(node: AstNode): number {
+    let changed = 0;
+    if (node.type === "element" && node.tagName === "pre" && !classes(node).includes("wrap")) {
+        const code = node.children?.find(
+            (child) => child.type === "element" && child.tagName === "code",
+        );
+        const lines = code?.children ?? [];
+        if (
+            code &&
+            lines.length &&
+            lines.every((line) => line.type === "element" && classes(line).includes("ec-line"))
+        ) {
+            code.properties ??= {};
+            const properties = code.properties;
+            const style = styleProperties(properties.style);
+            if (
+                style &&
+                !style.names.has("content-visibility") &&
+                !style.names.has("contain-intrinsic-block-size") &&
+                !["height", "block-size", "min-height", "max-height"].some((name) =>
+                    style.names.has(name),
+                )
+            ) {
+                properties.style = `${style.text};content-visibility:auto;contain-intrinsic-block-size:auto calc(${lines.length} * 1lh)`;
+                properties["data-stalux-offscreen-code"] = "";
+                changed++;
+            }
+        }
+    }
+    for (const child of node.children ?? []) changed += containCodeBlocks(child);
+    return changed;
+}
+
+export function codeContainmentPlugin(): ExpressiveCodePlugin {
+    return {
+        name: "stalux-offscreen-code",
+        hooks: {
+            postprocessRenderedBlockGroup({ renderData }) {
+                containCodeBlocks(renderData.groupAst);
+            },
+        },
+    };
+}
+
+/** Mermaid SVGs have an exact viewBox ratio; skipping offscreen paint need not estimate their size. */
+export function containMermaidSvgs(document: DefaultTreeAdapterMap["document"]): number {
+    let changed = 0;
+    function visit(node: DefaultTreeAdapterMap["node"]) {
+        if ("tagName" in node) {
+            if (node.tagName === "template" || node.tagName === "noscript") return;
+            const attribute = (name: string) =>
+                node.attrs.find((a) => a.name.toLowerCase() === name);
+            if (node.tagName === "svg" && attribute("id")?.value.startsWith("satteri-mermaid-")) {
+                const box = attribute("viewbox")
+                    ?.value.trim()
+                    .split(/[\s,]+/u)
+                    .map(Number);
+                const style = styleProperties(attribute("style")?.value);
+                if (
+                    box?.length === 4 &&
+                    box.every(Number.isFinite) &&
+                    (box[2] ?? 0) > 0 &&
+                    (box[3] ?? 0) > 0 &&
+                    style &&
+                    !style.names.has("content-visibility")
+                ) {
+                    const ratio = style.names.has("aspect-ratio")
+                        ? ""
+                        : `;aspect-ratio:${box[2]}/${box[3]}`;
+                    const value = `${style.text};content-visibility:auto${ratio}`;
+                    const existing = attribute("style");
+                    if (existing) existing.value = value;
+                    else node.attrs.push({ name: "style", value });
+                    node.attrs.push({ name: "data-stalux-offscreen-svg", value: "" });
+                    changed++;
+                }
+            }
+        }
+        if ("childNodes" in node) for (const child of node.childNodes) visit(child);
+    }
+    visit(document);
+    return changed;
+}

package/src/internal/project-mode.ts

@@ -0,0 +1,7 @@
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+/** Linked consumers still need injected routes; only the theme's own root has file routes. */
+export function isPluginProject(projectRoot: URL, themeRoot: URL): boolean {
+    return realpathSync(fileURLToPath(projectRoot)) !== realpathSync(fileURLToPath(themeRoot));
+}

package/src/internal/search-style.ts

@@ -0,0 +1,29 @@
+import { createRequire } from "node:module";
+import type { Plugin } from "vite";
+
+const publicId = "virtual:stalux-search-style";
+const virtualId = `\0${publicId}`;
+
+/** Astro dev treats a direct CSS ?url import as a module script; keep it a URL-only leaf. */
+export function searchStylePlugin(development: boolean, base: string): Plugin {
+    const stylesheet = createRequire(import.meta.url)
+        .resolve("@pagefind/component-ui/css")
+        .replaceAll("\\", "/");
+    return {
+        name: "stalux:search-style",
+        configureServer(server) {
+            // A linked package can be outside the consumer's workspace root.
+            server.config.server.fs.allow.push(stylesheet);
+        },
+        async resolveId(id, importer) {
+            if (id !== publicId) return;
+            return development
+                ? virtualId
+                : this.resolve(`${stylesheet}?url`, importer, { skipSelf: true });
+        },
+        load(id) {
+            if (id !== virtualId) return;
+            return `export default ${JSON.stringify(`${base.replace(/\/$/, "")}/@fs${stylesheet}`)};`;
+        },
+    };
+}

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

@@ -336,19 +336,18 @@ export const styleNames: { classes: Record<string, string>; variables: Record<st
         "stalux-page-enter": "k6",
         "stalux-page-enter-back": "k7",
         "stalux-page-exit": "k8",
-        "stalux-post-content-reveal": "k9",
-        "stalux-random-spin": "ka",
-        "stalux-sidebar-left-back-in": "kb",
-        "stalux-sidebar-left-back-out": "kc",
-        "stalux-sidebar-left-in": "kd",
-        "stalux-sidebar-left-out": "ke",
-        "stalux-sidebar-right-back-in": "kf",
-        "stalux-sidebar-right-back-out": "kg",
-        "stalux-sidebar-right-in": "kh",
-        "stalux-sidebar-right-out": "ki",
-        "stalux-social-stalux-social-arrive": "kj",
-        "stalux-taxonomy-enter": "kk",
-        "stalux-taxonomy-enter-back": "kl",
-        "stalux-word-word-glow": "km"
+        "stalux-random-spin": "k9",
+        "stalux-sidebar-left-back-in": "ka",
+        "stalux-sidebar-left-back-out": "kb",
+        "stalux-sidebar-left-in": "kc",
+        "stalux-sidebar-left-out": "kd",
+        "stalux-sidebar-right-back-in": "ke",
+        "stalux-sidebar-right-back-out": "kf",
+        "stalux-sidebar-right-in": "kg",
+        "stalux-sidebar-right-out": "kh",
+        "stalux-social-stalux-social-arrive": "ki",
+        "stalux-taxonomy-enter": "kj",
+        "stalux-taxonomy-enter-back": "kk",
+        "stalux-word-word-glow": "kl"
     }
 };

package/src/internal/webmcp-mutations.ts

@@ -0,0 +1,37 @@
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+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 = createRequire(import.meta.url).resolve("@mcp-b/webmcp-polyfill");
+    const version = JSON.parse(
+        readFileSync(new URL("../package.json", pathToFileURL(entry)), "utf8"),
+    ).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 };
+        },
+    };
+}